Deployment & Operations

Upgrades

How to move an instance to a newer version of lazyit. Upgrades are routine — pull the new code, rebuild the images, bring the stack up — but always back up first, because database migrations are forward-only.

Before you upgrade

Back up both databases and the environment file first. Database migrations only move forward — there is no automatic rollback. Your safety net is the pre-upgrade backup. See Backups & restore.

The upgrade

From the repository root:

git pull          # or ship a new built artifact / image
docker compose -f compose.yaml -f infra/docker-compose.prod.yaml \
  --profile prod --env-file infra/env/.env.prod up -d --build

The rebuild brings up the new images, and the one-shot migrate job re-runs automatically before the API starts — applying any new database migrations (a no-op if there’s nothing pending). You don’t run migrations by hand.

Support policy

Only the latest release is supported — stay current. You do not have to install versions one at a time: jumping across several releases at once (say 1.2 → 1.9) in a single upgrade is safe, because the one-shot migrate job applies every pending database migration in order. The one exception is a major version in the range. A major always ships with a ⚠️ Upgrade actions section in its release notes describing a manual step you must perform (a new required setting, a topology change). So jump freely across patch and minor releases, but stop and read the Upgrade actions for each major you cross. The running version is shown on Settings → Instance.

Deprecated features

When a feature, setting, endpoint, or import/export format is being retired, it is deprecated in a minor release first — the release notes say “deprecated, will be removed in X.0” — and it keeps working until then. It is removed only in the next major, listed in that major’s ⚠️ Upgrade actions (which you already read before upgrading). So a minor upgrade never removes something you depend on; watch the release notes for deprecations and plan the swap before the next major.

New required settings after a pull

A version that adds a feature may introduce a new required environment value. The guided bootstrap only writes new values on a fresh render — it never edits an existing environment file — so after pulling a version that needs one, add it by hand and recreate the affected service. Two examples that have shipped:

The background-job broker URL (REDIS_URL), required since background workers shipped. If it’s missing, background document import fails.

grep -q '^REDIS_URL=' infra/env/.env.prod || echo 'REDIS_URL=redis://valkey:6379' >> infra/env/.env.prod
docker compose -f compose.yaml -f infra/docker-compose.prod.yaml --profile prod \
  --env-file infra/env/.env.prod up -d api

The workflow secret key (WORKFLOW_SECRET_KEY), required before enabling the Applications Workflow Engine. The API fails loud at boot if the engine is enabled and the key is missing or the wrong length.

grep -q '^WORKFLOW_SECRET_KEY=' infra/env/.env.prod \
  || echo "WORKFLOW_SECRET_KEY=$(openssl rand -hex 32)" >> infra/env/.env.prod
docker compose -f compose.yaml -f infra/docker-compose.prod.yaml --profile prod \
  --env-file infra/env/.env.prod up -d api

The workflow secret key is an unrotatable key, like the identity-provider master key: it decrypts stored connector credentials. Back it up off-host and never generate a fresh one on a restore, or those credentials become undecryptable. See Backups & restore.

Release notes call out any new required value. When in doubt, compare your environment file against the shipped example (infra/env/.env.prod.example) for newly added entries.

Rolling back

There is no automatic rollback. To go back to a previous version, restore the pre-upgrade database backup and redeploy the previous image. This is exactly why the pre-upgrade backup is mandatory.

Bundled component versions

The bundled images (database, identity provider, search, broker, proxy) are pinned to specific versions for reproducible deploys. They move only on a deliberate bump. Before bumping the identity provider in particular, back up its database and keep the matching master key, since its data is tied to that key.