App on a VPS
Ama runs a shop app on a small VPS. Her compose.yml has web and db (Postgres 17), in a project called shop, so Docker’s network for it is shop_default. She wants:
- nightly backups taken on the VPS
- monthly drills from her laptop
- the private key never on the VPS
On the VPS
Section titled “On the VPS”-
Install
pgband make a folder, as the user that runs Docker:Terminal window curl -fsSL https://raw.githubusercontent.com/iotabyt/pgbackup-r2/main/scripts/install.sh | shmkdir -p ~/backups/shop && cd ~/backups/shoppgb initnano .env -
Fill in
.env.dbonly exists on the Compose network, soPGB_NETWORKjoins it:Terminal window PG_MAJOR=17S3_ENDPOINT=https://<account-id>.r2.cloudflarestorage.comS3_BUCKET=ama-backupsS3_PREFIX=shopAWS_ACCESS_KEY_ID=... # an Object Read & Write tokenAWS_SECRET_ACCESS_KEY=...DATABASE_URL=postgresql://shop:<password>@db:5432/shopPGB_NETWORK=shop_default # so "db" resolvesAGE_RECIPIENTS=age1... # the public key onlyAGE_IDENTITY= # empty on the serverHEARTBEAT_URL=https://hc-ping.com/<uuid>docker network lslists the network names if you’re not sure of yours. -
Check, back up once, and start the nightly container:
Terminal window pgb doctor # ✓ for Docker, .env, database and bucket; "-" for the absent private keypgb backup # a first backup nowpgb nightly start # container pgbackup-shop, backing up at 02:00 UTCpgb nightly status
pgb nightly runs schedule in a container named pgbackup-<S3_PREFIX>, with --restart unless-stopped, so it comes back after reboots. pgb nightly logs -f follows its log, and pgb nightly stop removes it.
On her laptop
Section titled “On her laptop”A separate folder with its own .env:
- the same bucket settings, with a token that can also write drill records (see Set up R2)
AGE_IDENTITYfilled in- no
DATABASE_URLorPGB_NETWORK
pgb verify # minutes after the first backup: does it open?pgb drill # restores into a throwaway Postgres 17 and compares row countsAfter that, a drill once a month: see Monthly drills. pgb doctor on the laptop warns once the last successful drill is more than 35 days old.
Upgrading Postgres
Section titled “Upgrading Postgres”When she moves to Postgres 18, she sets PG_MAJOR=18 in both .env files. Then, on the VPS:
pgb updatepgb nightly stop && pgb nightly startSee Postgres versions for why the image has to match.
The same thing as a Compose service
Section titled “The same thing as a Compose service”If Ama would rather keep everything in compose.yml, the backup can be a service next to the database instead of pgb nightly:
services: db: image: postgres:17 # ... her existing database
backup: image: ghcr.io/iotabyt/pgbackup-r2:pg17 restart: unless-stopped env_file: backup.env # the same settings, kept out of git depends_on: [db]docker compose up -d backupdocker compose run --rm backup backup # a first backup nowdocker compose logs backupThe service runs schedule by default: it sleeps until BACKUP_AT, backs up, prunes and pings. Its log is plain timestamped lines:
2026-11-18T02:00:01Z INFO backing up postgresql://***@db:5432/shop to s3://ama-backups/shop/2026-11-18T020001Z.dump.age2026-11-18T02:00:23Z INFO backed up shop/2026-11-18T020001Z.dump.age (48.2 MB, 37 tables) in 22.1sMonthly drills: prove a backup restores, every month.
pgbackup-r2 is an open-source tool from Iotabyt. MIT licensed.