Upgrade and rollback¶

Treat an upgrade as a reversible change, not as a simple pull. This workflow targets self-hosted Docker Compose deployments.

Before upgrading¶

Read the target release notes and identify database, configuration, and broker changes.
Record the current commit, image digest, IMAGE_TAG, and service state.
Back up the database, .env, CREDENTIAL_ENCRYPTION_KEY, and custom assets using Backup, restore, and migration.
Pause live strategies or enter a maintenance window; check for open orders and long-running jobs.
Rehearse with a sanitized production backup in staging.

Standard upgrade¶

For prebuilt images:

docker compose pull
docker compose up -d migration
docker compose up -d
docker compose ps

For a source deployment, check out the intended tag or commit and rebuild using the repository workflow. Pin production to a versioned tag rather than relying indefinitely on latest.

Validate in order:

/api/health and container health.
Administrator login, authorization, and system settings.
Data status, research, strategy compilation, and a small backtest.
Broker connectivity, account queries, and paper execution.
Queues, notifications, logs, disk usage, and error rate.

When to roll back¶

Stop expanding the change and evaluate rollback when health checks remain unhealthy, migrations fail, a core surface is unavailable, order or account state is inconsistent, error rate rises persistently, or critical queues accumulate.

Rollback methods¶

Application-image rollback only¶

Only when the database remains backward compatible, restore the previous IMAGE_TAG and restart:

docker compose pull
docker compose up -d

Incompatible database migration occurred¶

Stop all writers.
Restore both the pre-upgrade application version and full database backup.
Use the same .env and CREDENTIAL_ENCRYPTION_KEY.
Validate on an isolated address before restoring traffic.

Do not manipulate migration records manually to simulate a rollback, and never use docker compose down -v as part of rollback.

Change record¶

Record the operator, window, old and target versions, backup location, migration result, acceptance checks, rollback triggers, and final decision. For an incident, add a timeline and corrective actions.