# 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](https://age-encryption.org) 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:

   ```bash
   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:

```bash
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:

```bash
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.