Migrating from previous versions
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
- 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-configcommand, and do the actions of its “To do by hand” list. See Migrating the configuration files. The command does not migrate theKANTREE_*environment variables and the.envfile: rename them with the tables of Configuration changes in 11.0. - Check
secret_key. It must be set (notchangeme), and should be at least 32 characters: shorter keys cannot be used later to move credentials to a dedicated key.check-configfails without asecret_key. - Configure a credential key. Kantree 11 encrypts stored credentials during the upgrade. Without
credential_encryption_keys, the keys are derived fromsecret_key, and changingsecret_keylater would make every stored credential unreadable. Generate a key withdocker compose run --rm app gen-credential-encryption-keyand setcredential_encryption_keys: [<key>]. Back it up with the same care as the database. See Secret keys. - Update your proxy configuration. Kantree 11 adds the collaboration server (
/hocuspocus) and the MCP server. The examplenginx-docker.confalready routes them; update your own reverse proxy if you use one (see Using your own reverse proxy). - Give the files to the new user. The image now runs as the user
65532. Before the first start, rundocker compose run --rm --user root --entrypoint chown app -R 65532:65532 /uploads. Make sure that this user can read yourconfig.yml. - Check the precedence of your settings.
config.ymlnow overrides the defaults of the container (DB_*andREDIS_*variables,push_server_url). UseKANTREE_<SETTING>variables to overrideconfig.yml. - Check your configuration:
docker compose run --rm app check-config. - 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. - 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 andpostgres: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
- Expect users to log in again. Sessions created before Kantree 11 are not accepted.
- 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. - Read the logs for
is deprecatedwarnings (docker compose logs app | grep "is deprecated"), and rename these settings. - Configure AI. The
ai_providerandai_api_keysettings 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 ofmigrate-configgives thecreate-ai-providercommand to run. - 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.
- While the previous version runs, save the database:
docker compose exec postgres pg_dump -U kantree -Fc kantree > kantree.dump. - Save the uploaded files:
docker compose cp app:/uploads ./uploads-backup. - Save the Redis data:
docker compose exec redis redis-cli save, thendocker compose cp redis:/data/dump.rdb ./dump.rdb. - Stop the previous version:
docker compose down. - Replace the files with the files of Kantree 11. Write
KANTREE_SECRET_KEYin the.envfile. Migrate your configuration (see Migrating the configuration files). - Create the new containers and volumes:
docker compose up --no-start. - Copy the data back:
docker compose cp ./uploads-backup/. app:/uploads, thendocker compose cp ./dump.rdb redis:/data/dump.rdb. - Give the files to the new user:
docker compose run --rm --user root --entrypoint chown app -R 65532:65532 /uploads. - Restore the database:
docker compose up -d postgres, thendocker compose exec -T postgres pg_restore -U kantree -d kantree --no-owner < kantree.dump. - Check the configuration and preview the renamed accounts:
docker compose run --rm app check-config, thendocker compose run --rm app preview-user-dedup. - 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.ymlin the container. Inside the container,localhostis the container itself: indatabase_uriandredis_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
/uploadsvolume (docker compose cp /path/to/uploads/. app:/uploadsafterdocker compose up --no-start), and removeupload_dirfrom yourconfig.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-configline. - 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.envfile: rename them with the tables below - the AI settings: it gives the
create-ai-providercommand 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.