Installing on an existing machine

Kantree includes a management script (./platform) which makes it easy to install, update and run your Kantree instance.

Installation

First, make sure you have PostgreSQL and Redis installed and configured, and that you have downloaded your license file. For help installating Postgres and Redis, consult the Requirements chapter.

Run the following command:

$ ./platform init

This command will:

  • make sure all the required system packages are installed and ask you to install the missing ones
  • create a Python virtualenv and install all required Python dependencies
  • verify that your license is valid
  • generate a configuration file by asking you some questions
  • check that the database and redis server are accessible
  • create the database schema
  • create an admin user

If a problem is reported when the configuration is checked, you can edit the generated configuration file manually as described in the Configuration section. Once edited, you can run init again.

If updating the database schema fails because the CREATE EXTENSION command fails for permissions reasons, you will need to create the extensions manually as described in the requirements section.

Note: If you are planning to automate the updating of Kantree, have a look at the Updating section which will give you pointers.

Creating an admin user

An admin user will be created during the init step but you can create additional ones or make an existing user an admin.

Create an adminstration user from the command line:

$ ./platform create_admin USERNAME EMAIL

Make an existing user an admin:

$ ./platform make_admin USERNAME

Running

Run Kantree using its built-in process manager:

$ ./platform run

Kantree will be available at http://localhost:5000.

The Procfile

To run Kantree as a background process, you can use any Procfile compatible process manager. You can find the Procfile needed to run Kantree at the root of the installation.

Kantree is divided into 4 processes:

  • web: the web frontend server (port 5000 by default)
  • worker: background worker
  • scheduler: the process launching tasks at fixed time
  • push: the push server, a socket.io server used to send events from the server to the client as they happen (port 4000 by default)

Kantree includes a simple Procfile runner called Honcho. The command ./platform run is actually an alias for honcho start and takes the same arguments. You can call Honcho using ./platform honcho.

You can also use foreman, the most popular Procfile runner which has more options and more export targets.

Exporting to init systems

Honcho has the ability to export a Procfile to other process runners using ./platform honcho export. Read more about it here.

Before proceeding, you will need to create a file named envfile at the root of your installation with the following content:

PATH=/path/to/kantree/venv/bin

(replace /path/to/kantree with the path of your kantree installation).

This ensures that the command listed in the Procfile will run in the Python virtualenv/

Using systemd

Your can export the Procfile to systemd compatible service file using the following command:

$ ./platform honcho export -a kantree -u kantree -e envfile systemd /usr/lib/systemd/system

Note: this uses the user kantree to run the processes (option -u)

Then enable the service and start it:

$ systemctl enable kantree.target
$ systemctl start kantree.target

Using Supervisor

Supervisor is a popular process runner for Python apps.

Note: if you were using supervisor with previous versions of Kantree, you will need to update the commands for each processes with the new ones found in the Procfile.

To export the Procfile as a supervisor config file, use the following command:

$ ./platform honcho export -a kantree -u kantree -e envfile supervisord /etc/supervisor/conf.d

Note: this uses the user kantree to run the processes (option -u)

Then update supervisor and start the services:

$ supervisorctl update
$ supervisorctl start kantree:*

Serving from your own domain

You’ll need to install a reverse-proxy to serve Kantree from a single domain name or under a different port.

The proxy must forward all requests other than the ones under the path /socket.io to the web process (port 5000). Requests under the path /socket.io must be fowarded to the push server (port 4000). The proxy must be able to handle WebSocket upgrades for the push server.

We recommend Nginx as proxy (which we use ourselves). You will find an nginx.conf.example file at the root of your installation.

You will need to replace the {{SERVER_NAME}} and {{PATH_TO_KANTREE_ROOT}} placeholders.

You will also need to update your configuration to specify the domain name.

On Ubuntu, it is as simple as:

$ sudo apt-get install nginx
$ sudo cp nginx.conf.example /etc/nginx/sites-available/kantree.conf
$ sudo vim /etc/nginx/sites-available/kantree.conf # replace placeholders
$ sudo ln -s /etc/nginx/sites-available/kantree.conf /etc/nginx/sites-enabled/kantree.conf
$ sudo service reload nginx

Remember that you still need to launch the run command or use a process runner as described in the previous section. Make sure port 80 is opened in your firewall.

Tip: on CentOS, if nginx reports a permission denied error when trying to connect the upstream (kantree), it is due to SELinux. You will need to modify SELinux as explained here.

Serving Kantree using HTTPS

To serve Kantree behind HTTPS, you must use a reverse-proxy like Nginx. First update your Kantree configuration file to use https as prefered protocol as explained in the confuration chapter.

Then update the nginx configuration file as explained in their documentation. Here is an example configuration:

server {
    listen 80;
    server_name {{SERVER_NAME}};

    location / {
        return 301 https://$server_name$request_uri;
    }
}

server {
    listen 443;
    server_name {{SERVER_NAME}};

    ssl on;
    ssl_certificate www.example.com.crt;
    ssl_certificate_key www.example.com.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    # all the location blocks as defined in the example nginx config file as the root of your installation
}

Web administration console

You can manage users and teams from the online administration console located at /admin (eg: http://localhost:5000/admin). Note that you need to be an admin to access this console, refer to the Creating an admin user section.

Updating Kantree

See the Updating section