Backup & Rollback
Automatic image backup before updates and one-click rollback to any previous version.
How It Works
Before every container update, drydock automatically backs up the current image metadata including the image name, tag, digest, and timestamp. This ensures you always have a record of exactly which image was running prior to each update.
These image-restore backup records live in the SQLite store in v1.9.0-rc.1 builds; v1.7 and earlier use the LokiJS JSON store. The /store volume persists them in either case. They describe container images, rather than snapshots of Drydock's database. Each container retains its N most recent backups, with older entries pruned automatically when the limit is exceeded.
Backup Retention
The number of backups retained per container is configurable via a trigger environment variable.
| Env var | Required | Description | Supported values | Default value when missing |
|---|---|---|---|---|
DD_ACTION_DOCKER_{trigger_name}_BACKUPCOUNT | ⚪ | Number of backups to retain per container | integer | 3 |
DD_ACTION_DOCKERCOMPOSE_{trigger_name}_BACKUPCOUNT | ⚪ | Number of backups to retain per container | integer | 3 |
Manual Rollback
Rollback is available in two ways:
- UI -- on the container detail page, select a previous backup and click Rollback. A shortcut is also available directly from the container's actions menu (the
...menu on each row). - API -- send a
POSTrequest to/api/v1/containers/:id/rollback, where:idis the container ID.
Rollback uses a stop-remove-recreate strategy: drydock stops the current container, removes it, and creates a new container with the original name using the backup image. The image is pulled and created from an immutable repo:tag@sha256:... reference whenever a digest can be established, so a registry retag between the backup and the rollback can't change what gets deployed. Backups written before digest capture existed resolve one from the retained local image at rollback time; if none can be established and the security policy requires one, the rollback is refused with an error instead of deploying the mutable tag.
You can optionally pass a backupId in the request body to target a specific backup. If omitted, the most recent backup is used.
# Roll back to the most recent backup
curl -X POST http://localhost:3000/api/v1/containers/my-container-id/rollback \
-H 'X-DD-Confirm-Action: container-rollback'
# Roll back to a specific backup
curl -X POST http://localhost:3000/api/v1/containers/my-container-id/rollback \
-H 'X-DD-Confirm-Action: container-rollback' \
-H "Content-Type: application/json" \
-d '{"backupId": "abc123"}'Health-gate SSE heartbeat
During an update, drydock waits for the new container to pass its Docker HEALTHCHECK. While waiting, periodic heartbeat events keep the UI informed so real-time status stays accurate even when healthcheck intervals are long (e.g. 60 s).
| Env var | Required | Description | Default |
|---|---|---|---|
DD_UPDATE_HEALTH_GATE_HEARTBEAT_MS | ⚪ | Interval (ms) at which phase: 'health-gate' SSE events are re-emitted during the health-gate wait. Set to 0 to disable. Values below 1000 fail startup. | 10000 |
Auto-Rollback on Health Failure
Containers with a Docker HEALTHCHECK can automatically roll back if they become unhealthy after an update.
Container Labels
| Label | Type | Default | Description |
|---|---|---|---|
dd.rollback.auto | boolean | false | Enable auto-rollback when health check fails after update |
dd.rollback.window | number (ms) | 300000 | Duration to monitor health after update (5 minutes) |
dd.rollback.interval | number (ms) | 10000 | Frequency of health status checks (10 seconds) |
How It Works
- An update completes successfully
- If
dd.rollback.auto=trueand the container has aHEALTHCHECK, monitoring starts - Health status is polled every
dd.rollback.intervalfor the duration ofdd.rollback.window - If the status becomes
unhealthy, rollback is triggered automatically - If the window expires without failure, the container is considered stable
HEALTHCHECK instruction in your Dockerfile. Without one, monitoring is skipped unless you enable the liveness watch below.Liveness watch for images without a HEALTHCHECK
For containers with no HEALTHCHECK, you can opt in to a liveness watch. After the update, Drydock polls the recreated container every dd.rollback.interval for the length of the liveness window. If the container exits, is OOM-killed, or its restart count rises above the value it had right after the update (a crash loop under a restart policy), Drydock rolls back to the previous image the same way it does for an unhealthy container, with the same auto-rollback audit entry. If the window passes with the container still up, the update stands.
| Setting | Type | Default | Description |
|---|---|---|---|
dd.rollback.liveness (label) | number (ms) | unset | Liveness window for this container. 0 turns the watch off for this container even when the action enables it |
LIVENESSWINDOW (action option) | number (ms) | 0 (off) | Default liveness window for every container the action updates. The label overrides it |
The watch works with both the Docker and Docker Compose actions, doesn't need dd.rollback.auto, and never applies to containers that have a HEALTHCHECK, which keep the health-based behavior above. With neither setting, containers without a healthcheck behave as before.
The Portainer action doesn't support the liveness watch, because a rollback would recreate the container through Docker and bypass the stack Portainer manages. LIVENESSWINDOW is rejected on a Portainer action at startup, and dd.rollback.liveness on a container it updates is ignored with a warning.
A container that was stopped before the update isn't watched. Rollbacks put the container back the way it was before the update: a container that was running is started again, and the rollback is only recorded as a success once the restored container is seen running. If it isn't, the audit entry says so and records a failure.
Rollbacks and later updates
A rollback, whether automatic or from the manual rollback action, remembers the candidate it undid. Drydock then blocks that same candidate with the "last update rolled back" reason until a different version shows up or you set dd.update.rollback-gate=off on the container, so the failed update isn't applied again once the recently-applied window passes.
Rollbacks take the same per-container lock updates do, so a rollback never runs at the same time as an update of that container. Starting an update, or a manual rollback, cancels any health or liveness watch still running for that container. An operator stopping the container by hand during a watch window still counts as an exit and triggers the rollback, the same as before.
Each rollback is recorded as an operation, so container state alerts don't report the stop and restart Drydock does for it.
Examples
services:
myapp:
image: myapp:latest
labels:
- dd.rollback.auto=true
- dd.rollback.window=600000
- dd.rollback.interval=5000
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
interval: 10s
timeout: 5s
retries: 3