1# Backups Configuration
2
3Gordon has two backup flows:
4
5- **Database backups**: PostgreSQL logical dumps via `pg_dump`, stored on the local filesystem.
6- **Volume backups**: best-effort filesystem archives of Gordon-managed named volumes, uploaded to S3. Administrative bind mounts are operator-owned host paths and are never archived.
7
8Backups are identified by app, service, and the declared database or volume
9(see [Apps](../config/apps.md)). Domains are routing addresses and are never a
10backup identity.
11
12## Database backups
13
14```toml
15[backups.databases]
16enabled = true
17schedule = "daily"
18storage_dir = "~/.gordon/backups"
19
20[backups.databases.retention]
21hourly = 24
22daily = 7
23weekly = 4
24monthly = 12
25```
26
27| Key | Default | Description |
28|---|---:|---|
29| `backups.databases.enabled` | `false` | Enables PostgreSQL backup service wiring |
30| `backups.databases.schedule` | `"daily"` | Scheduler preset: `hourly`, `daily`, `weekly`, `monthly` |
31| `backups.databases.storage_dir` | `""` | Root backup directory; defaults to `{server.data_dir}/backups` |
32| `backups.databases.retention.*` | `0` | Number of backups to keep per DB and schedule tier |
33
34## Volume backups to S3
35
36```toml
37[backups.volumes]
38enabled = true
39interval = "24h"
40compression = "gzip"
41timeout = "2h"
42max_concurrency = 2
43helper_image = "alpine:3.20"
44
45[backups.volumes.s3]
46bucket = "gordon-backups"
47region = "eu-west-3"
48prefix = "prod/gordon"
49# endpoint = "https://s3.example.com"
50# path_style = false
51# sse_algorithm = "AES256"
52# sse_kms_key_id = ""
53# storage_class = "ONEZONE_IA"
54
55[backups.volumes.retention]
56keep = 14
57```
58
59| Key | Default | Description |
60|---|---:|---|
61| `backups.volumes.enabled` | `false` | Enables automatic volume archives |
62| `backups.volumes.interval` | `"24h"` | Interval between scheduled runs |
63| `backups.volumes.compression` | `"gzip"` | `gzip` or `zstd`; helper image must provide the tool |
64| `backups.volumes.timeout` | `"2h"` | Per-volume archive/upload timeout |
65| `backups.volumes.max_concurrency` | `2` | Maximum concurrent volume backups |
66| `backups.volumes.helper_image` | `"alpine:3.20"` | Helper container image used for tar/compression |
67| `backups.volumes.s3.bucket` | `""` | Required when volume backups are enabled |
68| `backups.volumes.s3.region` | `""` | Required when volume backups are enabled |
69| `backups.volumes.s3.prefix` | `""` | Object key prefix |
70| `backups.volumes.s3.endpoint` | `""` | Optional S3-compatible endpoint |
71| `backups.volumes.s3.path_style` | `false` | Use path-style addressing for S3-compatible storage |
72| `backups.volumes.s3.sse_algorithm` | `""` | Server-side encryption sent with each upload, such as `AES256` |
73| `backups.volumes.s3.sse_kms_key_id` | `""` | KMS key ID for `aws:kms` encryption |
74| `backups.volumes.s3.storage_class` | `""` | Storage class sent with each upload, such as `STANDARD_IA` (AWS) or `ONEZONE_IA` (Scaleway One Zone); empty uses the bucket default |
75| `backups.volumes.retention.keep` | `14` | Completed archives to keep per app + volume |
76
77Volume backup objects are stored under the canonical app name:
78
79```text
80<prefix>/apps/<app>/volumes/<volume>/<timestamp>-<id>.tar.gz   # gzip
81<prefix>/apps/<app>/volumes/<volume>/<timestamp>-<id>.tar.zst  # zstd
82```
83
84Objects written by earlier versions under a domain prefix are not read or
85migrated: back them up and re-run the app's volume backups if you need them in
86the current layout.
87
88## Notes
89
90- Volume backups archive the app's declared volumes that its backup declaration references.
91- Bind mounts, tmpfs mounts, anonymous volumes, and undeclared volumes are never backed up.
92- Database backups archive the app's declared PostgreSQL databases that its backup declaration references.
93- Only volumes listed in a service's `backup.volume` are archived. Leave caches and rebuildable data (CI runner state, build caches) out of that list.
94- Stored size is roughly `retention.keep` × the compressed size of each backed-up volume.
95- Live volume archives are best-effort; consistency requires application quiesce, pause, or stop.
96- Automated volume restore is not part of the MVP.
97- Snapshots are not generic across Docker/Podman volumes and require backend-specific support such as ZFS, Btrfs, LVM, EBS, or a snapshot-capable volume driver.
98- S3 credentials should come from the environment, shared config, instance role, or Gordon secret conventions. Use least-privilege IAM for the configured prefix.
99
100## Related
101
102- [App Manifest](./apps.md)
103- [CLI Backup Command](../cli/backup.md)
104- [Configuration Reference](./reference.md)