diff options
Diffstat (limited to 'doc')
31 files changed, 721 insertions, 631 deletions
diff --git a/doc/analytics.markdown b/doc/analytics.markdown index 13657b56..d72fc383 100644 --- a/doc/analytics.markdown +++ b/doc/analytics.markdown @@ -62,9 +62,4 @@ This chart show the average lead and cycle time for the last 1000 tasks over tim Those metrics are calculated and recorded every day for the whole project. -Don't forget to run the daily job for statistics calculation -------------------------------------------------------- - -To generate accurate analytic data, you should run the daily cronjob **project daily statistics**. - -[Read the documentation of Kanboard CLI](cli.markdown) +Note: Don't forget to run the [daily cronjob](cronjob.markdown) to have accurate statistics. diff --git a/doc/api-board-procedures.markdown b/doc/api-board-procedures.markdown index d8503d6d..6f8a878e 100644 --- a/doc/api-board-procedures.markdown +++ b/doc/api-board-procedures.markdown @@ -156,261 +156,3 @@ Response example: ] } ``` - -## getColumns - -- Purpose: **Get all columns information for a given project** -- Parameters: - - **project_id** (integer, required) -- Result on success: **columns properties** -- Result on failure: **empty list** - -Request example: - -```json -{ - "jsonrpc": "2.0", - "method": "getColumns", - "id": 887036325, - "params": [ - 1 - ] -} -``` - -Response example: - -```json -{ - "jsonrpc": "2.0", - "id": 887036325, - "result": [ - { - "id": "1", - "title": "Backlog", - "position": "1", - "project_id": "1", - "task_limit": "0" - }, - { - "id": "2", - "title": "Ready", - "position": "2", - "project_id": "1", - "task_limit": "0" - }, - { - "id": "3", - "title": "Work in progress", - "position": "3", - "project_id": "1", - "task_limit": "0" - } - ] -} -``` - -## getColumn - -- Purpose: **Get a single column** -- Parameters: - - **column_id** (integer, required) -- Result on success: **column properties** -- Result on failure: **null** - -Request example: - -```json -{ - "jsonrpc": "2.0", - "method": "getColumn", - "id": 1242049935, - "params": [ - 2 - ] -} -``` - -Response example: - -```json -{ - "jsonrpc": "2.0", - "id": 1242049935, - "result": { - "id": "2", - "title": "Youpi", - "position": "2", - "project_id": "1", - "task_limit": "5" - } -} -``` - -## moveColumnUp - -- Purpose: **Move up the column position** -- Parameters: - - **project_id** (integer, required) - - **column_id** (integer, required) -- Result on success: **true** -- Result on failure: **false** - -Request example: - -```json -{ - "jsonrpc": "2.0", - "method": "moveColumnUp", - "id": 99275573, - "params": [ - 1, - 2 - ] -} -``` - -Response example: - -```json -{ - "jsonrpc": "2.0", - "id": 99275573, - "result": true -} -``` - -## moveColumnDown - -- Purpose: **Move down the column position** -- Parameters: - - **project_id** (integer, required) - - **column_id** (integer, required) -- Result on success: **true** -- Result on failure: **false** - -Request example: - -```json -{ - "jsonrpc": "2.0", - "method": "moveColumnDown", - "id": 957090649, - "params": { - "project_id": 1, - "column_id": 2 - } -} -``` - -Response example: - -```json -{ - "jsonrpc": "2.0", - "id": 957090649, - "result": true -} -``` - -## updateColumn - -- Purpose: **Update column properties** -- Parameters: - - **column_id** (integer, required) - - **title** (string, required) - - **task_limit** (integer, optional) - - **description** (string, optional) -- Result on success: **true** -- Result on failure: **false** - -Request example: - -```json -{ - "jsonrpc": "2.0", - "method": "updateColumn", - "id": 480740641, - "params": [ - 2, - "Boo", - 5 - ] -} -``` - -Response example: - -```json -{ - "jsonrpc": "2.0", - "id": 480740641, - "result": true -} -``` - -## addColumn - -- Purpose: **Add a new column** -- Parameters: - - **project_id** (integer, required) - - **title** (string, required) - - **task_limit** (integer, optional) - - **description** (string, optional) -- Result on success: **column_id** -- Result on failure: **false** - -Request example: - -```json -{ - "jsonrpc": "2.0", - "method": "addColumn", - "id": 638544704, - "params": [ - 1, - "Boo" - ] -} -``` - -Response example: - -```json -{ - "jsonrpc": "2.0", - "id": 638544704, - "result": 5 -} -``` - -## removeColumn - -- Purpose: **Remove a column** -- Parameters: - - **column_id** (integer, required) -- Result on success: **true** -- Result on failure: **false** - -Request example: - -```json -{ - "jsonrpc": "2.0", - "method": "removeColumn", - "id": 1433237746, - "params": [ - 1 - ] -} -``` - -Response example: - -```json -{ - "jsonrpc": "2.0", - "id": 1433237746, - "result": true -} -``` diff --git a/doc/api-column-procedures.markdown b/doc/api-column-procedures.markdown new file mode 100644 index 00000000..c5d2793b --- /dev/null +++ b/doc/api-column-procedures.markdown @@ -0,0 +1,229 @@ +API Column Procedures +===================== + +## getColumns + +- Purpose: **Get all columns information for a given project** +- Parameters: + - **project_id** (integer, required) +- Result on success: **columns properties** +- Result on failure: **empty list** + +Request example: + +```json +{ + "jsonrpc": "2.0", + "method": "getColumns", + "id": 887036325, + "params": [ + 1 + ] +} +``` + +Response example: + +```json +{ + "jsonrpc": "2.0", + "id": 887036325, + "result": [ + { + "id": "1", + "title": "Backlog", + "position": "1", + "project_id": "1", + "task_limit": "0" + }, + { + "id": "2", + "title": "Ready", + "position": "2", + "project_id": "1", + "task_limit": "0" + }, + { + "id": "3", + "title": "Work in progress", + "position": "3", + "project_id": "1", + "task_limit": "0" + } + ] +} +``` + +## getColumn + +- Purpose: **Get a single column** +- Parameters: + - **column_id** (integer, required) +- Result on success: **column properties** +- Result on failure: **null** + +Request example: + +```json +{ + "jsonrpc": "2.0", + "method": "getColumn", + "id": 1242049935, + "params": [ + 2 + ] +} +``` + +Response example: + +```json +{ + "jsonrpc": "2.0", + "id": 1242049935, + "result": { + "id": "2", + "title": "Youpi", + "position": "2", + "project_id": "1", + "task_limit": "5" + } +} +``` + +## changeColumnPosition + +- Purpose: **Change the column position** +- Parameters: + - **project_id** (integer, required) + - **column_id** (integer, required) + - **position** (integer, required, must be >= 1) +- Result on success: **true** +- Result on failure: **false** + +Request example: + +```json +{ + "jsonrpc": "2.0", + "method": "changeColumnPosition", + "id": 99275573, + "params": [ + 1, + 2, + 3 + ] +} +``` + +Response example: + +```json +{ + "jsonrpc": "2.0", + "id": 99275573, + "result": true +} +``` + +## updateColumn + +- Purpose: **Update column properties** +- Parameters: + - **column_id** (integer, required) + - **title** (string, required) + - **task_limit** (integer, optional) + - **description** (string, optional) +- Result on success: **true** +- Result on failure: **false** + +Request example: + +```json +{ + "jsonrpc": "2.0", + "method": "updateColumn", + "id": 480740641, + "params": [ + 2, + "Boo", + 5 + ] +} +``` + +Response example: + +```json +{ + "jsonrpc": "2.0", + "id": 480740641, + "result": true +} +``` + +## addColumn + +- Purpose: **Add a new column** +- Parameters: + - **project_id** (integer, required) + - **title** (string, required) + - **task_limit** (integer, optional) + - **description** (string, optional) +- Result on success: **column_id** +- Result on failure: **false** + +Request example: + +```json +{ + "jsonrpc": "2.0", + "method": "addColumn", + "id": 638544704, + "params": [ + 1, + "Boo" + ] +} +``` + +Response example: + +```json +{ + "jsonrpc": "2.0", + "id": 638544704, + "result": 5 +} +``` + +## removeColumn + +- Purpose: **Remove a column** +- Parameters: + - **column_id** (integer, required) +- Result on success: **true** +- Result on failure: **false** + +Request example: + +```json +{ + "jsonrpc": "2.0", + "method": "removeColumn", + "id": 1433237746, + "params": [ + 1 + ] +} +``` + +Response example: + +```json +{ + "jsonrpc": "2.0", + "id": 1433237746, + "result": true +} +``` diff --git a/doc/api-file-procedures.markdown b/doc/api-file-procedures.markdown index bd05ce6b..930be733 100644 --- a/doc/api-file-procedures.markdown +++ b/doc/api-file-procedures.markdown @@ -1,7 +1,7 @@ API File Procedures =================== -## createFile +## createTaskFile - Purpose: **Create and upload a new task attachment** - Parameters: @@ -18,7 +18,7 @@ Request example: ```json { "jsonrpc": "2.0", - "method": "createFile", + "method": "createTaskFile", "id": 94500810, "params": [ 1, @@ -39,7 +39,7 @@ Response example: } ``` -## getAllFiles +## getAllTaskFiles - Purpose: **Get all files attached to task** - Parameters: @@ -52,7 +52,7 @@ Request example: ```json { "jsonrpc": "2.0", - "method": "getAllFiles", + "method": "getAllTaskFiles", "id": 1880662820, "params": { "task_id": 1 @@ -83,7 +83,7 @@ Response example: } ``` -## getFile +## getTaskFile - Purpose: **Get file information** - Parameters: @@ -96,7 +96,7 @@ Request example: ```json { "jsonrpc": "2.0", - "method": "getFile", + "method": "getTaskFile", "id": 318676852, "params": [ "1" @@ -123,7 +123,7 @@ Response example: } ``` -## downloadFile +## downloadTaskFile - Purpose: **Download file contents (encoded in base64)** - Parameters: @@ -136,7 +136,7 @@ Request example: ```json { "jsonrpc": "2.0", - "method": "downloadFile", + "method": "downloadTaskFile", "id": 235943344, "params": [ "1" @@ -154,7 +154,7 @@ Response example: } ``` -## removeFile +## removeTaskFile - Purpose: **Remove file** - Parameters: @@ -167,7 +167,7 @@ Request example: ```json { "jsonrpc": "2.0", - "method": "removeFile", + "method": "removeTaskFile", "id": 447036524, "params": [ "1" @@ -185,7 +185,7 @@ Response example: } ``` -## removeAllFiles +## removeAllTaskFiles - Purpose: **Remove all files associated to a task** - Parameters: @@ -198,7 +198,7 @@ Request example: ```json { "jsonrpc": "2.0", - "method": "removeAllFiles", + "method": "removeAllTaskFiles", "id": 593312993, "params": { "task_id": 1 diff --git a/doc/api-json-rpc.markdown b/doc/api-json-rpc.markdown index 34559df5..bb14b008 100644 --- a/doc/api-json-rpc.markdown +++ b/doc/api-json-rpc.markdown @@ -52,6 +52,7 @@ Usage - [Projects](api-project-procedures.markdown) - [Project Permissions](api-project-permission-procedures.markdown) - [Boards](api-board-procedures.markdown) +- [Columns](api-column-procedures.markdown) - [Swimlanes](api-swimlane-procedures.markdown) - [Categories](api-category-procedures.markdown) - [Automatic Actions](api-action-procedures.markdown) diff --git a/doc/api-swimlane-procedures.markdown b/doc/api-swimlane-procedures.markdown index ab288c0c..c58e56c9 100644 --- a/doc/api-swimlane-procedures.markdown +++ b/doc/api-swimlane-procedures.markdown @@ -235,12 +235,13 @@ Response example: } ``` -## moveSwimlaneUp +## changeSwimlanePosition -- Purpose: **Move up the swimlane position** +- Purpose: **Move up the swimlane position** (only for active swimlanes) - Parameters: - **project_id** (integer, required) - **swimlane_id** (integer, required) + - **position** (integer, required, must be >= 1) - Result on success: **true** - Result on failure: **false** @@ -249,11 +250,12 @@ Request example: ```json { "jsonrpc": "2.0", - "method": "moveSwimlaneUp", + "method": "changeSwimlanePosition", "id": 99275573, "params": [ 1, - 2 + 2, + 3 ] } ``` @@ -268,39 +270,6 @@ Response example: } ``` -## moveSwimlaneDown - -- Purpose: **Move down the swimlane position** -- Parameters: - - **project_id** (integer, required) - - **swimlane_id** (integer, required) -- Result on success: **true** -- Result on failure: **false** - -Request example: - -```json -{ - "jsonrpc": "2.0", - "method": "moveSwimlaneDown", - "id": 957090649, - "params": { - "project_id": 1, - "swimlane_id": 2 - } -} -``` - -Response example: - -```json -{ - "jsonrpc": "2.0", - "id": 957090649, - "result": true -} -``` - ## updateSwimlane - Purpose: **Update swimlane properties** diff --git a/doc/api-user-procedures.markdown b/doc/api-user-procedures.markdown index 6ecf12c6..6c09355d 100644 --- a/doc/api-user-procedures.markdown +++ b/doc/api-user-procedures.markdown @@ -113,6 +113,48 @@ Response example: } ``` +## getUserByName + +- Purpose: **Get user information** +- Parameters: + - **username** (string, required) +- Result on success: **user properties** +- Result on failure: **null** + +Request example: + +```json +{ + "jsonrpc": "2.0", + "method": "getUserByName", + "id": 1769674782, + "params": { + "username": "biloute" + } +} +``` + +Response example: + +```json +{ + "jsonrpc": "2.0", + "id": 1769674782, + "result": { + "id": "1", + "username": "biloute", + "password": "$2y$10$dRs6pPoBu935RpmsrhmbjevJH5MgZ7Kr9QrnVINwwyZ3.MOwqg.0m", + "role": "app-user", + "is_ldap_user": "0", + "name": "", + "email": "", + "google_id": null, + "github_id": null, + "notifications_enabled": "0" + } +} +``` + ## getAllUsers - Purpose: **Get all available users** @@ -220,3 +262,96 @@ Response example: "result": true } ``` + +## disableUser + +- Purpose: **Disable a user** +- Parameters: + - **user_id** (integer, required) +- Result on success: **true** +- Result on failure: **false** + +Request example: + +```json +{ + "jsonrpc": "2.0", + "method": "disableUser", + "id": 2094191872, + "params": { + "user_id": 1 + } +} +``` + +Response example: + +```json +{ + "jsonrpc": "2.0", + "id": 2094191872, + "result": true +} +``` + +## enableUser + +- Purpose: **Enable a user** +- Parameters: + - **user_id** (integer, required) +- Result on success: **true** +- Result on failure: **false** + +Request example: + +```json +{ + "jsonrpc": "2.0", + "method": "enableUser", + "id": 2094191872, + "params": { + "user_id": 1 + } +} +``` + +Response example: + +```json +{ + "jsonrpc": "2.0", + "id": 2094191872, + "result": true +} +``` + +## isActiveUser + +- Purpose: **Check if a user is active** +- Parameters: + - **user_id** (integer, required) +- Result on success: **true** +- Result on failure: **false** + +Request example: + +```json +{ + "jsonrpc": "2.0", + "method": "isActiveUser", + "id": 2094191872, + "params": { + "user_id": 1 + } +} +``` + +Response example: + +```json +{ + "jsonrpc": "2.0", + "id": 2094191872, + "result": true +} +``` diff --git a/doc/centos-installation.markdown b/doc/centos-installation.markdown index d0fd6a00..576119b4 100644 --- a/doc/centos-installation.markdown +++ b/doc/centos-installation.markdown @@ -1,6 +1,8 @@ Centos Installation =================== +Note: Some features of Kanboard require that you run [a daily background job](cronjob.markdown). + Centos 7 -------- diff --git a/doc/cli.markdown b/doc/cli.markdown index bcb478dd..9334d84b 100644 --- a/doc/cli.markdown +++ b/doc/cli.markdown @@ -4,7 +4,7 @@ Command Line Interface Kanboard provides a simple command line interface that can be used from any Unix terminal. This tool can be used only on the local machine. -This feature is useful to run commands outside the web server process by example running a huge report. +This feature is useful to run commands outside of the web server processes. Usage ----- @@ -28,6 +28,7 @@ Options: -v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug Available commands: + cronjob Execute daily cronjob help Displays help for a command list Lists commands export @@ -42,6 +43,8 @@ Available commands: notification:overdue-tasks Send notifications for overdue tasks projects projects:daily-stats Calculate daily statistics for all projects + trigger + trigger:tasks Trigger scheduler event for all tasks ``` Available commands @@ -116,7 +119,7 @@ Emails will be sent to all users with notifications enabled. You can also display the overdue tasks with the flag `--show`: ```bash -$ ./kanboard notification:overdue-tasks --show +./kanboard notification:overdue-tasks --show +-----+---------+------------+------------+--------------+----------+ | Id | Title | Due date | Project Id | Project name | Assignee | +-----+---------+------------+------------+--------------+----------+ @@ -125,20 +128,22 @@ $ ./kanboard notification:overdue-tasks --show +-----+---------+------------+------------+--------------+----------+ ``` -Cronjob example: - -```bash -# Everyday at 8am we check for due tasks -0 8 * * * cd /path/to/kanboard && ./kanboard notification:overdue-tasks >/dev/null 2>&1 -``` - ### Run daily project stats calculation -You can add a background task to calculate the project statistics every day: +This command calculate the statistics of each project: ```bash -$ ./kanboard projects:daily-stats +./kanboard projects:daily-stats Run calculation for Project #0 Run calculation for Project #1 Run calculation for Project #10 ``` + +### Trigger for tasks + +This command send a "daily cronjob event" to all open tasks of each project. + +```bash +./kanboard trigger:tasks +Trigger task event: project_id=2, nb_tasks=1 +``` diff --git a/doc/config.markdown b/doc/config.markdown index 393efbae..150cb6dc 100644 --- a/doc/config.markdown +++ b/doc/config.markdown @@ -174,34 +174,6 @@ define('LDAP_GROUP_FILTER', ''); define('LDAP_GROUP_ATTRIBUTE_NAME', 'cn'); ``` -Google Authentication settings ------------------------------- - -```php -// Enable/disable Google authentication -define('GOOGLE_AUTH', false); - -// Google client id (Get this value from the Google developer console) -define('GOOGLE_CLIENT_ID', ''); - -// Google client secret key (Get this value from the Google developer console) -define('GOOGLE_CLIENT_SECRET', ''); -``` - -Github Authentication settings ------------------------------- - -```php -// Enable/disable GitHub authentication -define('GITHUB_AUTH', false); - -// GitHub client id (Copy it from your settings -> Applications -> Developer applications) -define('GITHUB_CLIENT_ID', ''); - -// GitHub client secret key (Copy it from your settings -> Applications -> Developer applications) -define('GITHUB_CLIENT_SECRET', ''); -``` - Reverse-Proxy Authentication settings ------------------------------------- @@ -295,6 +267,9 @@ define('API_AUTHENTICATION_HEADER', ''); // Hide login form, useful if all your users use Google/Github/ReverseProxy authentication define('HIDE_LOGIN_FORM', false); +// Disabling logout (for external SSO authentication) +define('DISABLE_LOGOUT', false); + // Override API token stored in the database, useful for automated tests define('API_AUTHENTICATION_TOKEN', 'My unique API Token'); ``` diff --git a/doc/cronjob.markdown b/doc/cronjob.markdown new file mode 100644 index 00000000..32f12888 --- /dev/null +++ b/doc/cronjob.markdown @@ -0,0 +1,32 @@ +Background Job Scheduling +========================= + +To work properly, Kanboard requires that a background job run on a daily basis. +Usually on Unix platforms, this process is done by `cron`. + +This background job is necessary for these features: + +- Reports and analytics (calculate daily stats of each projects) +- Send overdue task notifications +- Execute automatic actions connected to the event "Daily background job for tasks" + +Configuration on Unix and Linux platforms +----------------------------------------- + +There are multiple ways to define a cronjob on Unix/Linux operating systems, this example is for Ubuntu 14.04. +The procedure is similar to other systems. + +Edit the crontab of your web server user: + +```bash +sudo crontab -u www-data -e +``` + +Example to execute the daily cronjob at 8am: + +```bash +0 8 * * * cd /path/to/kanboard && ./kanboard cronjob >/dev/null 2>&1 +``` + +Note: the cronjob process must have write access to the database in case you are using Sqlite. +Usually, running the cronjob under the web server user is enough. diff --git a/doc/debian-installation.markdown b/doc/debian-installation.markdown index 147fe452..ec956049 100644 --- a/doc/debian-installation.markdown +++ b/doc/debian-installation.markdown @@ -1,6 +1,8 @@ How to install Kanboard on Debian? ================================== +Note: Some features of Kanboard require that you run [a daily background job](cronjob.markdown). + Debian 8 (Jessie) ----------------- diff --git a/doc/docker.markdown b/doc/docker.markdown index fe72a6c8..3f13e954 100644 --- a/doc/docker.markdown +++ b/doc/docker.markdown @@ -2,7 +2,18 @@ How to run Kanboard with Docker? ================================ Kanboard can run easily with [Docker](https://www.docker.com). -There is a `Dockerfile` in the repository to build your own container. + +The image size is approximately **50MB** and contains: + +- [Alpine Linux](http://alpinelinux.org/) +- The [process manager S6](http://skarnet.org/software/s6/) +- Nginx +- PHP-FPM + +The Kanboard cronjob is also running everyday at midnight. +URL rewriting is enabled in the included config file. + +When the container is running, the memory utilization is around **20MB**. Use the stable version ---------------------- @@ -17,7 +28,7 @@ docker run -d --name kanboard -p 80:80 -t kanboard/kanboard:stable Use the development version (automated build) --------------------------------------------- -Every new commit on the repository trigger a new build on [Docker Hub](https://registry.hub.docker.com/u/kanboard/kanboard/). +Every new commit on the repository trigger a new build on the [Docker Hub](https://registry.hub.docker.com/u/kanboard/kanboard/). ```bash docker pull kanboard/kanboard @@ -29,31 +40,57 @@ The tag **latest** is the **development version** of Kanboard, use at your own r Build your own Docker image --------------------------- +There is a `Dockerfile` in the Kanboard repository to build your own image. Clone the Kanboard repository and run the following command: ```bash docker build -t youruser/kanboard:master . ``` -To run your image in background on the port 80: +or ```bash -docker run -d --name kanboard -p 80:80 -t youruser/kanboard:master +make docker-image ``` -Store your data on a volume ---------------------------- - -By default Kanboard will store attachments and the Sqlite database in the directory data. Run this command to use a custom volume path: +To run your container in background on the port 80: ```bash -docker run -d --name kanboard -v /your/local/data/folder:/var/www/html/data -p 80:80 -t kanboard/kanboard:master +docker run -d --name kanboard -p 80:80 -t youruser/kanboard:master ``` +Volumes +------- + +You can attach 2 volumes to your container: + +- Data folder: `/var/www/kanboard/data` +- Plugins folder: `/var/www/kanboard/plugins` + +Use the flag `-v` to mount a volume on the host machine like described in [official Docker documentation](https://docs.docker.com/engine/userguide/containers/dockervolumes/). + +Upgrade your container +---------------------- + +- Pull the new image +- Remove the old container +- Restart a new container with the same volumes + +Environment variables +--------------------- + +The list of environment variables is available on [this page](env.markdown). + +Config files +------------ + +- The container already include a custom config file located at `/var/www/kanboard/config.php`. +- You can store your own config file on the data volume: `/var/www/kanboard/data/config.php`. + References ---------- - [Official Kanboard images](https://registry.hub.docker.com/u/kanboard/kanboard/) - [Docker documentation](https://docs.docker.com/) -- [Dockerfile stable version](https://github.com/kanboard/docker/blob/master/Dockerfile) +- [Dockerfile stable version](https://github.com/kanboard/docker) - [Dockerfile dev version](https://github.com/fguillot/kanboard/blob/master/Dockerfile) diff --git a/doc/env.markdown b/doc/env.markdown new file mode 100644 index 00000000..a01d0a6f --- /dev/null +++ b/doc/env.markdown @@ -0,0 +1,11 @@ +Environment Variables +===================== + +Environment variables maybe useful when Kanboard is deployed as container (Docker). + +| Variable | Description | +|---------------|---------------------------------------------------------------------------------------------------------------------------------| +| DATABASE_URL | `[database type]://[username]:[password]@[host]:[port]/[database name]`, example: `postgres://foo:foo@myserver:5432/kanboard` | +| DEBUG | Enable/Disable debug mode | +| DEBUG_FILE | Debug file location, `DEBUG_FILE=php://stderr` | +| ENABLE_SYSLOG | Enable/Disable logging to Syslog: `ENABLE_SYSLOG=1` | diff --git a/doc/freebsd-installation.markdown b/doc/freebsd-installation.markdown index 84b35ad8..7b36dff1 100644 --- a/doc/freebsd-installation.markdown +++ b/doc/freebsd-installation.markdown @@ -55,7 +55,7 @@ Generally 3 elements have to be installed: Fetch and extract ports... ```bash -$ portsnap fetch +$ portsnap fetch $ portsnap extract ``` @@ -122,6 +122,7 @@ there is no need to install it manually. Please note ----------- -Port is being hosted on [bitbucket](https://bitbucket.org/if0/freebsd-kanboard/). Feel free to comment, +- Port is being hosted on [bitbucket](https://bitbucket.org/if0/freebsd-kanboard/). Feel free to comment, fork and suggest updates! -
\ No newline at end of file +- Some features of Kanboard require that you run [a daily background job](cronjob.markdown). + diff --git a/doc/github-authentication.markdown b/doc/github-authentication.markdown deleted file mode 100644 index ba0f371f..00000000 --- a/doc/github-authentication.markdown +++ /dev/null @@ -1,80 +0,0 @@ -Github Authentication -===================== - -Requirements ------------- - -OAuth Github API credentials (available in your [Settings > Applications > Developer applications](https://github.com/settings/applications)) - -How does this work? -------------------- - -The Github authentication in Kanboard uses the [OAuth 2.0](http://oauth.net/2/) protocol, so any user of Kanboard can be linked to a Github account. - -That means you can use your Github account to login on Kanboard. - -How to link a Github account ----------------------------- - -1. Go to your user profile -2. Click on **External accounts** -3. Click on the link **Link my Github Account** -4. You are redirected to the **Github Authorize application form** -5. Authorize Kanboard by clicking on the button **Accept** -6. Your account is now linked - -Now, on the login page you can be authenticated in one click with the link **Login with my Github Account**. - -Your name and email are automatically updated from your Github Account if defined. - -Installation instructions -------------------------- - -### Setting up OAuth 2.0 - -- On Github, go to the page [Register a new OAuth application](https://github.com/settings/applications/new) -- Just follow the [official Github documentation](https://developer.github.com/guides/basics-of-authentication/#registering-your-app) -- In Kanboard, you can get the **callback url** in **Settings > Integrations > Github Authentication** - -### Setting up Kanboard - -Either create a new `config.php` file or rename the `config.default.php` file and set the following values: - -```php -// Enable/disable Github authentication -define('GITHUB_AUTH', true); - -// Github client id (Copy it from your settings -> Applications -> Developer applications) -define('GITHUB_CLIENT_ID', 'YOUR_GITHUB_CLIENT_ID'); - -// Github client secret key (Copy it from your settings -> Applications -> Developer applications) -define('GITHUB_CLIENT_SECRET', 'YOUR_GITHUB_CLIENT_SECRET'); -``` - -### Github Entreprise - -To use this authentication method with Github Enterprise you have to change the default urls. - -Replace these values by your self-hosted instance of Github: - -```php -// Github oauth2 authorize url -define('GITHUB_OAUTH_AUTHORIZE_URL', 'https://github.com/login/oauth/authorize'); - -// Github oauth2 token url -define('GITHUB_OAUTH_TOKEN_URL', 'https://github.com/login/oauth/access_token'); - -// Github API url (don't forget the slash at the end) -define('GITHUB_API_URL', 'https://api.github.com/'); -``` - -Notes ------ - -Kanboard uses these information from your public Github profile: - -- Full name -- Public email address -- Github unique id - -The Github unique id is used to link the local user account and the Github account. diff --git a/doc/gitlab-authentication.markdown b/doc/gitlab-authentication.markdown deleted file mode 100644 index 8d2f0000..00000000 --- a/doc/gitlab-authentication.markdown +++ /dev/null @@ -1,83 +0,0 @@ -Gitlab Authentication -===================== - -Requirements ------------- - -- Account on [Gitlab.com](https://gitlab.com) or you own self-hosted Gitlab instance -- Have Kanboard registered as application in Gitlab - -How does this work? -------------------- - -The Gitlab authentication in Kanboard uses the [OAuth 2.0](http://oauth.net/2/) protocol, so any user of Kanboard can be linked to a Gitlab account. - -That means you can use your Gitlab account to login on Kanboard. - -How to link a Gitlab account ----------------------------- - -1. Go to your user profile -2. Click on **External accounts** -3. Click on the link **Link my Gitlab Account** -4. You are redirected to the **Gitlab authorization form** -5. Authorize Kanboard by clicking on the button **Accept** -6. Your account is now linked - -Now, on the login page you can be authenticated in one click with the link **Login with my Gitlab Account**. - -Your name and email are automatically updated from your Gitlab Account if defined. - -Installation instructions -------------------------- - -### Setting up OAuth 2.0 - -- On Gitlab, register a new application by following the [official documentation](http://doc.gitlab.com/ce/integration/oauth_provider.html) -- In Kanboard, you can get the **callback url** in **Settings > Integrations > Gitlab Authentication**, just copy and paste the url - -### Setting up Kanboard - -Either create a new `config.php` file or rename the `config.default.php` file and set the following values: - -```php -// Enable/disable Gitlab authentication -define('GITLAB_AUTH', true); - -// Gitlab application id -define('GITLAB_CLIENT_ID', 'YOUR_APPLICATION_ID'); - -// Gitlab application secret -define('GITLAB_CLIENT_SECRET', 'YOUR_APPLICATION_SECRET'); -``` - -### Custom endpoints for self-hosted Gitlab - -Change these default values if you use a self-hosted instance of Gitlab: - -```php -// Gitlab oauth2 authorize url -define('GITLAB_OAUTH_AUTHORIZE_URL', 'https://gitlab.com/oauth/authorize'); - -// Gitlab oauth2 token url -define('GITLAB_OAUTH_TOKEN_URL', 'https://gitlab.com/oauth/token'); - -// Gitlab API url endpoint (don't forget the slash at the end) -define('GITLAB_API_URL', 'https://gitlab.com/api/v3/'); -``` - -Notes ------ - -Kanboard uses these information from your Gitlab profile: - -- Full name -- Email address -- Gitlab unique id - -The Gitlab unique id is used to link the local user account and the Gitlab account. - -Known issues ------------- - -Gitlab OAuth will work only with url rewrite enabled. At the moment, Gitlab doesn't support callback url with query string parameters. See [Gitlab issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/2443) diff --git a/doc/google-authentication.markdown b/doc/google-authentication.markdown deleted file mode 100644 index 0f4f3ec1..00000000 --- a/doc/google-authentication.markdown +++ /dev/null @@ -1,64 +0,0 @@ -Google Authentication -===================== - -Requirements ------------- - -OAuth Google API credentials (available in the Google Developer Console) - -How does this work? -------------------- - -- The Google authentication in Kanboard use the OAuth 2.0 protocol -- Any user account in Kanboard can be linked to a Google Account -- When a Kanboard user account is linked to Google, you can login with one click - -Procedure to link a Google Account ----------------------------------- - -1. Go to your user profile -2. Click on **External accounts** -3. Click on the link **Link my Google Account** -4. You are redirected to the **Google Consent screen** -5. Authorize Kanboard by clicking on the button **Accept** -6. Your account is now linked - -Now, on the login page you can be authenticated in one click with the link **Login with my Google Account**. - -Your name and email are automatically updated from your Google Account. - -Installation instructions -------------------------- - -### Setting up OAuth 2.0 in Google Developer Console - -- Follow the [official Google documentation](https://developers.google.com/accounts/docs/OAuth2Login#appsetup) to create a new application -- In Kanboard, you can get the **redirect url** in **Settings > Integrations > Google Authentication** - -### Setting up Kanboad - -Create a custom `config.php` file or copy the `config.default.php` file: - -```php -<?php - -// Enable/disable Google authentication -define('GOOGLE_AUTH', true); // Set this value to true - -// Google client id (Get this value from the Google developer console) -define('GOOGLE_CLIENT_ID', 'YOUR_CLIENT_ID'); - -// Google client secret key (Get this value from the Google developer console) -define('GOOGLE_CLIENT_SECRET', 'YOUR_CLIENT_SECRET'); -``` - -Notes ------ - -Kanboard use these information from your Google profile: - -- Full name -- Email address -- Google unique id - -The Google unique id is used to link together the local user account and the Google account. diff --git a/doc/heroku.markdown b/doc/heroku.markdown index 56d79bc9..f145f70e 100644 --- a/doc/heroku.markdown +++ b/doc/heroku.markdown @@ -35,5 +35,5 @@ heroku open Limitations ----------- -The storage of Heroku is ephemeral, that means uploaded files through Kanboard are not persistent after a reboot. -We may want to install a plugin to store your files in a cloud storage provider like [Amazon S3](https://github.com/kanboard/plugin-s3). +- The storage of Heroku is ephemeral, that means uploaded files through Kanboard are not persistent after a reboot. You may want to install a plugin to store your files in a cloud storage provider like [Amazon S3](https://github.com/kanboard/plugin-s3). +- Some features of Kanboard require that you run [a daily background job](cronjob.markdown). diff --git a/doc/index.markdown b/doc/index.markdown index 1e95fe06..7a3ca8e5 100644 --- a/doc/index.markdown +++ b/doc/index.markdown @@ -93,6 +93,7 @@ Technical details - [Installation on Ubuntu](ubuntu-installation.markdown) - [Installation on Debian](debian-installation.markdown) - [Installation on Centos](centos-installation.markdown) +- [Installation on OpenSuse](suse-installation.markdown) - [Installation on FreeBSD](freebsd-installation.markdown) - [Installation on Windows Server with IIS](windows-iis-installation.markdown) - [Installation on Windows Server with Apache](windows-apache-installation.markdown) @@ -102,7 +103,9 @@ Technical details ### Configuration +- [Daily background job](cronjob.markdown) - [Config file](config.markdown) +- [Environment variables](env.markdown) - [Email configuration](email-configuration.markdown) - [URL rewriting](nice-urls.markdown) @@ -117,9 +120,6 @@ Technical details - [LDAP authentication](ldap-authentication.markdown) - [LDAP group synchronization](ldap-group-sync.markdown) - [LDAP parameters](ldap-parameters.markdown) -- [Google authentication](google-authentication.markdown) -- [Github authentication](github-authentication.markdown) -- [Gitlab authentication](gitlab-authentication.markdown) - [Reverse proxy authentication](reverse-proxy-authentication.markdown) ### Contributors diff --git a/doc/installation.markdown b/doc/installation.markdown index b208be8a..dd4283f8 100644 --- a/doc/installation.markdown +++ b/doc/installation.markdown @@ -39,3 +39,8 @@ Security - Don't forget to change the default user/password - Don't allow everybody to access to the directory `data` from the URL. There is already a `.htaccess` for Apache but nothing for Nginx. + +Notes +----- + +- Some features of Kanboard require that you run [a daily background job](cronjob.markdown) diff --git a/doc/keyboard-shortcuts.markdown b/doc/keyboard-shortcuts.markdown index 8c809b77..beb15d3d 100644 --- a/doc/keyboard-shortcuts.markdown +++ b/doc/keyboard-shortcuts.markdown @@ -6,6 +6,7 @@ Keyboard shortcuts availability depends of the page you are presently. Project views (Board, Calendar, List, Gantt) -------------------------------------------- +- Switch to the project overview = **v o** - Switch to the board view = **v b** (press on **v** then **b**) - Switch to the calendar view = **v c** - Switch to the list view = **v l** @@ -25,4 +26,4 @@ Application - Go to the search box = **f** - Reset the search box = **r** - Close dialog box = **ESC** -- Submit form = **CTRL+ENTER** or **⌘+ENTER**
\ No newline at end of file +- Submit form = **CTRL+ENTER** or **⌘+ENTER** diff --git a/doc/plugin-external-link.markdown b/doc/plugin-external-link.markdown new file mode 100644 index 00000000..36252aff --- /dev/null +++ b/doc/plugin-external-link.markdown @@ -0,0 +1,78 @@ +External Link Providers +======================= + +This functionality allows you to link a task to additional items stored on another system. + +For example, you can link a task to: + +- Traditional web page +- Attachment (PDF documents stored on the web, archive...) +- Any ticketing system (bug tracker, customer support ticket...) + +Each item has a type, a URL, a dependency type and a title. + +By default, Kanboard includes two kinds of providers: + +- Web Link: You copy and paste a link and Kanboard will fetch the page title automatically +- Attachment: Link to anything that is not a web page + +Workflow +-------- + +1. The end-user copy and paste the URL to the form and submit +2. If the link type is "auto", Kanboard will loop through all providers registered until there is a match +3. Then, the link provider returns a object that implements the interface `ExternalLinkInterface` +4. A form is shown to the user with all pre-filled data before to save the link + +Interfaces +---------- + +To implement a new link provider from a plugin, you need to create 2 classes that implement those interfaces: + +- `Kanboard\Core\ExternalLink\ExternalLinkProviderInterface` +- `Kanboard\Core\ExternalLink\ExternalLinkInterface` + +### ExternalLinkProviderInterface + +| Method | Usage | +|----------------------------|-----------------------------------------------------------------| +| `getName()` | Get provider name (label) | +| `getType()` | Get link type (will be saved in the database) | +| `getDependencies()` | Get a dictionary of supported dependency types by the provider | +| `setUserTextInput($input)` | Set text entered by the user | +| `match()` | Return true if the provider can parse correctly the user input | +| `getLink()` | Get the link found with the properties | + +### ExternalLinkInterface + +| Method | Usage | +|-------------------|------------------| +| `getTitle()` | Get link title | +| `getUrl()` | Get link URL | +| `setUrl($url)` | Set link URL | + +Register a new link provider +---------------------------- + +In your `Plugin.php`, just call the method `register()` from the object `ExternalLinkManager`: + +```php +<?php + +namespace Kanboard\Plugin\MyExternalLink; + +use Kanboard\Core\Plugin\Base; + +class Plugin extends Base +{ + public function initialize() + { + $this->externalLinkManager->register(new MyLinkProvider()); + } +} +``` + +Examples +-------- + +- Kanboard includes the default providers "WebLink" and "Attachment" diff --git a/doc/plugin-helpers.markdown b/doc/plugin-helpers.markdown new file mode 100644 index 00000000..8cc6b42a --- /dev/null +++ b/doc/plugin-helpers.markdown @@ -0,0 +1,40 @@ +Registering new helpers +======================= + +Helper skeleton: + +```php +<?php + +namespace Kanboard\Plugin\MyPlugin\Helper\MyHelper; + +use Kanboard\Core\Base; + +class MyHelper extends Base +{ + public function doSomething() + { + return 'foobar'; + } +} +``` + +Register your helper class: + +```php +$this->helper->register('myHelper', '\Kanboard\Plugin\MyPlugin\Helper\MyHelper'); +``` + +Using your helper from a template: + +```php +<p> + <?= $this->myHelper->doSomething() ?> +</p> +``` + +Using your helper from another class: + +```php +$this->helper->myHelper->doSomething(); +``` diff --git a/doc/plugin-hooks.markdown b/doc/plugin-hooks.markdown index 6e9718d9..c1b3e577 100644 --- a/doc/plugin-hooks.markdown +++ b/doc/plugin-hooks.markdown @@ -58,8 +58,28 @@ class Plugin extends Base } ``` +Example to override default values for task forms: + +```php +class Plugin extends Base +{ + public function initialize() + { + $this->hook->on('controller:task:form:default', function (array $default_values) { + return empty($default_values['score']) ? array('score' => 4) : array(); + }); + } +} +``` + List of merging hooks: +#### controller:task:form:default + +- Override default values for task forms +- Arguments: + - `$default_values`: actual default values (array) + #### controller:calendar:project:events - Add more events to the project calendar @@ -131,26 +151,45 @@ Template names without prefix are core templates. List of template hooks: -- `template:auth:login-form:before` -- `template:auth:login-form:after` -- `template:dashboard:sidebar` -- `template:config:sidebar` -- `template:config:integrations` -- `template:project:integrations` -- `template:user:integrations` -- `template:export:sidebar` -- `template:layout:head` -- `template:layout:top` -- `template:layout:bottom` -- `template:project:dropdown`: "Actions" menu on left in different project views -- `template:project:header:before` -- `template:project:header:after` -- `template:project-user:sidebar` -- `template:task:sidebar:information` -- `template:task:sidebar:actions` -- `template:user:sidebar:information` -- `template:user:sidebar:actions` -- `template:app:filters-helper:before` -- `template:app:filters-helper:after` +| Hook | Description | +|------------------------------------------|----------------------------------------------------| +| `template:analytic:sidebar` | Sidebar on analytic pages | +| `template:app:filters-helper:before` | Filter helper dropdown (top) | +| `template:app:filters-helper:after` | Filter helper dropdown (bottom) | +| `template:auth:login-form:before` | Login page (top) | +| `template:auth:login-form:after` | Login page (bottom) | +| `template:config:sidebar` | Sidebar on settings page | +| `template:config:application ` | Application settings form | +| `template:config:integrations` | Integration page in global settings | +| `template:dashboard:sidebar` | Sidebar on dashboard page | +| `template:export:sidebar` | Sidebar on export pages | +| `template:layout:head` | Page layout `<head/>` tag | +| `template:layout:top` | Page layout top header | +| `template:layout:bottom` | Page layout footer | +| `template:project:dropdown` | "Actions" menu on left in different project views | +| `template:project:header:before` | Project filters (before) | +| `template:project:header:after` | Project filters (after) | +| `template:project:integrations` | Integration page in projects settings | +| `template:project:sidebar` | Sidebar in project settings | +| `template:project-user:sidebar` | Sidebar on project user overview page | +| `template:task:menu` | "Actions" menu on left in different task views | +| `template:task:dropdown` | Task dropdown menu in listing pages | +| `template:task:sidebar` | Sidebar on task page | +| `template:task:form:right-column` | Right column in task form | +| `template:task:show:top ` | Show task page: top | +| `template:task:show:bottom` | Show task page: bottom | +| `template:task:show:before-description` | Show task page: before description | +| `template:task:show:before-tasklinks` | Show task page: before tasklinks | +| `template:task:show:before-subtasks` | Show task page: before subtasks | +| `template:task:show:before-timetracking` | Show task page: before timetracking | +| `template:task:show:before-attachements` | Show task page: before attachments | +| `template:task:show:before-comments` | Show task page: before comments | +| `template:user:authentication:form` | "Edit authentication" form in user profile | +| `template:user:create-remote:form` | "Create remote user" form | +| `template:user:external` | "External authentication" page in user profile | +| `template:user:integrations` | Integration page in user profile | +| `template:user:sidebar:actions` | Sidebar in user profile (section actions) | +| `template:user:sidebar:information` | Sidebar in user profile (section information) | + Another template hooks can be added if necessary, just ask on the issue tracker. diff --git a/doc/plugins.markdown b/doc/plugins.markdown index f3f922f3..e38c887f 100644 --- a/doc/plugins.markdown +++ b/doc/plugins.markdown @@ -13,6 +13,7 @@ Plugin creators should specify explicitly the compatible versions of Kanboard. I - [Override default application behaviors](plugin-overrides.markdown) - [Add schema migrations for plugins](plugin-schema-migrations.markdown) - [Custom routes](plugin-routes.markdown) +- [Add helpers](plugin-helpers.markdown) - [Add mail transports](plugin-mail-transports.markdown) - [Add notification types](plugin-notifications.markdown) - [Add automatic actions](plugin-automatic-actions.markdown) @@ -21,6 +22,7 @@ Plugin creators should specify explicitly the compatible versions of Kanboard. I - [Authentication plugin registration](plugin-authentication.markdown) - [Authorization Architecture](plugin-authorization-architecture.markdown) - [Custom Group Providers](plugin-group-provider.markdown) +- [External Link Providers](plugin-external-link.markdown) - [LDAP client](plugin-ldap-client.markdown) Examples of plugins diff --git a/doc/suse-installation.markdown b/doc/suse-installation.markdown new file mode 100644 index 00000000..ce36c8f7 --- /dev/null +++ b/doc/suse-installation.markdown @@ -0,0 +1,14 @@ +Installation on OpenSuse +======================== + +OpenSuse Leap 42.1 +------------------ + +```bash +sudo zypper install php5 php5-sqlite php5-gd php5-json php5-mcrypt php5-mbstring php5-openssl +cd /srv/www/htdocs +sudo wget http://kanboard.net/kanboard-latest.zip +sudo unzip kanboard-latest.zip +sudo chmod -R 777 kanboard +sudo rm kanboard-latest.zip +``` diff --git a/doc/translations.markdown b/doc/translations.markdown index 629c4355..00707e1c 100644 --- a/doc/translations.markdown +++ b/doc/translations.markdown @@ -5,7 +5,7 @@ How to translate Kanboard to a new language? -------------------------------------------- - Translations are stored inside the directory `app/Locale` -- There is subdirectory for each language, for example in French we have `fr_FR`, Italian `it_IT` etc. +- There is a subdirectory for each language, for example in French we have `fr_FR`, Italian `it_IT` etc. - A translation is a PHP file that returns an Array with a key-value pairs - The key is the original text in English and the value is the translation of the corresponding language - **French translations are always up to date** @@ -34,20 +34,9 @@ Translations are displayed with the following functions in the source code: - `t()`: display text with HTML escaping - `e()`: display text without HTML escaping -- `dt()`: display date and time using the `strftime()` function formats Always use the english version in the source code. -### Date and time translation - -Date strings use the function `strftime()` to format the date. - -For example, the original English version can be defined like that `Created on %B %e, %Y at %k:%M %p` and that will output something like that `Created on January 11, 2015 at 15:19 PM`. The French version can be modified to display a different format, `Créé le %d/%m/%Y à %H:%M` and the result will be `Créé le 11/01/2015 à 15:19`. - -All formats are available in the [PHP documentation](http://php.net/strftime). - -### Placeholders - Text strings use the function `sprintf()` to replace elements: - `%s` is used to replace a string diff --git a/doc/ubuntu-installation.markdown b/doc/ubuntu-installation.markdown index cec3ebba..ab4dfe7c 100644 --- a/doc/ubuntu-installation.markdown +++ b/doc/ubuntu-installation.markdown @@ -26,3 +26,5 @@ sudo unzip kanboard-latest.zip sudo chown -R www-data:www-data kanboard/data sudo rm kanboard-latest.zip ``` + +Some features of Kanboard require that you run [a daily background job](cronjob.markdown). diff --git a/doc/windows-apache-installation.markdown b/doc/windows-apache-installation.markdown index 2c8f74e1..27b6812e 100644 --- a/doc/windows-apache-installation.markdown +++ b/doc/windows-apache-installation.markdown @@ -123,3 +123,8 @@ Tested configuration -------------------- - Windows 2008 R2 / Apache 2.4.12 / PHP 5.6.8 + +Notes +----- + +- Some features of Kanboard require that you run [a daily background job](cronjob.markdown). diff --git a/doc/windows-iis-installation.markdown b/doc/windows-iis-installation.markdown index 6206db21..bd4607de 100644 --- a/doc/windows-iis-installation.markdown +++ b/doc/windows-iis-installation.markdown @@ -65,3 +65,9 @@ Tested configurations - Windows 2008 R2 Standard Edition / IIS 7.5 / PHP 5.5.16 - Windows 2012 Standard Edition / IIS 8.5 / PHP 5.3.29 + +Notes +----- + +- Some features of Kanboard require that you run [a daily background job](cronjob.markdown). + |