Installing using Docker

Kantree includes a Dockerfile which lets you build a Docker image. It also includes a docker-compose.yml file to let you start all the needed services in one command. This is the easiest way to launch Kantree.

Launching

First, install Docker and Compose.

Ensure that your license file is located at the root of your installation. Run docker compose:

$ docker compose up

Kantree will then be accessible at http://localhost:5000.

Compose will launch three containers:

• PostgreSQL using the official postgres:12 image
• Redis using the official redis:alpine image
• Kantree by building the image from the current directory

You can configure Kantree using a configuration file as described in the Configuration chapter.

After creating your configuation file (config.yml), modify the volumes section of the app service in the docker-compose.yml file to mount it under /app/config.yml. Example:

version: '3'
services:
  app:
    build: .
    links:
      - postgres
      - redis
    ports:
      - "5000:5000"
      - "4000:4000"
    volumes:
      - ${PWD}/license:/app/license
      - ${PWD}/config.yml:/app/config.yml
# ...

To use a different domain name, refer to the last section of this guide.

Note that you shoud configure the Postgres container to suit your needs. We especially recommand to use volumes to avoid loosing data.

Create an admin user using the following command:

$ docker compose run app create-admin admin admin@example.com

The kantree image

If you prefer to create a container yourself, you can just build the image using:

$ docker build -t kantree .

For the container to start, you must mount a license file under /app/license.
You can also provide a configuration file under /app/kantree/config.yml.
If you want to persist uploaded files, you will need to mount the /uploads dir.

The image exposes the following ports:

• 5000: for HTTP service
• 4000: for WebSocket service

The image does not include PostgreSQL or Redis. You will need to launch these containers independently and make them available in the kantree container (via link or network) under the names postgres and redis.

The image will auto-create a config file with PostgreSQL, Redis and uploaded file settings. You can set the KANTREE_NO_DOCKER_CONF=1 environment variable to prevent the creation of this file so none of your settings are overrided.

The container can be configured with some environment variables:

Example:

$ docker run --name kantree -v /path/to/license:/app/license -v /path/to/config.yml:/app/config.yml -p 5000:5000 -p 4000:4000 kantree

Updating

To update Kantree, rebuild the kantree image, upgrade the database schema and re-create the kantree container.

To update the schema, use the following command:

$ docker run [options] kantree upgrade-db

Using compose, the procedure is as follow:

1. Rebuild the image: docker compose build app
2. Stop and destroy the kantree container: docker compose stop app && docker compose rm app
3. Upgrade the database schema: docker compose run app upgrade-db
4. Restart the container: docker compose start app

Commands

To create a user or make an existing user an admin you can do:

$ docker run [options] app create-admin USERNAME EMAIL
$ docker run [options] app make-admin USERNAME

When started without any command the container will launch all the processes needed for Kantree to work. However, these processes can be split into different containers:

$ docker run [options] app run web
$ docker run [options] app run push
$ docker run [options] app run worker
$ docker run [options] app run scheduler

Note that starting processes this way will not automatically ensure that the database is up to date. You can run this command to do so:

$ docker run [options] app upgrade-db

If you are using docker compose, you can do:

$ docker-compose run app <command> <args>

Example:

$ docker compose run app create-admin admin admin@localhost

Using a custom hostname

Note that the docker image is the equivalent of a node and that you will need a reverse-proxy in front of the nodes. Refer to the Multi-node deployment section for more info.

To quickly create a reverse proxy, you can use the official nginx image. Save the following config file as app.conf and replace the {{SERVER_NAME}} placeholder with your hostname:

upstream app {
    server kantree:5000;
}

upstream push {
    ip_hash;
    server kantree:4000;
}

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

    location / {
        proxy_pass http://app;
        proxy_redirect off;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location /socket.io {
        proxy_pass http://push;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_read_timeout 2m;
        proxy_buffering off;
    }
}

Launch the nginx container:

$ docker run -d -v /path/to/app.conf:/etc/nginx/conf.d/kantree.conf -p 80:80 nginx