Backup, restore, and migration¶

This guide is for self-hosted administrators. A useful backup must restore a working QuantDinger deployment, not merely produce a database file.

What to preserve¶

Asset	Required	Purpose
PostgreSQL database	Yes	Users, strategies, backtests, orders, and durable settings
`.env`	Yes	Ports, deployment mode, and external-service configuration
`CREDENTIAL_ENCRYPTION_KEY`	Yes	Decrypts saved broker, exchange, and provider credentials
Reverse-proxy and certificate configuration	Production	Domains, HTTPS, and proxy rules
Custom strategies, scripts, and mounted directories	As used	Assets outside the database and images
Image version or `IMAGE_TAG`	Recommended	Reproduces the runtime that created the backup

Never commit .env, keys, or database backups to Git. Encrypt backups and store them separately from the production host.

Create a consistent backup¶

Record the current services and images:

bash docker compose ps docker compose images

Export PostgreSQL in custom format:

bash mkdir -p backups docker exec quantdinger-db pg_dump -U quantdinger -Fc -d quantdinger -f /tmp/quantdinger.dump docker cp quantdinger-db:/tmp/quantdinger.dump ./backups/quantdinger.dump

Copy .env, proxy configuration, and custom mounts to encrypted backup storage.
Record the timestamp, QuantDinger version, database image version, and checksums.
Perform a restore drill in an isolated environment. A backup that has not been restored successfully is not yet proven.

For a busy production deployment, pause strategies and new job submission until the database export completes.

Restore into a new environment¶

Install Docker and a compatible QuantDinger version.
Restore .env, retaining the original CREDENTIAL_ENCRYPTION_KEY.
Start PostgreSQL and stop application services that can write to it.
Copy and restore the dump:

bash docker cp ./backups/quantdinger.dump quantdinger-db:/tmp/restore.dump docker exec quantdinger-db pg_restore -U quantdinger -d quantdinger --clean --if-exists /tmp/restore.dump

Run the target version's migrations and start the stack:

bash docker compose up -d migration docker compose up -d

Verify health, administrator login, strategy and backtest history, broker accounts, notifications, and queues in that order.

Restore into staging first whenever possible. Do not run docker compose down -v during recovery because it deletes data volumes.

Move to another host¶

Use an old-host backup, new-host restore, acceptance test, and traffic cutover:

Lower DNS TTL and record the old version.
Pause new strategies, schedules, and write entry points on the old host.
Create the final database backup and copy configuration and custom assets.
Restore on the new host and validate through a temporary domain.
Switch DNS or the load balancer and monitor health, logs, and order state.
Keep the old environment as a read-only rollback point until the new one is stable.

For a cross-version move, restore the old version first and then follow Upgrade and rollback. Do not attach a restored database to an unverified older application version.

Recurring checklist¶

Back up daily or according to the required recovery point objective.
Create a non-overwriting full backup before every upgrade.
Complete an isolated restore drill at least quarterly.
Verify checksums, encryption keys, and retention regularly.
Restrict backup credentials and audit download and restore operations.