dtf-system/docs/BACKUP.md

Database backup

The backup service copies the database off the server once a day (ops/db_backup.py). It runs pg_dump, checks the archive, encrypts it with age and uploads it to an R2 bucket used for nothing else. Each run is recorded, and the Kanban shows the latest one under Integrações → "Backup do banco" ("Em dia", "Verificar" or "Não configurado").

The artwork is not backed up. Originals and print files are temporary (7 to 30 days) and already stored on R2. The database holds what cannot be recreated: orders, customers, quotes, payments, the Tiny connection and the operators.

Why the backup cannot be read or deleted from the server

• The server only encrypts. It holds the public key (age1…). The private key, which is the only way to open a backup, stays with the owner.
• Its own bucket and token. The backup token reaches the backup bucket only, and the artwork token cannot reach it.
• Nothing is deleted by the job. The bucket's lifecycle rule removes old copies. The bucket lock keeps anyone, including someone holding the token, from deleting or overwriting a copy before its time.

Setup (once)

1. Key pair. Generate it on your own computer, not on the server:

   docker run --rm gitea.blyzer.com.br/blyzer/dtf-api:latest age-keygen
   

   Or, with age installed (sudo pacman -S age, apt install age), just run age-keygen.

   Save the whole output (the AGE-SECRET-KEY-1… line is the private key) in the password manager. Only the public key: age1… value goes to Portainer. Without the private key, no backup can ever be restored.

2. Cloudflare R2 → Create bucket. Use a name such as dtf-backups.

3. Settings on that bucket:

   • Object lifecycle rules: delete objects after 35 days.
   • Bucket lock rules: retain for 30 days, prefix db/.

4. R2 → Manage API tokens → Create API token.

   • Permission: Object Read & Write.
   • Scope: the dtf-backups bucket only.

5. Portainer. Add these to the stack's environment, then redeploy:

   Variable	Value
   BACKUP_S3_ENDPOINT	same as R2_ENDPOINT
   BACKUP_BUCKET	dtf-backups
   BACKUP_ACCESS_KEY_ID	the new token's Access Key ID
   BACKUP_SECRET_ACCESS_KEY	the new token's Secret Access Key
   BACKUP_AGE_RECIPIENT	the public key, age1…
   BACKUP_HOUR	optional, default 3 (03:00 Brasília)

The first backup runs as soon as the service starts. After that it runs daily, and a failed run is retried an hour later.

Restore test

Do this after setup, and then once a month. Open the console of the backup container in Portainer (Containers → …_backup… → Console) and run:

python -m ops.db_backup list
python -m ops.db_backup verify --identity -

--identity - asks for the private key to be pasted. It is kept only in the container's memory while the command runs. verify restores the latest backup into a scratch database, prints its row counts and drops it. The live database is not touched.

Restoring for real

From the backup container's console:

python -m ops.db_backup restore db/2026/10/dtf-20261001T060000Z.dump.age --into dtf_restored --identity -

This restores into a new database (or an empty one), never over the running one. Then do one of these:

• Check the restored data, then point the stack at it.
• On a new server, deploy only the db service first. Restore into dtf while it is still empty, then deploy the rest. db-init then applies the schema and grants on top.