Skip to main content

Updates and Scaling

Day-two operations: getting new releases in, and giving Kanera more room as the team grows.

Updates​

Each Kanera release is a tagged version such as v1.9.0 with its own docker-compose.yml. Updating means swapping in the new release's compose file and pulling its images. You can skip releases: going from v1.9.0 straight to v1.12.0 is fine, because every pending database migration runs in order during the update.

Update to the latest release​

From your kanera directory on the server:

docker compose exec -T postgres pg_dump -U kanera kanera | gzip > kanera-$(date +%F).sql.gz
cp docker-compose.yml docker-compose.previous.yml
curl -fsSLo docker-compose.yml https://github.com/happendev/Kanera/releases/latest/download/docker-compose.yml
docker compose pull
docker compose up -d
docker compose logs migrate

Before you run it, read the release notes for every release between your version and the new one. A change that needs action, such as a new setting or a one-time reconnect, is listed under the release that introduced it, so going from v1.9.0 to v1.12.0 means reading the 1.10.0, 1.11.0, and 1.12.0 notes.

To move to a specific release instead of the latest, download its compose file by tag:

curl -fsSLo docker-compose.yml https://github.com/happendev/Kanera/releases/download/v1.9.0/docker-compose.yml

Check which version you're running​

docker compose images api

The TAG column shows the release, for example 1.9.0. The first line of docker-compose.yml names it too.

Before updating​

  • Back up the database and uploads. The pg_dump above covers the database; the kanera_uploads volume needs its own copy. Keep both, plus your .env, off the server's primary disk. See Storage and Backups.
  • Keep the previous compose file. The cp above saves it as docker-compose.previous.yml, which is what you need to roll back.
  • Keep your changes out of docker-compose.yml. The update replaces that file. Put ports, extra networks, or other local changes in a docker-compose.override.yml next to it; Compose merges it automatically and updates leave it alone.
  • Make sure the current deployment is healthy. An update should not hide an existing database, storage, or routing problem.

Verify the update​

docker compose images api
docker compose ps --all
docker compose logs --tail=100 api worker public-api mcp
curl https://kanera.example.com/api/health

The api image should show the new version, and migrate should show as exited with code 0. Also check the public API and MCP health endpoints if you expose them. Then sign in, open a populated board, and create and delete a temporary card.

If an update fails​

  • The migration did not start: fix the Compose or environment error and rerun docker compose up -d.
  • The migration failed: keep the logs and the backup, and do not rerun it repeatedly without understanding the error. Open an issue with the migrate logs.
  • You need to go back: an older release cannot run against a database the newer one has migrated. Stop Kanera (docker compose down), restore the pre-update database and uploads together, put the previous compose file back (mv docker-compose.previous.yml docker-compose.yml), and run docker compose up -d.
  • Never restore a backup over a running newer version. Test your restore procedure on a separate database or host before you rely on it.

Scaling notes​

The default deployment uses multiple app API replicas and one worker.

  • API_REPLICAS controls app API process count. Defaults to 2.
  • PUBLIC_API_REPLICAS controls public API process count. Defaults to 1.
  • MCP_REPLICAS controls MCP process count. Defaults to 1.
  • Keep worker at exactly 1.
  • Valkey is required for realtime fanout, presence, and shared rate limits.

Raise replicas only when the server has enough CPU, memory, and database connection capacity. If you raise API_REPLICAS, review PG_POOL_MAX and PostgreSQL max_connections.

The single worker is deliberate. It runs schedulers, notification and webhook delivery, and cleanup jobs, and a second copy would duplicate that work rather than share it. If delivery is falling behind, look at database and outbound network capacity before considering more worker processes.