Skip to main content

​
Overview

CaseBender ships as a public, source-free Community release bundle and a matching set of versioned container images. Customers do not need access to the private source repository. Upgrading means verifying the new bundle, updating the deployment files in the existing installation directory, pulling the pinned images, and recreating the containers. Data and configuration remain in named Docker volumes and .env. Use a pinned target version. Never change a production deployment to a mutable latest tag during an upgrade.
If the current installation uses docker-compose.yml with app, db, or an embedded MinIO service, first follow Migrate a Legacy Docker Compose Installation. The procedure below is only for installations already managed by the signed bundle.
Database migrations and default-data seeding run automatically on startup after every upgrade. You do not need to run any migration commands manually.

​
What persists across upgrades

Paid licenses are bound to the Installation ID. After an upgrade, confirm Settings → License or ./casebender license still shows the same ID. See License. Do not send LICENSE_SECRET_KEY to CaseBender to request a paid key.
Never run docker compose down -v on a production system. The -v flag deletes all named volumes — your database, license, and files. Without those volumes, the next start creates a fresh database and a new activation state.

​
Upgrade procedure (Docker Compose)

Run the commands from the existing installation directory. Do not copy release.env, Compose files, or the CLI by hand. ./casebender upgrade applies the signed bundle (CLI, Compose, Nginx stock file, preflight/canary, release.env, and release-manifest.json) and never overwrites .env.
1

Back up your database and .env

Verify that the backup can be read and store it outside the Docker host.
2

Apply the signed bundle

On a connected host, download, verify (SHA-256 and Cosign), and apply a pinned version in one command. v1.0.9 is also accepted. Never use latest.
The default download base is the public CaseBender Blob store used by the Quickstart. Override it with CASEBENDER_RELEASE_BASE_URL when you mirror artifacts internally. Cosign must be installed for a --version upgrade.On an air-gapped host, sneakernet the versioned archive (and, if you have them, the .sha256 and .sigstore.json sidecars). Then apply the local tar. Inner SHA256SUMS is required. Cosign runs only when a .sigstore.json sidecar sits next to the archive.
Bare ./casebender upgrade does not pull images. It prints the current pin and the two commands above. To pull and recreate the current pin after a failed recreate, use ./casebender upgrade --reapply (add --offline when images are already loaded).If this installation’s CLI does not accept --version, copy only casebender from the verified bundle into this directory once, then rerun the command.The managed path writes .env.pre-upgrade, copies pinned release metadata into .env without replacing secrets, preserves an existing AUDIT_INTEGRITY_SECRET or generates it once for an older installation, runs preflight, pulls the exact images unless --offline, and recreates containers without building source.The command then waits for web, api, and ingestion to report healthy (database migrations finish before web becomes healthy), recreates the Nginx container so it resolves the new application containers, and checks /api/health and /api/v1/health through Nginx. It reports success only after those checks pass. The default wait is 10 minutes. Set CASEBENDER_READY_TIMEOUT_SECONDS for releases with long migrations. On failure the command exits non-zero, keeps all volumes and .env, and prints the retry and rollback commands.If deploy/nginx/nginx.conf was customized, the CLI writes nginx.conf.pre-upgrade and installs the stock release file. Re-apply site TLS and proxy settings from that backup. Include .env and .env.pre-upgrade in the protected backup set.
3

Watch the logs

Migrations and seeding run on boot — wait for the app to report healthy.

​
Verify after upgrading

  • Sign in and confirm your existing cases, alerts, and users are present.
  • Confirm your login still works (your admin password is unchanged).
  • Confirm the deployment remains ACTIVE; an existing installation must not display /setup.
  • Confirm organization, role, TLP, API-key scope, and integration egress checks.
  • Update a non-critical test alert and verify its audit entry appears without an integrity configuration error.
  • Check the worker is processing jobs:
Run the automated canary:

​
Rollback

Do not start older application images against a schema that they do not support. Use the release note’s declared rollback path. When the release notes explicitly confirm backward schema compatibility, the managed rollback restores the previous immutable image pin saved immediately before the upgrade:
For an air-gapped host whose previous images are still loaded, add --offline. The command preserves the failed release configuration as .env.pre-rollback. If a database migration is not backward compatible, do not use image-only rollback. Stop the stack and restore the pre-upgrade database and matching volumes before starting the previous pinned image set:
Always upgrade a staging environment first, and take a fresh database backup immediately before upgrading production.

​
Common upgrade mistakes

The two most common problems both come from losing state:
  • Changing the Compose project name or directory. Docker derives volume names from the project. Renaming the folder or using a different -p project name points Compose at new, empty volumes. Always upgrade from the same directory/project so your existing volumes are reused.
  • Replacing .env. The bundle’s release.env contains only pinned release metadata. It must not replace the installation’s secret-bearing .env.
  • Running only docker compose pull. A raw image pull bypasses managed secret recovery, release pinning, preflight, and backup creation. Always run ./casebender upgrade --version <id> or ./casebender upgrade --offline ./casebender-onprem-vX.Y.Z.tar.gz.
  • Rotating AUDIT_INTEGRITY_SECRET. A new value cannot verify audit entries written with the previous key. Preserve the installation-specific value across upgrades, rollbacks, and restores.
  • Recreating an application container without Nginx. Nginx resolves web, api, and ingestion only when it starts. If one of those containers is recreated outside ./casebender up, upgrade, or rollback (for example with a raw docker compose up), Nginx keeps the old address and cannot reach the application. Recreate only the proxy; no data is touched:

​
Activation compatibility

The activation migration is idempotent:
  • databases with existing users become ACTIVE;
  • existing passwords, users, roles, organizations, cases, and API keys are not changed;
  • no second administrator is created; and
  • only a genuinely empty installation enters first-run activation.
Validate this behavior against a sanitized copy of each supported customer database before promotion.

​
Desktop Installer

If you deployed with the Desktop Installer, use the app’s built-in update flow — it pulls the latest images and recreates services while preserving your data directory, .env, and license key.

​
Google Cloud Run

Cloud Run upgrades deploy a new revision. Because Cloud Run has an ephemeral filesystem, the license secret must be provided via Secret Manager as LICENSE_SECRET_KEY so it persists across revisions. Redeploy against your existing Cloud SQL instance and secrets:
Migrations run automatically on the new revision.