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:9.4 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-prod.yml), modify the volumes section of the kantree service in the docker-compose.yml file to mount it under /app/kantree/config-prod.yml. Example:

version: '3'
services:
  kantree:
    build: .
    links:
      - postgres
      - redis
    ports:
      - "5000:5000"
      - "4000:4000"
    volumes:
      - ${PWD}/license:/app/license
      - ${PWD}/kantree/config-prod.yml:/app/kantree/config-prod.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 kantree 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-prod.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:

Key Default Description
DB_HOST postgres Hostname of the Postgres server
DB_PORT 5432 Port of the Postgres server
DB_USER postgres Username to connect to the server
DB_PASSWORD   Password to connect to the server
DB_NAME ${DB_USER} Database to use for Kantree
REDIS_HOST redis Hostname of the Redis server
REDIS_PORT 6379  
REDIS_DB 0 Redis DB number
KANTREE_NO_DOCKER_CONF   Set this variable to 1 to avoid generating a basic config file for services

Example:

$ docker run --name kantree -v /path/to/license:/app/license -v /path/to/config.yml:/app/kantree/config-prod.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 kantree
  2. Stop and destroy the kantree container: docker-composer stop kantree && docker-compose rm kantree
  3. Upgrade the database schema: docker-composer run kantree upgrade-db
  4. Restart the container: docker-composer start kantree

Commands

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

$ docker run [options] kantree create_admin USERNAME EMAIL
$ docker run [options] kantree 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] kantree web
$ docker run [options] kantree push
$ docker run [options] kantree worker
$ docker run [options] kantree 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] kantree upgrade_db

If you are using docker-composer, you can do:

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

Example:

$ docker-compose run kantree 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 /api {
        add_header Cache-Control no-cache; # header needed for IE
        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