DATA

Backups and restores

Schedule backups, send them off-site, verify they can actually be restored, and restore to a point in time.

A backup captures your applications’ data directories, your managed databases and your named volumes into one encrypted archive. It can run on a schedule, land off-site in S3, and — the part most panels skip — be tested without touching anything live.

A definition, and its runs

Two different objects wear the word “backup”, and the distinction saves confusion later:

A definition: The configuration — what to capture, where to send it, on what schedule. It never holds data, is never restorable, and does not count against your project’s backup quota.
A run: One realized archive on disk or in a bucket, produced by the schedule or by Back up now. This is the thing you restore, verify, export or delete.

Editing a definition changes what the next run captures. It never rewrites an archive that already exists — an old backup stays exactly what it was when it was taken.

What goes in

A backup is scoped either to one project or to a whole server, and four independent switches decide what it captures:

Switch	Captures
Applications	Each application’s data directory on the host.
Databases	A logical dump per managed database — `pg_dump`, `mysqldump`, `mongodump`, or the engine’s equivalent.
Volumes	Named Docker volumes, as a tar per volume.
Linux instances	The `/root`, `/home` and `/data` of each instance. Its own switch because an instance is a whole machine and can be an order of magnitude larger than an application’s data dir.

A project-scoped backup captures only that project. A server-scoped one captures every project on the machine — useful for an operator snapshot, wrong as a per-tenant default.

Scheduling

A definition takes @hourly, @daily, @weekly, or a cron expression of the form <minute> <hour> * * *:

TEXT

@daily
@weekly
30 4 * * *

Deliberately narrower than full cron. A backup that fires every minute is not a backup policy, it is a way to fill a disk — so the grammar only expresses the daily-ish cadences a backup actually wants.

Runs are limited in width: a couple execute at a time and the rest wait their turn. A queued backup is not a failed backup, and letting twenty dumps compete for the same disk makes all twenty slow.

How many are kept

A schedule that never deletes anything fills a disk on a timer. Three independent limits decide what survives, each of them settable per project and falling back to the platform default when left unset:

Limit	Applies to	Off when
Keep last N	Runs of one schedule. The oldest are deleted once the newest N are in place.	0
Age in days	Completed backups older than the window, whatever produced them. Capped at 3650.	0
Max per project	Every backup the project holds, manual and scheduled together — a ceiling, not a sweep.	0

The first two delete archives; the third refuses to create one. Reaching the per-project ceiling makes a scheduled run skip with a warning rather than quietly dropping an older backup to make room — the panel will not decide for you which archive is expendable. Definitions never count against it.

A failed run is kept, not swept: the age sweep only touches completed backups. That is deliberate — a row saying *this failed, here is why* is the only trace you have that the schedule ran at all, and it holds no data worth reclaiming.

This is separate from the history the panel keeps about itself — metrics, deployments, the audit log. Those are rows in a database; these are archives on a disk.

Where it lands

Local: A file in the platform’s backup directory, mode 0700. Fine for convenience, useless against the failure where the host itself is lost.
S3, R2 or B2: Any S3-compatible bucket, configured per project. This is the one that survives losing the server.

A remote backup pins the exact bucket coordinates it was written to, encrypted, at the moment it finishes. Editing or removing a project’s storage config later never re-points an existing archive at the wrong bucket — which would make it unrestorable and orphan the real object.

Configure the bucket, then use Test storage — it lists the bucket with the stored credentials. Discovering a typo the night the schedule fires is the expensive way to find it.

Encryption and integrity

Archives are AES-256-GCM encrypted at rest with the install’s backup key, kept separate from database access.
A sha256 of the final on-disk file is recorded at write time and re-verified before every restore. A mismatch refuses the restore rather than replaying a corrupt or tampered archive over live data.
Reading backups needs backups:view; creating them backups:create; restoring and exporting backups:restore. Restore is its own permission because it overwrites.

Proving a backup is restorable

Verify replays every database dump in the archive into a throwaway scratch container, waits for that container to accept connections, and counts the objects it ends up holding. Then it throws the container away. Live data is never touched.

An untested backup is a hypothesis. A dump can be written, encrypted, hashed, shipped off-site and still replay into nothing — an empty database, a truncated dump, an engine version that will not read it. You find that out either on a Tuesday afternoon with a scratch container, or at 3 a.m. with your production data gone.

The same readiness probe and object count run at the end of a real restore, so “ready” means the same thing on both paths. A restore that replays cleanly into a database nobody can reach reports a warning rather than a green tick — the worst thing this feature could say is “Restore completed” over a database that is down, because then you stop looking.

Restoring

A restore takes a COMPLETED run and replays it. You can narrow it to specific applications, databases or volumes rather than replaying the whole archive — useful when one database was dropped and the rest of the project is fine.

A restore overwrites. The data currently in the targeted databases and volumes is replaced by what the archive holds. There is no undo, and the previous state is not kept anywhere unless you took a backup of it first.

Before a restore you are not fully sure about, take a fresh backup of the current state. It costs minutes and it is the only thing standing between “we restored the wrong day” and a permanent loss.

Taking a backup elsewhere

Export produces a .dcbak — a portable copy of a realized backup, encrypted with a passphrase you choose rather than with the install’s key. That is what makes it readable by a different DockBoard install:

01Export the run, choosing a passphrase. Store the passphrase somewhere other than next to the file.
02On the target install, Import the .dcbak, supplying the same passphrase and the server to restore onto.
03The import restores immediately — it is a restore, with all of a restore’s consequences.

Lose the passphrase and the archive is unreadable. Nobody can recover it — that is the property that makes exporting one safe to store off-site in the first place.

Import also accepts a raw at-rest archive from this same install, with no passphrase. That is the disaster-recovery shape: you have the file and this install’s key and nothing else, and demanding a passphrase it never had would refuse the very restore the file exists for.

Backing up DockBoard itself

Everything above backs up your data. The platform’s own database — which projects exist, which servers, which credentials — is backed up separately, from Admin → Backups:

Control-plane dump: A daily logical dump of the platform database. Small — schema and rows, no blobs — so a fortnight of history costs almost nothing and covers a corruption noticed late.
Point-in-time recovery: A weekly physical base backup plus WAL archiving. Together they recover any instant in between. Either alone recovers nothing useful — which is why the status page reports both, separately.

These dumps decrypt to every credential on the platform, so they sit behind whole-fleet authority (servers:manage) and are never reachable by a project member or an API key. Treat the downloaded file with the same care as the platform database itself.