AS1024
/
Kanboard-Prod
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update documentation

This commit is contained in:
Frédéric Guillot 2014-10-26 19:58:47 -04:00
parent c5f59f8c8f
commit d97e1bd4cf
23 changed files with 172 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
README.markdown
View File

@ -60,6 +60,7 @@ Documentation
- [Editing projects](docs/editing-projects.markdown)
- [Sharing boards and tasks](docs/sharing-projects.markdown)
- [Automatic actions](docs/automatic-actions.markdown)
- [Project permissions](docs/project-permissions.markdown)
#### Working with tasks
@ -67,7 +68,12 @@ Documentation
#### Working with users
- [User management](docs/manage-users.markdown)
- [User management](docs/user-management.markdown)
#### Settings
- [Application settings](docs/application-configuration.markdown)
- [Board settings](docs/board-configuration.markdown)
#### More
@ -104,7 +110,6 @@ Documentation
#### Developers and sysadmins
- [Board configuration](docs/board-configuration.markdown)
- [Email configuration](docs/email-configuration.markdown)
- [Command line interface](docs/cli.markdown)
- [Json-RPC API](docs/api-json-rpc.markdown)

2
app/Template/config_application.php
View File

@ -7,7 +7,7 @@
<?= Helper\form_csrf() ?>
<?= Helper\form_label(t('Application URL'), 'application_url') ?>
<?= Helper\form_text('application_url', $values, $errors, array('placeholder="http://example.kanboar.net/"')) ?><br/>
<?= Helper\form_text('application_url', $values, $errors, array('placeholder="http://example.kanboard.net/"')) ?><br/>
<p class="form-help"><?= t('Example: http://example.kanboard.net/ (used by email notifications)') ?></p>
<?= Helper\form_label(t('Language'), 'application_language') ?>

2
app/Template/project_users.php
View File

@ -9,7 +9,7 @@
<?php if (empty($users['allowed'])): ?>
<div class="alert alert-error"><?= t('Nobody have access to this project.') ?></div>
<?php else: ?>
<div class="listing">
<div class="alert alert-info">
<p><?= t('Only those users have access to this project:') ?></p>
<ul>
<?php foreach ($users['allowed'] as $user_id => $username): ?>

9
assets/css/app.css
View File

