Migrate a legacy Docker Compose installation

Use this guide when the existing installation has a docker-compose.yml with services such as app, db, and minio, or when it has historically been updated with docker compose pull. This is a one-time layout migration. It is not the same as a routine upgrade of an installation that already uses docker-compose.prod.yml and ./casebender upgrade.

Do not continue without a tested PostgreSQL restore and a verified attachment backup. Never run ./casebender init, replace the existing .env, rotate an existing encryption or audit key, or run docker compose down -v.

What changes

Area	Legacy installation	Signed bundle
Compose file	`docker-compose.yml`	`docker-compose.prod.yml`
Web service	`app`	`web`
PostgreSQL service	`db`	`postgres`
Image selection	Often `latest`	Version pinned by `release.env`
Upgrade command	Often raw Compose commands	`./casebender upgrade`
Attachments	Usually MinIO in `miniodata`	Local `/data` in `casebender_data`, or an external object store
License key	Often `casebender_secret`	`LICENSE_SECRET_KEY` in `.env`
Audit integrity	May be absent	Stable `AUDIT_INTEGRITY_SECRET` in `.env`

Docker Compose prefixes named volumes with the Compose project name. Keeping the same installation directory and project name normally lets the signed bundle reuse pgdata and redis_data. A different directory or -p value creates different volume names and can make the application appear empty even though the original data still exists.

Phase 1: Inventory the existing installation

Run these commands from the existing installation directory:

pwd
docker compose ls
docker compose config --services
docker compose config --volumes
docker compose ps
docker volume ls

Record:

the Compose project name and installation directory;
the exact CaseBender image tags;
the PostgreSQL image and major version;
the actual volume names mounted at /var/lib/postgresql/data, /data, and /app/apps/web/app/secret;
whether attachments use MinIO, local storage, or an external provider;
the current database user, database name, and internal hostname;
the current TLS and reverse-proxy configuration.

Inspect mounts without printing environment secrets:

docker inspect "$(docker compose ps -q db)" \
  --format '{{range .Mounts}}{{println .Name "->" .Destination}}{{end}}'
docker inspect "$(docker compose ps -q app)" \
  --format '{{range .Mounts}}{{println .Name "->" .Destination}}{{end}}'

Check required keys by name only:

for key in \
  AUTH_SECRET AUTH_SALT NEXTAUTH_SECRET LICENSE_SECRET_KEY \
  FIELD_ENCRYPTION_KEY CREDENTIAL_ENCRYPTION_KEY \
  WEBHOOK_KEY_PEPPER CONNECTOR_BUNDLE_SIGNING_KEY OAUTH_BROKER_SECRET \
  AUDIT_INTEGRITY_SECRET POSTGRES_PASSWORD REDIS_PASSWORD; do
  if grep -q "^${key}=." .env; then
    printf '%s: configured\n' "$key"
  else
    printf '%s: missing\n' "$key"
  fi
done

Do not paste .env, license keys, encryption keys, database URLs, or backup contents into tickets or chat.

Phase 2: Create and test the recovery set

PostgreSQL

Create a logical backup using the legacy db service:

mkdir -p migration-backup
chmod 700 migration-backup

docker compose exec -T db \
  sh -c 'pg_dump -Fc -U "$POSTGRES_USER" "${POSTGRES_DB:-casebender}"' \
  > "migration-backup/casebender-$(date +%F).dump"

test -s "migration-backup/casebender-$(date +%F).dump"
docker run --rm -i postgres:17 pg_restore --list \
  < "migration-backup/casebender-$(date +%F).dump" >/dev/null

The final proof is a restore into an isolated staging database followed by application validation. Listing the archive is not a restore rehearsal. Record baseline counts for users, organizations, cases, alerts, tasks, attachments, evidence, and audit records. Use approved read-only queries for the deployed schema.

Configuration, TLS, and secrets

cp -p .env "migration-backup/.env.$(date +%F)"
cp -p docker-compose.yml "migration-backup/docker-compose.yml.$(date +%F)"
cp -p nginx.conf "migration-backup/nginx.conf.$(date +%F)" 2>/dev/null || true

Store the backup outside the Docker host in the approved encrypted recovery system. Include:

.env;
TLS certificates, private keys, and custom trust stores;
the exact license secret and license blob;
field and credential encryption keys;
webhook, connector-signing, OAuth, authentication, and audit secrets;
integration configuration and proxy/egress settings;
the current Compose file and image inventory.

If LICENSE_SECRET_KEY is absent from .env, preserve the existing value before stopping app:

umask 077
docker compose exec -T app \
  sh -c 'cat /app/apps/web/app/secret/license_secret_key' \
  > migration-backup/license_secret_key
