Running and configuring the container

The app container runs Kantree. This chapter explains how it runs and how to configure it. All the options are listed in the Configuration reference, and the options of the extensions in Extensions.

What the container does

The app container starts every Kantree process: web server, push server, collaboration server, workers and scheduler (and the MCP server when mcp_enabled is set). To start only some of them, see Running specific processes.

At every start, the container first upgrades the database, then starts Kantree.

If one of the processes keeps failing, the container stops. Give it a restart policy: the example uses restart: unless-stopped.

The container runs as the user 65532. It keeps the uploaded files in the /uploads volume. Back up this volume with the database (see Backups).

It listens on these ports, which your reverse proxy forwards (see Using your own reverse proxy):

Running commands

To run a Kantree command, use:

$ docker compose run --rm app <command>

For example:

$ docker compose run --rm app gen-credential-encryption-key

Configuring the container

Kantree is configured with a configuration file written in YAML (config.yml), with environment variables, or both:

• mount your config.yml in the container. The user 65532 must be able to read it. To use another path, set it in the KANTREE_CONFIG environment variable.
• set KANTREE_<OPTION> environment variables, for example KANTREE_SECRET_KEY for secret_key. With Compose, you can write them in the .env file or in the environment section of the app service. Their values are read as JSON when possible: KANTREE_SERVER_SECURED=true gives the boolean true.

Option names are not case-sensitive in config.yml: this chapter uses the lower-case form. Environment variables take precedence over the files (see Set an option).

After you change the configuration, check it:

$ docker compose run --rm app check-config

Then restart the container with docker compose up -d (it re-creates the container when its environment changed) or docker compose restart app, and read the logs: an option with a former name writes an is deprecated warning.

Defaults of the container

At every start, the container writes its defaults to config-docker.yml. Your config.yml and the KANTREE_<OPTION> variables override them. Set KANTREE_NO_DOCKER_CONF=1 to disable these defaults.

Main settings

Secret keys

You must provide a secret key. It signs sessions and cookies, and protects the collaboration server.

secret_key: YOUR_SECRET_KEY

Use a random value of at least 32 characters (not changeme), for example generated with openssl rand -hex 32. Keep it stable: changing the secret key logs every user out.

Kantree encrypts the credentials it stores (integration tokens, OAuth secrets, API keys). We strongly recommend to set a dedicated key for them. Without credential_encryption_keys, the keys are derived from secret_key, and changing secret_key later would make every stored credential unreadable.

Generate a key:

$ docker compose run --rm app gen-credential-encryption-key

Then set it in your configuration:

credential_encryption_keys: [YOUR_CREDENTIAL_KEY]

Back up this key with the same care as the database: stored credentials cannot be read without it.

Push notification keys

Desktop and mobile notifications need VAPID keys. Without them, push notifications are not sent. Generate them:

$ docker compose run --rm app generate-web-push-keys

Then set them in your configuration, with your own contact address:

notification_web_push_public_key: PUBLIC_KEY
notification_web_push_private_key: PRIVATE_KEY
notification_web_push_subject: mailto:admin@yourcompany.com

The other options are listed in Notifications.

Hostnames

This is required if you serve Kantree from anything other than the example address (http://localhost:8080).

• server_name: the hostname (including port if different than 80 or 443) under which Kantree will be accessible. This will be used to generate URLs.
• server_secured: set to true to indicate that Kantree is served over HTTPS.
• push_server_url: the full URL under which the Kantree push server will be accessible. This will be used to connect to the push server from the frontend.

Important: If you are using HTTPS, don’t forget to update push_server_url as well.

Example:

server_name: example.com
server_secured: true
push_server_url: https://example.com

If your reverse proxy forwards /socket.io to the push server (as in the example), push_server_url is the URL of Kantree.

If your reverse proxy does not serve the collaboration server at /hocuspocus on the address of Kantree, set its public URL with collab_server_url.

If you are using an IP as your server_name, you will also need to set the option session_cookie_domain to the same value. Example:

server_name: 192.168.1.1:8080
session_cookie_domain: 192.168.1.1:8080

PostgreSQL and Redis

By default, the container connects to the postgres and redis containers of the example. To use other servers, set these environment variables on the app container:

You can also set the full addresses in your configuration, which overrides these variables:

database_uri: postgresql://user:pass@host:port/db
redis_uri: redis://host:port/db

Emails

If not configured, emails won’t be sent:

mail_server: localhost
mail_port: 587
mail_username: example
mail_password: example
mail_use_tls: true

The former smtp_* names still work but are deprecated: a warning is written in the logs. When both names are set, the mail_* value is used.

You can configure the default sender address using the mail_default_sender option:

mail_default_sender: "Kantree <no-reply@yourcompany.com>"

To send emails with Mailgun, Brevo or Sweego instead of SMTP, see Email sending.

Uploaded files

By default, uploaded files are stored in the /uploads volume of the container. The user 65532 must be able to write in it.

You can store them in an S3-compatible object storage (AWS S3, MinIO…) instead:

upload_backend: s3
upload_backends:
  s3:
    backend: s3
    bucket: BUCKETNAME
    access_key: ACCESSKEY
    secret_key: SECRETKEY
    region: REGIONNAME # (eg: eu-central-1)
    async: true

Browsers upload the files directly to the bucket: add a CORS rule to the bucket that allows the GET, POST and PUT methods from the URL of Kantree. All the options of the backend are listed in s3.

Important: before 11.0, this setting was named upload_default_backend. Kantree 11 does not read this name: without upload_backend, new files are stored in upload_dir, on the local disk.

upload_tmp_dir and nginx_uploads are described in File storage.

Logs

Read the logs of the container with:

$ docker compose logs -f app

You can also write them to a file with log_filename. The user 65532 must be able to write the file: use a path in a volume, so that it is kept when the container is re-created.

log_filename: /path/in/a/volume/kantree.log

To show this file in the logs view of the admin area, set admin_log_filename to the same path. The other options are listed in Logging and monitoring.