@ -364,6 +364,15 @@ input.form-date {
border-color: #ddd;
}
.alert ul {
margin-top: 10px;
margin-bottom: 10px;
}
.alert li {
margin-left: 25px;
}
/* labels */
a.label {
text-decoration: none;

36
docs/application-configuration.markdown Normal file
View File

@ -0,0 +1,36 @@
Application settings
====================
Some parameters for the application can be changed on the settings page.
Only administrators can change those settings.
Go to the menu **Settings**, then choose **Application settings** on the left.
![Application settings](http://kanboard.net/screenshots/documentation/application-settings.png)
### Application URL
This parameter is used for email notifications.
The email footer will contains a link to the Kanboard task.
### Language
The application language can be changed at anytime.
The language will be set for all users.
### Timezone
By default, Kanboard use UTC as timezone, but you can define your own timezone.
The list contains all supported timezones by your web server.
### Date format
Input format used for date fields, by example the due date for tasks.
Kanboard offer 3 different choices:
- DD/MM/YYYY
- MM/DD/YYYY (default)
- YYYY/MM/DD
The [ISO 8601](http://en.wikipedia.org/wiki/ISO_8601) format is always accepted (YYYY-MM-DD or YYYY_MM_DD).

52
docs/board-configuration.markdown
View File

@ -1,30 +1,36 @@
Board configuration
===================
Board settings
===============
Some parameters for the boards can be changed with a config file.
Some parameters for boards can be changed on the settings page.
Only administrators can change those settings.
Default values are available in the file `config.default.php`.
If you want to override the default values, you have to create a config file `config.php` in the root directory of your Kanboard installation.
Go to the menu **Settings**, then choose **Board settings** on the left.
### Auto-refresh frequency for the public board view
```php
// Auto-refresh frequency in seconds for the public board view (60 seconds by default)
define('BOARD_PUBLIC_CHECK_INTERVAL', 60);
```
### Auto-refresh frequency for the board (Ajax polling)
```php
// Board refresh frequency in seconds (the value 0 disable this feature, 10 seconds by default)
define('BOARD_CHECK_INTERVAL', 10);
```
![Board settings](http://kanboard.net/screenshots/documentation/board-settings.png)
### Task highlighting
Display a shadow around the task when a task was moved recently. Set the value 0 to disable this feature.
This feature display a shadow around the task when a task is moved recently.
```php
// Period (in seconds) to consider a task was modified recently (0 to disable, 2 days by default)
define('RECENT_TASK_PERIOD', 48*60*60);
```
Set the value 0 to disable this feature, 2 days by default (172800 seconds).
Everything moved since 2 days will have shadow around the task.
### Refresh interval for public board
When you share a board, the page will refresh automatically every 60 seconds by default.
### Refresh interval for private board
When your web browser is open on a board, Kanboard check every 10 seconds if something have been changed by someone else.
Technically this process is done by Ajax polling.
### Default columns for new projects
You can change the default column names here.
It's useful if you always create projects with the same columns.
Each column name must be separated by a comma.
By default, Kanboard use those column names: Backlog, Ready, Work in progress and Done.

2
docs/centos-installation.markdown
View File

@ -34,6 +34,8 @@ If SeLinux is enabled, be sure that the Apache user can write to the directory d
chcon -R -t httpd_sys_content_rw_t /var/www/html/kanboard/data
```
You can also disable SeLinux if you don't need it.
Centos 6.5
----------

2
docs/cli.markdown
View File

@ -4,7 +4,7 @@ Command Line Interface
Kanboard provide 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 by example a huge report.
This feature is useful to run commands outside the web server process by example running a huge report.
Usage
-----

18
docs/creating-projects.markdown
View File

@ -3,12 +3,26 @@ Creating projects
Kanboard can handle multiple projects.
To create a new project, click on the top menu "projects" and click on the link "New project".
Creating projects for multiple users
-------------------------------------
![Project creation link](http://kanboard.net/screenshots/documentation/project-creation-link.png)
- Only administrators can create and manage those projects
- User management is available
To create a new project, click on the top menu **Projects** and click on the link **New project**.
Then the form appears:
![Project creation form](http://kanboard.net/screenshots/documentation/project-creation-form.png)
It's very easy, you just have to find a name for your project.
Creating a private prooject
---------------------------
- Everybody can create a private project
- There is **NO** user management
- Only the owner and administrators can access to the project
To create a new private project, click on the top menu **Projects** and click on the link **New private project**.
Note: project names must be unique.

1
docs/creating-tasks.markdown
View File

@ -22,3 +22,4 @@ Field description:
- **Color**: Choose the color of the card.
- **Complexity**: Used in agile project management (Scrum), the complexity or story points is a number that tells the team how hard the story is. Often, people use the fibonacci series.
- **Due Date**: Overdue tasks will have a red due date and upcoming due dates will be black on the board. Several date format are accepted in addition to the date picker.
- **Original Estimate**: Estimation in hours to complete the tasks.

7
docs/email-configuration.markdown
View File

@ -93,14 +93,9 @@ Here a example:
### How to display a link to the task in notifications?
To do that, you have to specify the URL of your Kanboard installation in your config file.
To do that, you have to specify the URL of your Kanboard installation in your [Application Settings](http://kanboard.net/documentation/application-configuration).
By default, nothing is defined, so no links will be displayed.
```php
// Your Kanboard base URL, example: http://demo.kanboard.net/ (used by email notifications or CLI scripts)
define('KANBOARD_URL', '');
```
Examples:
- http://demo.kanboard.net/

14
docs/github-authentication.markdown
View File

@ -9,7 +9,9 @@ Requirements
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. When that is done, they no longer need to manually login with their Kanboard account, but can simply automatically login with their GitHub account.
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.
When that is done, they no longer need to manually login with their Kanboard account, but can simply automatically login with their GitHub account.
How to link a GitHub account
----------------------------------
@ -26,16 +28,16 @@ Installation instructions
### Setting up OAuth 2.0
If you know what you're doing, you can directly go to the ["Register a new OAuth application"](https://github.com/settings/applications/new) site, set everything up and skip to [Setting up Kanboard](#setting-up-kanboard) below.
On Github, go to the page ["Register a new OAuth application"](https://github.com/settings/applications/new).
Summarizing the [official GitHub documentation](https://developer.github.com/guides/basics-of-authentication/#registering-your-app):
Just follow the [official GitHub documentation](https://developer.github.com/guides/basics-of-authentication/#registering-your-app):
- Open your [**Settings**](https://github.com/settings), select [**Applications**](https://github.com/settings/applications) from the sidebar and click on [**Register new application**](https://github.com/settings/applications/new) on the top, next to where it says **Developer applications**
- Fill out the form with whatever values you like, only the **Authorization callback URL** _must_ be: **http://YOUR_SERVER/?controller=user&action=gitHub**
- Open your [Settings](https://github.com/settings), select [Applications](https://github.com/settings/applications) from the sidebar and click on [Register new application](https://github.com/settings/applications/new) on the top, next to where it says **Developer applications**
- Fill out the form with whatever values you like, the **Authorization callback URL** _must_ be: **http://YOUR_SERVER/?controller=user&action=gitHub**
### Setting up Kanboard
Either create a new `config.php` file or copy and rename the `config.default.php` file and set the following values:
Either create a new `config.php` file or rename the `config.default.php` file and set the following values:
```php
// Enable/disable GitHub authentication

4
docs/installation.markdown
View File

@ -14,12 +14,14 @@ From the archive
1. You must have a web server with PHP installed
2. Download the source code and copy the directory `kanboard` where you want
3. Check if the directory `data` is writeable (It's the location Kanboard stores uploaded files as well as the sqlite database)
3. Check if the directory `data` is writeable
4. With your browser go to <http://yourpersonalserver/kanboard>
5. The default login and password is **admin/admin**
6. Start to use the software
7. Don't forget to change your password!
Note: The folder data is the location where Kanboard stores uploaded files as well as the Sqlite database.
From the repository
-------------------

9
docs/ldap-authentication.markdown
View File

@ -5,18 +5,21 @@ Requirements
------------
- LDAP extension for PHP
- LDAP server (By example: OpenLDAP or Microsoft Active Directory)
- LDAP server:
- OpenLDAP
- Microsoft Active Directory
- Novell eDirectory
Workflow
--------
When the LDAP authentication is activated, the login process work like that:
1. Try to authenticate the user by using the database
1. Try first to authenticate the user by using the database
2. If the user is not found inside the database, a LDAP authentication is performed
3. If the LDAP authentication is successful, a local user is created automatically with no password and marked as LDAP user.
Differences between a local user and a LDAP user are the following:
### Differences between a local user and a LDAP user are the following:
- LDAP users have no local passwords
- LDAP users can't modify their password with the user interface

6
docs/mysql-configuration.markdown
View File

@ -4,8 +4,6 @@ How to use Mysql or MariaDB instead of Sqlite
By default Kanboard use Sqlite to stores its data.
However it's possible to use Mysql or MariaDB instead of Sqlite.
By example, it can be useful if you don't want to store any data on the web server itself.
Mysql configuration
-------------------
@ -37,7 +35,7 @@ The second step is to create a config file named `config.php`:
### Define Mysql parameters
Inside our config file write those lines:
Copy and paste this config file and replace the values:
```php
<?php
@ -52,4 +50,4 @@ define('DB_HOSTNAME', 'REPLACE_ME');
define('DB_NAME', 'kanboard');
```
Now, you are ready to use Mysql!
Note: You can also rename the template file `config.default.php` to `config.php`.

14
docs/project-permissions.markdown Normal file
View File

@ -0,0 +1,14 @@
Project permissions
===================
To define project permissions, go to the project page and click on **User management**.
![Project permissions](http://kanboard.net/screenshots/documentation/project-permissions.png)
By default, a new project is visible from nobody except administrators.
The first section tell you who have access to the project.
**Only those users can be assigned to tasks**.
![Project default permssions](http://kanboard.net/screenshots/documentation/project-nobody-allowed.png)
You can allow only some specific users or choose to allow all Kanboard users.

34
docs/reverse-proxy-authentication.markdown
View File

@ -1,28 +1,35 @@
Reverse Proxy Authentication
============================
This authentication method is often used for [SSO](http://en.wikipedia.org/wiki/Single_sign-on) (Single Sign-On) especially for large organizations.
The authentication is done by another system, Kanboard doesn't know your password and suppose you are already authenticated.
Requirements
------------
- A well configured reverse proxy (or Apache auth on the same server), that performs authentication and sends the authenticated username to Kanboard using a HTTP header. It is useful if you have yet some SSO (Single-Sign-On) in your organization, so you should know what your are doing.
- A well configured reverse proxy
or
- Apache auth on the same server
How does this work?
-------------------
- Your reverse proxy authenticates the user and adds a HTTP header containing its login to the request. The default header name or how to specify it should be in the reverse proxy documentation, however:
- If it is the same web server that runs Kanboard, the CGI spec specifies this header to be REMOTE_USER (see [RFC 3875](http://www.ietf.org/rfc/rfc3875) §4.1.11). For example, Apache adds REMOTE_USER by default if `Require valid-user` is set. Note this header is only set for CGI (like PHP), and not if Apache is a reverse proxy to another Apache running Kanboard. It works the same with IIS and nginx according to their documentation.
- If it is a real reverse proxy, the HTTP ICAP extension draft spec proposes the header to be X-Authenticated-User (see [IETF draft spec §3.4](http://tools.ietf.org/html/draft-stecher-icap-subid-00#section-3.4)). This de-facto standart has been adopted by a number of tools.
- Kanboard retrieves the value of the specified HTTP header, and:
- If the user does not exist yet, creates it (it also checks if it is the default admin).
- **Authenticates the given user without any prompt, assuming it's valid (so it does NOT prompt the login page)**.
1. Your reverse proxy authenticates the user and send the username through a HTTP header.
2. Kanboard retreive the username from the request
- The user is created automatically if necessary
- Open a new Kanboard session without any prompt assuming it's valid
Installation instructions
-------------------------
### Setting up your reverse proxy
This is not in the scope of this documentation. You should check that the user login is sent by the reverse proxy using a HTTP header, and find which one.
This is not in the scope of this documentation.
You should check the user login is sent by the reverse proxy using a HTTP header, and find which one.
### Setting up Kanboard
@ -46,5 +53,12 @@ define('REVERSE_PROXY_DEFAULT_ADMIN', 'myadmin');
// In case the username is not an email address, it
// will be updated automatically as USER@mydomain.com
define('REVERSE_PROXY_DEFAULT_DOMAIN', 'mydomain.com');
```
Notes:
- If the proxy is the same web server that runs Kanboard, according the [CGI protocol](http://www.ietf.org/rfc/rfc3875) the header name will be `REMOTE_USER`. By example, Apache add `REMOTE_USER` by default if `Require valid-user` is set.
- If Apache is a reverse proxy to another Apache running Kanboard, the header `REMOTE_USER` is not set (same behaviour with IIS and Nginx).
- If you have a real reverse proxy, the [HTTP ICAP draft](http://tools.ietf.org/html/draft-stecher-icap-subid-00#section-3.4) proposes the header to be `X-Authenticated-User`. This de-facto standart has been adopted by a number of tools.

4
docs/tests.markdown
View File

@ -128,11 +128,11 @@ Actually only the API calls are tested.
Real HTTP calls are made with those tests.
So a local instance of Kanboard is necessary and must listen on `http://localhost:8000`.
Don't forget that all data will be removed/altered by the testsuite.
Don't forget that all data will be removed/altered by the test suite.
Moreover the script will reset and set a new API key.
1. Start a local instance of Kanboard `php -S 127.0.0.1:8000`
2. Run the testsuite from another terminal
2. Run the test suite from another terminal
The same method as above is used to run tests across different databases:

6
docs/translations.markdown
View File

@ -18,11 +18,11 @@ How to translate Kanboard to a new language?
3. Use the content of the French locales and replace the values
4. Inside the file `app/Model/Config.php`, add a new entry for your translation inside the function `getLanguages()`
5. Check with your local installation of Kanboard if everything is ok
6. Send a pull-request with Github
6. Send a [pull-request with Github](https://help.github.com/articles/using-pull-requests/)
How to update an existing translation?
--------------------------------------
1. Open the translation file `app/Locale/xx_XX/translations.php`
2. Missing translations are commented with `//` and the values are empty, just fill blank and remove comments
3. Check with your local installation of Kanboard and send a pull-request
2. Missing translations are commented with `//` and the values are empty, just fill blank and remove the comment
3. Check with your local installation of Kanboard and send a [pull-request](https://help.github.com/articles/using-pull-requests/)

3
docs/update.markdown
View File

@ -1,6 +1,8 @@
Update
======
Important: **Always do a backup of your database before upgrading!**
From the archive
----------------
@ -11,6 +13,7 @@ From the archive
5. Login and check if everything is ok
6. Remove the old Kanboard directory
From the repository
-------------------

0
docs/manage-users.markdown → docs/user-management.markdown
View File

4
docs/webhooks.markdown
View File

@ -33,8 +33,8 @@ Base URL: `http://YOUR_SERVER_HOSTNAME/?controller=webhook&action=task`
- `title`: Task title (required)
- `description`: Task description
- `color_id`: Supported colors are yellow, blue, green, purple, red, orange and grey
- `project_id`: Project id (Get the id from the projects page, mouse over on the project title)
- `owner_id`: Assignee (Get the user id from the users page, mouse over on the username)
- `project_id`: Project id (Get the id from the project page)
- `owner_id`: Assignee (Get the user id from the users page)
- `column_id`: Column on the board (Get the column id from the projects page, mouse over on the column name)
Only the token and the title parameters are mandatory. The different id can also be found in the database.

2
docs/windows-iis-installation.markdown
View File

@ -6,7 +6,7 @@ Windows 2008/2012 with IIS
### PHP installation
- Install IIS on your server (Add new role and don't forget to enable CGI/FastCGI)
- Install IIS on your server (Add a new role and don't forget to enable CGI/FastCGI)
- Install PHP by following the official documentation:
- [Microsoft IIS 5.1 and IIS 6.0](http://php.net/manual/en/install.windows.iis6.php)
- [Microsoft IIS 7.0 and later](http://php.net/manual/en/install.windows.iis7.php)