Migrating from previous versions

In this article

Migrating to 11.0

Read this section before starting Kantree 11: the database upgrade runs when the container starts. Back up your database and your uploaded files first (see Backups).

Kantree 11.0 is only distributed as a Docker image. If you installed a previous version from the archive (with ./platform), see Moving from the archive to the Docker image.

Before the first start

  1. Migrate your configuration. Some settings are renamed or removed, and some former names are no longer read (see Configuration changes in 11.0). Pull the image of Kantree 11, but do not start it. Then migrate your configuration files with the migrate-config command, and do the actions of its “To do by hand” list. See Migrating the configuration files. The command does not migrate the KANTREE_* environment variables and the .env file: rename them with the tables of Configuration changes in 11.0.
  2. Check secret_key. It must be set (not changeme), and should be at least 32 characters: shorter keys cannot be used later to move credentials to a dedicated key. check-config fails without a secret_key.
  3. Configure a credential key. Kantree 11 encrypts stored credentials during the upgrade. 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 with docker compose run --rm app gen-credential-encryption-key and set credential_encryption_keys: [<key>]. Back it up with the same care as the database. See Secret keys.
  4. Update your proxy configuration. Kantree 11 adds the collaboration server (/hocuspocus) and the MCP server. The example nginx-docker.conf already routes them; update your own reverse proxy if you use one (see Using your own reverse proxy).
  5. Give the files to the new user. The image now runs as the user 65532. Before the first start, run docker compose run --rm --user root --entrypoint chown app -R 65532:65532 /uploads. Make sure that this user can read your config.yml.
  6. Check the precedence of your settings. config.yml now overrides the defaults of the container (DB_* and REDIS_* variables, push_server_url). Use KANTREE_<SETTING> variables to override config.yml.
  7. Check your configuration: docker compose run --rm app check-config.
  8. Preview the renamed accounts. Emails and usernames are now unique, regardless of case: the database upgrade renames the duplicate accounts. To see them, run docker compose run --rm app preview-user-dedup.
  9. If you used the previous docker-compose.yml, move your data. It kept the database, the uploaded files and the Redis data in anonymous volumes. The new example uses named volumes and postgres:18. Follow Moving the data of the previous example before you start Kantree 11: it includes steps 1, 7 and 8.

After the first start

  1. Expect users to log in again. Sessions created before Kantree 11 are not accepted.
  2. Move the unread notifications. Kantree 11 keeps notifications in the database instead of Redis. After the first start, run docker compose run --rm app backfill-unread-notifications. Until then, the inbox does not show the notifications that were unread before the upgrade. Keep the Redis data of the previous version: the command reads it.
  3. Read the logs for is deprecated warnings (docker compose logs app | grep "is deprecated"), and rename these settings.
  4. Configure AI. The ai_provider and ai_api_key settings are not migrated. To give AI features to all the organizations, create a global AI provider (see AI settings). If you used these settings, the report of migrate-config gives the create-ai-provider command to run.
  5. Enable desktop and mobile notifications. They need VAPID keys: see Notifications.

Moving the data of the previous example

If you used the docker-compose.yml of a previous version, do these steps in its directory.

  1. While the previous version runs, save the database: docker compose exec postgres pg_dump -U kantree -Fc kantree > kantree.dump.
  2. Save the uploaded files: docker compose cp app:/uploads ./uploads-backup.
  3. Save the Redis data: docker compose exec redis redis-cli save, then docker compose cp redis:/data/dump.rdb ./dump.rdb.
  4. Stop the previous version: docker compose down.
  5. Replace the files with the files of Kantree 11. Write KANTREE_SECRET_KEY in the .env file. Migrate your configuration (see Migrating the configuration files).
  6. Create the new containers and volumes: docker compose up --no-start.
  7. Copy the data back: docker compose cp ./uploads-backup/. app:/uploads, then docker compose cp ./dump.rdb redis:/data/dump.rdb.
  8. Give the files to the new user: docker compose run --rm --user root --entrypoint chown app -R 65532:65532 /uploads.
  9. Restore the database: docker compose up -d postgres, then docker compose exec -T postgres pg_restore -U kantree -d kantree --no-owner < kantree.dump.
  10. Check the configuration and preview the renamed accounts: docker compose run --rm app check-config, then docker compose run --rm app preview-user-dedup.
  11. Start Kantree 11: docker compose up -d.

Then follow the steps of After the first start.

Moving from the archive to the Docker image

If you installed a previous version from the archive, you can keep your PostgreSQL and Redis servers, or move your data to the containers of the example.

