Backups

Coldrune backs up the entire SQLite database as an encrypted snapshot to S3-compatible storage.

Configure S3

Add to your .env:

BACKUP_S3_ENDPOINT=https://fsn1.your-objectstorage.com
BACKUP_S3_REGION=us-east-1
BACKUP_S3_BUCKET=coldrune-backups
BACKUP_S3_ACCESS_KEY=your-access-key
BACKUP_S3_SECRET_KEY=your-secret-key

Works with Hetzner Object Storage, AWS S3, MinIO, and any S3-compatible provider.

If BACKUP_S3_ENDPOINT is not set, all backup features are disabled.

Manual backup

coldrune backup create

Or via API:

curl -X POST http://localhost:7100/api/backups \
  -H 'Authorization: Bearer <token>'

Backup endpoints require superadmin access.

Scheduled backups

BACKUP_SCHEDULE_HOURS=24

Set to 0 to disable. The backup runs as a background task inside the server process.

Retention policy

BACKUP_RETAIN_DAILY_DAYS=7
BACKUP_RETAIN_WEEKLY_WEEKS=4

After each scheduled backup, the server cleans up old backups:

• Daily: keeps the most recent backup from each of the last N days
• Weekly: keeps one backup per ISO week for the last M weeks
• Anything older is deleted from S3

List backups

coldrune backup list

Restore

coldrune backup restore --id <backup-id>

This downloads, decrypts, validates the SQLite header, and writes the restored database to {db_path}.restore.{id}.

Caution

Restore does not automatically swap the database. You must manually stop the server, replace the database file, and restart.

Restore procedure

1. Restore the backup: coldrune backup restore --id <backup-id>
2. Stop the server: sudo systemctl stop coldrune
3. Swap the database: mv coldrune.db coldrune.db.old && mv coldrune.db.restore.<id> coldrune.db
4. Restart: sudo systemctl start coldrune

Backup format

Backups use a custom binary format:

CRBU (4 bytes magic) | version (1 byte) | nonce (12 bytes) | ciphertext

Encrypted with a key derived from the master key via HKDF-SHA256 (info: coldrune-backup-key), using AES-256-GCM. The backup is created using SQLite’s VACUUM INTO for a consistent snapshot without locking the database.

After key rotation

Old backups remain encrypted with the old master key. After rotating keys, create a new backup immediately. Keep the old master key stored securely if you need to restore from pre-rotation backups.