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.

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. If you are accessing Kantree using an IP address (eg. http://192.168.1.1:5000), you will need to set the SESSION_COOKIE_DOMAIN configuration option

To run Kantree as a background process, we recommand using Supervisord which is a popular process runner for Python applications. Install Supervisor (apt install supervisor on Debian-like systems or yum install supervisor on CentOS).

We provide an example configuration file for supervisor as supervisor.conf.example. It assumes that Kantree is installed under /opt/kantree (feel free to change). Copy this file to the supervisor configuration folder as:

  • /etc/supervisorctl/conf.d/kantree.conf on Debian-like systems
  • /etc/supervisord.d/kantree.ini on CentOS

Then update supervisor: supervisorctl update. Read more about managing supervisor on their website.

Kantree is divided into 4 processes:

  • web: the web frontend server
  • 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)

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. We recommend Nginx (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 TLSv1.1 TLSv1.2;
    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 organizations 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.