test -s migration-backup/license_secret_key

Transfer that value into the protected LICENSE_SECRET_KEY entry during the environment transformation. Do not print it.

Attachments

If STORAGE_PROVIDER=minio, back up the bucket through the S3/MinIO API. A tarball or direct copy of MinIO’s internal miniodata layout is a disaster recovery snapshot, not a valid local-storage migration. Keep both:

a snapshot or archive of the original miniodata volume; and
an object-level export made with mc mirror or your approved S3 backup process.

Compare the exported object count and size with the source, then download several known case attachments and evidence files from the rehearsal system.

Phase 3: Check alert-promotion compatibility

The new release enables alert-to-case promotion by default. Keep it explicitly disabled during a legacy-data migration:

ENTERPRISE_ALERT_PROMOTION=disabled

Check the schema and legacy observable parentage:

SELECT to_regclass('"AlertPromotionOperation"') AS promotion_table;

SELECT count(*) AS dual_parent_observables
FROM "Observable"
WHERE "alertId" IS NOT NULL
  AND "caseId" IS NOT NULL;

SELECT EXISTS (
  SELECT 1
  FROM pg_constraint
  WHERE conname = 'Observable_at_most_one_parent_check'
) AS parent_constraint_installed;

Stop and use the release-specific promotion backfill procedure when:

the promotion table is missing;
any dual-parent observable exists; or
backfill verification is not clean.

Do not enable promotion until the schema migration is applied, dual-parent conflicts are zero, the parent constraint decision is verified, and the worker outbox processor is healthy.

Phase 4: Choose the attachment target

Option A: Continue using an external MinIO or S3-compatible service

This minimizes application-level storage change. The object store must remain reachable from the new web container. Set:

STORAGE_PROVIDER=minio
MINIO_ENDPOINT=minio.internal.example
MINIO_PORT=9000
MINIO_USE_SSL=true
MINIO_ACCESS_KEY=existing-access-key
MINIO_SECRET_KEY=existing-secret-key
MINIO_BUCKET=casebender

MINIO_ENDPOINT is a hostname, not a URL. Use a trusted TLS endpoint for production. The signed bundle does not run an embedded MinIO container, so an external endpoint must exist before cutover.

Option B: Migrate MinIO objects to local `/data`

Create the target volume with the same Compose project name:

PROJECT_NAME="$(docker compose ls --format json |
  node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{const v=JSON.parse(s);console.log(v[0]?.Name??"")})')"
test -n "$PROJECT_NAME"
docker volume create "${PROJECT_NAME}_casebender_data"

Use mc mirror or an equivalent object-level export to write each bucket object under the same object key in casebender_data. Do not copy MinIO’s internal volume files directly. Set:

STORAGE_PROVIDER=local
STORAGE_PATH=/data
MINIO_ENDPOINT=

Validate object counts, total bytes, and representative downloads in staging. Retain the original miniodata backup through the rollback window.

Phase 5: Prepare `.env` for the signed bundle

Start from the existing .env; do not start from .env.example and do not run ./casebender init.

Variable	Migration action
`POSTGRES_USER`	Preserve the existing user, commonly `superadmin`
`POSTGRES_PASSWORD`	Preserve exactly
`POSTGRES_DB`	Preserve exactly
`POSTGRES_PRISMA_URL`	Change only hostname `db` to `postgres`
`POSTGRES_URL`	Change only hostname `db` to `postgres`
`POSTGRES_URL_NON_POOLING`	Change only hostname `db` to `postgres`
`REDIS_PASSWORD`	Add a strong installation-specific value if absent
`REDIS_URL`	Use `redis://:<password>@redis:6379`
`OPENSEARCH_PASSWORD`	Add a strong installation-specific value required by the production Compose definition
`LICENSE_SECRET_KEY`	Preserve the value recovered from `.env` or `casebender_secret`
`AUDIT_INTEGRITY_SECRET`	Preserve if present; otherwise generate once during managed preparation
Encryption and signing keys	Preserve existing values and legacy fallbacks
`NEXTAUTH_URL`, `NEXTAPP_URL`	Preserve the customer URLs
`DEPLOYMENT_PROFILE`	Set to `onprem` unless enterprise is licensed and prepared
`CASEBENDER_LEGACY_BOOTSTRAP`	Set to `false`
`ENTERPRISE_ALERT_PROMOTION`	Keep `disabled` until compatibility checks pass

The release’s ./casebender upgrade copies CASEBENDER_RELEASE_VERSION and CASEBENDER_REGISTRY from the verified release.env, and backfills missing audit and integration secrets. Never replace an existing value during a routine migration. Update NO_PROXY for the new internal names, including postgres, redis, web, api, worker, and other enabled services.

