Updating and Release Channels

Updating & Release Channels

Docker Compose (CLI)

Change IMAGE_TAG in .env and redeploy, or use the in-app "Update now" button (admin console) — it's wired to the updater service, which has Docker socket access and pulls + redeploys automatically. Requires UPDATER_SHARED_SECRET set (see Configuration Reference); without it, the admin console still shows "update available" notices from the periodic check, just without a one-click trigger.

An in-app update:

1. pulls the new api, worker, migrate and updater images,
2. runs the database migrations,
3. restarts api and worker (never db or resolver),
4. writes the new IMAGE_TAG into your .env — so a later manual docker compose up -d keeps the new version instead of going back to the old one,
5. replaces the updater itself with the new image.

It only accepts a real release tag newer than the running version.

Upgrading from v0.1.4 or older (or v0.1.5-beta9 and earlier): the updater in those versions can't replace itself yet, so do that one upgrade from the host:

git pull   # docker-compose.yml now mounts .env writable into the updater
sed -i 's/^IMAGE_TAG=.*/IMAGE_TAG=<new tag>/' .env
docker compose pull api worker migrate updater
docker compose run --rm --no-deps migrate
docker compose up -d --no-deps api worker updater

Portainer Stacks

Change the IMAGE_TAG environment variable and redeploy the stack — Portainer re-pulls the image. The in-app "Update now" button doesn't apply here; docker-compose.portainer.yml omits the updater service entirely.

Azure Container Apps

Use Update now in the admin console, the same as on Docker Compose. It starts the deployment's updater job, which runs the database migrations, then moves the worker, the api and itself to the new release. The api's identity can only start that job; the job's own identity is limited to this resource group's container apps and jobs. Details: deploy/azure/README.md.

Run test update on the same page runs every update step on the version you already run: a safe way to check the Azure permissions before a real update. It's off by default; turn it on with UPDATE_REHEARSAL_ENABLED=true on the api (or enableTestUpdate=true when redeploying).

Deployments from before v0.1.5-rc2 don't have the updater job yet: redeploy once with the new imageTag (button or az deployment group create with your original parameters). After that, Update now works.

Redeploying with a new imageTag also still works, and is what applies changes to the template itself.

Release channels and version numbers

• Feature releases raise the middle number: v0.2.0, v0.3.0, … They go through vX.Y.Z-betaN → vX.Y.Z-rcN → vX.Y.Z, and the work happens on its own vX.Y.Z-beta branch until it's promoted to main.
• Patch releases raise the last number: v0.1.6, v0.1.7, … Fixes only, for the latest feature release, so a fix doesn't have to wait for (or come with) the next round of features.

main tracks the latest stable release. latest (the default IMAGE_TAG) tracks the newest published stable tag, not main's tip. Turn on Include prereleases under admin console → Updates to be offered betas and release candidates too.

---

← Production & Scaling · Home