To keep your servers, give the app container access to them:

  • Mount your config.yml in the container. Inside the container, localhost is the container itself: in database_uri and redis_uri, use an address of your servers that the container can reach.
  • Make sure your PostgreSQL server accepts password connections from the container (pg_hba.conf).
  • Copy your uploaded files to the /uploads volume (docker compose cp /path/to/uploads/. app:/uploads after docker compose up --no-start), and remove upload_dir from your config.yml.
  • Stop the processes of the previous version, and remove its systemd unit or supervisord configuration.

To use the containers of the example, save your database with pg_dump -Fc kantree > kantree.dump and your Redis data (redis-cli save, then copy the dump.rdb file of your Redis server), then follow Moving the data of the previous example from step 4. Remove database_uri, redis_uri and upload_dir from your config.yml so that the defaults of the container are used.

In both cases, follow the steps of Before the first start and After the first start.

Configuration changes in 11.0

Kantree 11 no longer uses the frasco library. Some settings that frasco read have new names, and the former names of some of them no longer work.

Change Former names still work? What to do
smtp_* is now mail_* Yes, with a warning Rename the settings
Authentication settings use the auth_ prefix Yes, with a warning Rename the settings
frasco_users_* is now auth_* No Rename the settings
upload_default_backend is now upload_backend No Rename the setting
Options of some integrations move out of extensions No Move the options
Removed extensions No: Kantree does not start Remove them from extensions
AI provider settings are removed No Create a global AI provider
default_feature_flags blocks the features that it does not list — Add the new flags if you set this setting
Case-sensitive usernames and emails are removed No: Kantree does not start Remove the settings

The migrate-config command applies these changes to your configuration files.

Migrating the configuration files

The migrate-config command of Kantree 11 migrates a configuration file. It keeps the comments of the file, and it does not need a working configuration: run it before the first start of Kantree 11.

In the directory of docker-compose.yml, first look at the changes:

$ docker compose run --rm -T app migrate-config config.yml --diff

Then write the migrated file next to your config.yml:

$ docker compose run --rm -T app migrate-config config.yml > config.v11.yml

The report of the command is written in the terminal, not in config.v11.yml. It lists the changes and the actions to do by hand. Do these actions, check config.v11.yml, then replace config.yml with it. Keep the original file as a backup.

Command Result
migrate-config config.yml --diff Shows the changes. Does not write anything.
migrate-config config.yml --in-place Replaces config.yml. The original file is config.yml.v10.bak.
migrate-config config.yml -o config.v11.yml Writes the migrated file to config.v11.yml
migrate-config config.yml Writes the migrated file to the standard output

--in-place and -o write the files in the container: they are only kept if the directory of config.yml is mounted read-write. Without a file name, the command migrates the file of KANTREE_CONFIG, or config.yml.

What the command does:

  • It comments out the removed settings, with the reason. It does not delete them.
  • It writes the moved settings before the place of the former setting, after a # Moved by kantree migrate-config line.
  • If you run it again on a migrated file, it changes nothing.

Migrate each configuration file of the instance: config.yml, and config.production.yml if it exists.

The command does not migrate:

  • the KANTREE_* environment variables and the .env file: rename them with the tables below
  • the AI settings: it gives the create-ai-provider command to run after the upgrade (see AI settings)

Renamed mail settings

10.X 11.0
smtp_server mail_server
smtp_port mail_port
smtp_username mail_username
smtp_password mail_password
smtp_use_tls mail_use_tls
smtp_<option> (for example smtp_suppress_send) mail_<option>
frasco_mail_<option> mail_<option>

Kantree 11 still reads the smtp_* names and writes SMTP_... is deprecated in the logs. If you set both names, the mail_* value is used. The frasco_mail_* names are not read.

Renamed authentication settings

Kantree 11 still reads these names, and writes ... is deprecated; use AUTH_... instead in the logs. If you set the auth_* name to a value other than its default, the former name is ignored.

10.X 11.0
allow_signup auth_allow_signup
enable_2fa auth_enable_2fa
user_can_reset_password auth_allow_reset_password
recaptcha_key, recaptcha_secret auth_recaptcha_key, auth_recaptcha_secret
hcaptcha_key, hcaptcha_secret auth_hcaptcha_key, auth_hcaptcha_secret
signup_welcome_email: true auth_send_welcome_email: welcome.md
validate_user_emails auth_send_email_validation_email
block_non_email_validated_users auth_block_non_email_validated_users

In 10.X, the frasco_users key or the frasco_users_* settings configured the login, the signup and the passwords. Kantree 11 does not read them. Each option now has the auth_ prefix:

10.X 11.0
frasco_users_<option>, or <option> under frasco_users: auth_<option>

For example, frasco_users_validate_password_regexps is now auth_validate_password_regexps. The *_message options of frasco_users and enable_admin are not available in 11.0.

Renamed upload settings

10.X 11.0
upload_default_backend upload_backend

