Enterprise On-Premise

Install & manage your on-premise instance of Kantree

Installing on an existing machine

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

Download

Download the latest release from https://enterprise.kantree.io/releases.

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:

$ ./platform run

This will start the multiple processes composing Kantree. The default ports are 5000 for the http server and 4000 for the websocket server.

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

Use ./platform run --help for options regarding ports and scalability.

Using systemd

Your can use the kantree.service.example unit file. Replace the path (default /opt/kantree).

Note: this uses the user kantree to run the process.

Then enable the service and start it:

$ systemctl enable kantree.service
$ systemctl start kantree.service

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 RHEL/CentOS/Rocky, 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