Administrator guide
Back up and restore
Create a self-contained recovery bundle, verify it before trust, and restore only the data and artifacts you intend.
A backup is not trustworthy just because a command returned success. OpenCircle writes the bundle manifest last and provides a separate read-only verifier for structure, checksums, database dumps, image identity, and file permissions.
This page covers local or SSH Docker Compose profiles. Railway uses its own protected upgrade-and-resume path — do not run these commands against a Railway deployment.
Create and verify a full bundle
Choose an off-host destination and the exact profile from your deployment receipt — never rely on whichever profile happens to be active:
Terminal
export OPENCIRCLE_PROFILE=circle-local export OPENCIRCLE_RECOVERY_BUNDLE=/path/to/off-host-storage/circle-YYYYMMDD-HHMMSS opencircle backup "$OPENCIRCLE_RECOVERY_BUNDLE" --profile "$OPENCIRCLE_PROFILE" opencircle backup verify "$OPENCIRCLE_RECOVERY_BUNDLE" --profile "$OPENCIRCLE_PROFILE"
A successful verification ends with result: OK and reports the bundle's profile, instance ID, and Compose project. The report itself is secret-redacting, but the bundle can still contain databases and configuration — store and move it accordingly.
Restore deliberately
Before restoring, compare the verifier's bundle instance ID with the live target's whoami instance ID, and confirm the destination profile and Server URL are the ones you intend:
Terminal
opencircle backup verify "$OPENCIRCLE_RECOVERY_BUNDLE" --profile "$OPENCIRCLE_PROFILE" opencircle whoami --profile "$OPENCIRCLE_PROFILE" --format json opencircle restore "$OPENCIRCLE_RECOVERY_BUNDLE" --profile "$OPENCIRCLE_PROFILE"
A healthy, already-set-up target requires an explicit --force on the same command — that flag authorizes overwrite, it does not make the chosen bundle correct.
| Restore mode | Recovers | Does not recover |
|---|---|---|
| default | Databases, selected persistent bytes, operator state, and stack bring-up | External provider accounts, DNS ownership, lost SSH authority |
| --data-only | Databases | Persistent artifact and media bytes |
| --artifacts-only | Persistent artifact and media volumes | Databases |
Restore is destructive. Preserve the current target before overwriting it, and never use --force to silence an identity mismatch you have not explained.
What backups do not provide
Backups do not provide automatic high availability or failover. Same-host rollback depends on the retained prior image and verified bundle, and host-loss recovery depends on independent, off-host retention.