Skip to main content

​
Release cadence and supported versions

Datris ships small releases often — typically several per month — and every release is tagged, published to Docker Hub as multi-architecture images, and described in the changelog. There is no separate stable and unstable line: latest is the current release. Run the pre-upgrade self-check before every upgrade — it catches the things that turn an upgrade into an outage and prints the fix for each.

​
Upgrade procedure

Upgrading means two things: pulling the latest pre-built images and refreshing the Compose file itself, since a new release can rename, add, or drop services. How you do it depends on how you installed. In every case your data is preserved — it lives in Docker volumes that survive an upgrade. Step 0 — check the deployment first. From the directory holding your docker-compose.yml and .env, run the pre-upgrade self-check. It catches the things an upgrade turns into an outage: data on an anonymous volume that --remove-orphans would drop, a missing AI slot secret the new server would crash-loop on, a disk too full to pull images, a container still running with a stale .env. Nothing is changed; it prints the fix for each finding and the upgrade command when the deployment is clean. See Doctor.
Installer (the curl … | sh Quick Start): just re-run the install command. It re-downloads the latest compose file and runtime scripts, leaves your .env and data untouched, pulls the new images, and restarts. When the datris CLI is on the machine it runs step 0 for you first: a warning continues, an error stops the upgrade with the fix on screen (DATRIS_SKIP_DOCTOR=1 bypasses it).
Single-file (docker-compose.standalone.yml): re-download the file (it carries the latest topology and inlined scripts), then pull and restart.
From source (cloned repo): pull the latest compose file from git, then pull images and restart.
No build tools required for any of these — the images come pre-built from Docker Hub.
Always pass --remove-orphans when upgrading manually. (The installer does this for you.) Releases occasionally rename, remove, or repurpose service blocks in docker-compose.yml (e.g. v1.6.15 replaced the bundled Ollama service with TEI on the same host port 11434). Without --remove-orphans, the previous version’s container keeps running and holding the port, causing the new container to fail with Bind for 0.0.0.0:<port> failed: port is already allocated. The flag is safe — it only removes containers that are no longer defined in your current compose file. Volumes (and your data) are untouched.
Your data is preserved across upgrades — Postgres pipelines, Vault secrets, MinIO buckets, MongoDB collections, and Kafka state all live in Docker volumes that survive docker compose pull and docker compose up -d.

​
Stale secrets after an upgrade

Datris occasionally deprecates secret paths between versions (for example, v1.5.6 split AI configuration into three new Vault slots and stopped reading the old single-slot path). Because Vault data persists across upgrades, deprecated entries stay in Vault and continue to appear in the Configuration → Secrets list even though the server ignores them. To clean them up:
  • Targeted (preserves your data): delete the stale entries one at a time from Configuration → Secrets in the UI, or run docker compose exec -e VAULT_TOKEN="$(docker compose exec -T datris cat /vault-token/token)" vault vault kv delete secret/oss/<name> for each deprecated path.
  • Total reset (destroys all data): see the next section.

​
Roll back

Every release is also published under its version tag, so rolling back is pinning the four image: lines in your Compose file to the version you were on (for example datrisai/datris-server:v1.28.2, and likewise datris-ui, datris-mcp-server, and datris-tap-runner), then docker compose up -d. Data written by the newer version stays in place; whether the older version reads it depends on what changed — check the changelog entry for the release you are backing out of before rolling back across one that migrated a store.