Phase 6: Rehearse the complete migration

Restore copies of PostgreSQL, attachments, .env, and secrets into an isolated network. Use the same PostgreSQL major version as the source. In rehearsal:

verify and extract the signed bundle;
preserve the intended Compose project name;
apply the .env, TLS, database-hostname, Redis, storage, and license changes;
run preflight;
start the pinned release;
verify migrations and service health;
compare baseline database and attachment counts;
validate login, cases, alerts, tasks, attachments, evidence, credentials, integrations, audit writes, and backups;
complete the alert-promotion backfill checks before enabling promotion;
record the actual recovery point and recovery time.

Do not connect the rehearsal environment to production integrations.

Phase 7: Production cutover

Announce a maintenance window and stop inbound integrations and user writes.
Take fresh final PostgreSQL and attachment backups.
Preserve the legacy Compose file as docker-compose.legacy.yml.
Verify and copy the new bundle files into the same installation directory.
Preserve .env and apply the reviewed transformation.

Install trusted TLS files at:

deploy/nginx/ssl/fullchain.pem
deploy/nginx/ssl/privkey.pem

Stop the legacy stack without deleting volumes:

docker compose -f docker-compose.legacy.yml down

Run:

./casebender preflight
./casebender upgrade
./casebender logs

Keep ENTERPRISE_ALERT_PROMOTION=disabled until post-migration schema and backfill verification passes. Then remove the override or set it to enabled, recreate the caller services, and test a non-critical promotion.

Phase 8: Validate and close the migration

Confirm:

every expected container is healthy;
the deployment remains ACTIVE and existing users can sign in;
baseline users, organizations, cases, alerts, tasks, audit records, and attachment counts match;
representative attachments and evidence download correctly;
stored integration credentials still decrypt and a safe connection test succeeds;
Redis, worker queues, and the alert-promotion outbox are healthy;
updating a non-critical alert creates an audit entry without an integrity error;
creating and merging a non-critical alert into a case succeeds after promotion is enabled;
the deployment can produce a new backup.

Run the release canary:

node scripts/deployment/canary-check.mjs \
  https://casebender.your-company.example

Retain the legacy Compose file, previous image manifest, original .env, database dump, object-store backup, and volume snapshots until the approved rollback window closes.

Rollback

Before starting the signed bundle, restart the legacy Compose file against the untouched volumes if rehearsal or preparation fails. After database migrations run:

use ./casebender rollback --confirm-schema-compatible only when the release notes explicitly permit image-only rollback;
otherwise stop the new stack, restore the matching pre-migration PostgreSQL and attachment backups, restore the legacy .env and Compose file, and start the previous pinned images.

Never run an older application image against an unsupported newer schema. After this one-time migration succeeds, follow Upgrading CaseBender for future releases.

Getting Started

Deployment

Alert Management

Case Management

Task Management

Time Tracking

Analytics

Audits

Settings

Migrate a Legacy Docker Compose Installation

Migrate a legacy Docker Compose installation

What changes

Phase 1: Inventory the existing installation

Phase 2: Create and test the recovery set

PostgreSQL

Configuration, TLS, and secrets

Attachments

Phase 3: Check alert-promotion compatibility

Phase 4: Choose the attachment target

Option A: Continue using an external MinIO or S3-compatible service

Option B: Migrate MinIO objects to local `/data`

Phase 5: Prepare `.env` for the signed bundle

Phase 6: Rehearse the complete migration

Phase 7: Production cutover

Phase 8: Validate and close the migration

Rollback

​Migrate a legacy Docker Compose installation

​What changes

​Phase 1: Inventory the existing installation

​Phase 2: Create and test the recovery set

​PostgreSQL

​Configuration, TLS, and secrets

​Attachments

​Phase 3: Check alert-promotion compatibility

​Phase 4: Choose the attachment target

​Option A: Continue using an external MinIO or S3-compatible service

​Option B: Migrate MinIO objects to local /data

​Phase 5: Prepare .env for the signed bundle

​Phase 6: Rehearse the complete migration

​Phase 7: Production cutover

​Phase 8: Validate and close the migration

​Rollback

Migrate a legacy Docker Compose installation

What changes

Phase 1: Inventory the existing installation

Phase 2: Create and test the recovery set

PostgreSQL

Configuration, TLS, and secrets

Attachments

Phase 3: Check alert-promotion compatibility

Phase 4: Choose the attachment target

Option A: Continue using an external MinIO or S3-compatible service

Option B: Migrate MinIO objects to local `/data`

Phase 5: Prepare `.env` for the signed bundle

Phase 6: Rehearse the complete migration

Phase 7: Production cutover

Phase 8: Validate and close the migration

Rollback