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.
7
8## Database backups
9
10```toml
11[backups.databases]
12enabled = true
13schedule = "daily"
14storage_dir = "~/.gordon/backups"
15
16[backups.databases.retention]
17hourly = 24
18daily = 7
19weekly = 4
20monthly = 12
21```
22
23| Key | Default | Description |
24|---|---:|---|
25| `backups.databases.enabled` | `false` | Enables PostgreSQL backup service wiring |
26| `backups.databases.schedule` | `"daily"` | Scheduler preset: `hourly`, `daily`, `weekly`, `monthly` |
27| `backups.databases.storage_dir` | `""` | Root backup directory; defaults to `{server.data_dir}/backups` |
28| `backups.databases.retention.*` | `0` | Number of backups to keep per DB and schedule tier |
29
30## Volume backups to S3
31
32```toml
33[backups.volumes]
34enabled = true
35interval = "24h"
36compression = "gzip"
37timeout = "2h"
38max_concurrency = 2
39helper_image = "alpine:3.20"
40
41[backups.volumes.s3]
42bucket = "gordon-backups"
43region = "eu-west-3"
44prefix = "prod/gordon"
45# endpoint = "https://s3.example.com"
46# path_style = false
47# sse_algorithm = "AES256"
48# sse_kms_key_id = ""
49
50[backups.volumes.retention]
51keep = 14
52```
53
54| Key | Default | Description |
55|---|---:|---|
56| `backups.volumes.enabled` | `false` | Enables automatic volume archives |
57| `backups.volumes.interval` | `"24h"` | Interval between scheduled runs |
58| `backups.volumes.compression` | `"gzip"` | `gzip` or `zstd`; helper image must provide the tool |
59| `backups.volumes.timeout` | `"2h"` | Per-volume archive/upload timeout |
60| `backups.volumes.max_concurrency` | `2` | Maximum concurrent volume backups |
61| `backups.volumes.helper_image` | `"alpine:3.20"` | Helper container image used for tar/compression |
62| `backups.volumes.s3.bucket` | `""` | Required when volume backups are enabled |
63| `backups.volumes.s3.region` | `""` | Required when volume backups are enabled |
64| `backups.volumes.s3.prefix` | `""` | Object key prefix |
65| `backups.volumes.s3.endpoint` | `""` | Optional S3-compatible endpoint |
66| `backups.volumes.s3.path_style` | `false` | Use path-style addressing for S3-compatible storage |
67| `backups.volumes.retention.keep` | `14` | Completed archives to keep per domain + volume |
68
69Volume backup objects are stored under:
70
71```text
72<prefix>/domains/<domain>/volumes/<volume>/<timestamp>-<id>.tar.gz   # gzip
73<prefix>/domains/<domain>/volumes/<volume>/<timestamp>-<id>.tar.zst  # zstd
74```
75
76## Notes
77
78- Volume backups include named volumes mounted by Gordon-managed route or attachment containers.
79- Bind mounts, tmpfs mounts, anonymous volumes, and non-Gordon volumes are excluded.
80- Live volume archives are best-effort; consistency requires application quiesce, pause, or stop.
81- Automated volume restore is not part of the MVP.
82- 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.
83- S3 credentials should come from the environment, shared config, instance role, or Gordon secret conventions. Use least-privilege IAM for the configured prefix.
84
85## Related
86
87- [Attachments Configuration](./attachments.md)
88- [CLI Backup Command](../cli/backup.md)
89- [Configuration Reference](./reference.md)