Important: Kantree 11 does not read upload_default_backend. If you do not rename it, new files are stored in upload_dir, on the local disk, instead of your storage backend.

upload_backends, upload_dir, exports_upload_backend, max_upload_size, max_public_upload_size and limit_public_upload_file_types do not change. The options of the s3 backend do not change.

Renamed service worker settings

10.X 11.0
cache_service_worker_name service_worker_name
cache_service_worker_url service_worker_url

The former names are not read.

Options of the extensions

In 10.X, you could give the options of an extension under its entry in extensions. In 11.0, give them as top-level settings, with the prefix of the extension. A top-level setting takes precedence over an option under the entry.

# 10.X
extensions:
  - kantree.integrations.trello:
      client_id: "..."
      client_secret: "..."

# 11.0
extensions:
  - kantree.integrations.trello
trello_client_id: "..."
trello_client_secret: "..."

These extensions ignore the options under their entry in 11.0. You must move their options:

Extension Prefix Example
kantree.integrations.trello trello_ trello_client_id
kantree.integrations.asana asana_ asana_client_id
kantree.integrations.dropbox dropbox_ dropbox_app_key
kantree.integrations.microsoft365 (also office365) microsoft365_ microsoft365_client_id
kantree.integrations.jira jira_ jira_field_type_map

The other extensions still read the options under their entry. Use the top-level form for them too:

Extension Prefix
kantree.integrations.google google_
kantree.integrations.github github_
kantree.integrations.slack slack_
kantree.extensions.auth.ldap ldap_ (see Directory Services)
kantree.extensions.auth.saml saml_ (see SSO)
kantree.extensions.auth.oidc (new) oidc_ (see SSO)
kantree.extensions.emailing emailing_

Removed extensions

If extensions lists one of these entries, Kantree does not start:

10.X entry 11.0
frasco.geoip Remove the entry. Geolocation is built in.
Any other frasco.* entry Remove the entry.
kantree.extensions.pgsql_adapter, kantree.extensions.enterprise.pgsql_adapter Remove the entry. The PostgreSQL protocol adapter is now the sqladapter command (port 55432).

AI settings

These settings are removed:

10.X 11.0
ai_provider A global AI provider
ai_api_key The API key of the global AI provider
ai_org_auto_enabled Removed. The organizations that did not configure AI use the first global provider.

Kantree 11 and migrate-config do not migrate these settings. To give AI features to all the organizations, create a global provider in the AI providers of the admin area, or with docker compose run --rm app create-ai-provider "<name>" <provider> (see AI).

If you used ai_provider with a base_url (custom provider), create a Custom provider with the same base URL.

ai_assistant does not change. The new AI settings are listed in AI.

Feature flags

default_feature_flags now gives the features of the organizations. The features that are not in this list are refused.

The default value of 11.0 adds documents, discussions, whiteboards, ai, dependencies, quadrant and emailing:

default_feature_flags: [teams, org_hub, sso, portfolios, gantt, documents, discussions, whiteboards, ai, dependencies, quadrant, emailing]

If your config.yml sets default_feature_flags, add the new flags that you want. Otherwise, your users cannot use these features.

Removed settings

Setting Why
disable_cache_service_worker Kantree always registers its service worker, because desktop and mobile notifications need it
kantree_coach_enabled, kantree_coach_token The Kantree Coach service is removed
ai_provider, ai_api_key, ai_org_auto_enabled See AI settings
auth_email_is_unique, auth_username_is_unique, auth_username_case_sensitive Emails and usernames are now unique, regardless of case

Important: if you set auth_email_is_unique: false, auth_username_is_unique: false or auth_username_case_sensitive: true, Kantree does not start. Remove the setting. Then run docker compose run --rm app preview-user-dedup to see the duplicate accounts that the database upgrade renames.

New settings

All the new settings have a default value. Change them only if you need the feature.

Feature Settings
Encryption of the stored credentials credential_encryption_keys: see Secret keys
Two-factor authentication, login attempts, sessions, outgoing webhooks auth_force_2fa, auth_freeze_login_*, auth_session_ttl, auth_check_username_availability, webhooks_whitelist: see Security
Collaboration server (documents, whiteboards) collab_*: see Collaboration server and Scaling
MCP server mcp_*: see MCP server
Several instances on one Redis server push_channel: see Redis
AI ai_*: see AI
Notifications notification_*: see Notifications
Calls in discussions, previews of office files livekit_*, wopi_*: see Office documents, video calls and maps
SSO panel on the login page sso_login_*: see Authentication
Uploads upload_tmp_dir, nginx_uploads: see File storage
Background tasks tasks_timeout, tasks_scheduled_timeout, queue_notifications: see Background processing

Migrating from older versions

The migration notes for versions before 11.0 are in the guide for versions 9.X and 10.X.