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.
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

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)

1

Back up your database and .env

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

Obtain and verify the new Community bundle

Download the public versioned archive, checksum, and Sigstore bundle linked from the CaseBender Quickstart. Download the matching release manifest and retain it with the change record. Do not clone the private source repository.
Confirm the extracted release-manifest.json contains the intended version, source commit, and seven signed image digests. Review the release notes for migration requirements and rollback compatibility.
3

Update deployment files in place

Keep the same installation directory and Compose project. Copy the new deployment files into it, but do not replace .env or delete any volumes.
If Nginx configuration changed in the release, review and merge it with your site-specific TLS and proxy configuration.
4

Run the managed upgrade

This makes a .env.pre-upgrade backup, copies the pinned release metadata into .env, preserves an existing AUDIT_INTEGRITY_SECRET or generates it once for an older installation, runs preflight, pulls the exact images, and recreates containers without building source. For preloaded air-gapped images, use ./casebender upgrade --offline.Do not replace the generated value on later upgrades. Include .env and .env.pre-upgrade in the protected backup set.
5

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 copy the verified release files and run ./casebender upgrade.
  • 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.

​
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.