Repository navigation
v1.5.0 — S3 backup storage & automatic retention
What's new
S3-compatible backup destinations
Configuration → Backup storage now configures a generic S3 destination:
- Works with AWS S3, MinIO, Cloudflare R2, Backblaze B2, Wasabi, and other S3-compatible providers.
- Configurable endpoint (blank for AWS), region, bucket, object prefix, access key ID, secret access key, session token, and force-path-style.
- Static credentials are encrypted with
APP_ENCRYPTION_KEYand are never returned by the API. Leave the access key and secret blank to use the API container's AWS credential chain. - Test connection checks
HeadBucketplus a temporary put/get/delete under the configured prefix, so it verifies the permissions a backup needs. - After every new backup passes its automatic restore check, it is uploaded to the bucket. The local archive remains on the console volume for the one-click restore list; the S3 object is the off-site copy.
- Existing backups are not uploaded retroactively; create a new backup after enabling S3.
Automatic backups and retention
- Choose an automatic interval: hourly, every 6/12 hours, daily, every 3 days, weekly, or every 30 days.
- Choose how many backups to keep (0–100). After a successful backup, older local archives and their matching S3 objects are removed automatically.
- Retention pauses when the new backup fails verification or its S3 upload fails, so older usable copies are not deleted while the current one is only local or unverified.
- Unverified backups are not uploaded to S3 and are not used to trigger retention.
- Manual creation, scheduled creation, restore, upload-restore, and deletion are serialised, avoiding a backup running against a half-restored database.
- The scheduler runs in the API process and checks once per minute; the API must be running for scheduled backups to occur.
Backup list
- Backups uploaded to S3 now show an S3 badge alongside the encrypted/plain and verification state.
- The create flow reports S3 upload warnings and retention warnings without hiding a backup that was successfully created locally.
- The staged create animation now includes the S3 upload stage.
Required S3 permissions
Replace the bucket and prefix as needed:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["s3:ListBucket"],
"Resource": "arn:aws:s3:::YOUR_BUCKET"
},
{
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:PutObject",
"s3:DeleteObject",
"s3:AbortMultipartUpload",
"s3:ListMultipartUploadParts"
],
"Resource": "arn:aws:s3:::YOUR_BUCKET/wireguard-console/backups/*"
}
]
}For non-AWS providers, grant the equivalent list/read/write/delete permissions on the bucket and prefix. Large backups use multipart upload, so include the multipart abort permission. Use an HTTPS endpoint outside a trusted local network; plain HTTP sends the access key and secret in cleartext.
Upgrade notes
- Migration 034 applies automatically on the next API start. It adds the S3 destination, automatic-backup interval, retention count, and last-attempt columns to the existing
configrow. - S3 is optional. Leaving it disabled preserves the previous local-only backup behaviour.
- New backups only: existing local archives are not uploaded automatically. Create a new backup after enabling S3 if you want a remote copy.
- S3 credentials are stored encrypted with
APP_ENCRYPTION_KEY; keep that key with your other deployment secrets. - The console keeps a local archive after uploading. If the console volume is lost, download the object from S3 and use Restore from upload.
- Automatic backups do not catch up missed intervals after downtime; the next attempt runs after the API restarts if the interval has elapsed.
Verification
- Backend:
go test ./...andgo vet ./...green. - Full E2E against PostgreSQL 18 with a fake S3 endpoint: S3 save/test, backup upload, remote retention deletion, and the existing backup/restore flows green.
- Scheduled-backup path exercised against a temporary PostgreSQL database: archive created, restore-verified, and
backup_last_auto_atupdated. - Frontend: 36 test files / 273 tests green;
tsc -bclean; production Vite build clean.