Cloudflare R2 offsite backups
Cloudflare R2 is an optional offsite destination for completed full backups. Configure it under Cockpit → Integrations → Cloudflare R2. Backup schedules and local retention stay under Cockpit → Backups → Backup settings (see Automatic backups).
Stellarr supports two connection modes:
| Mode | How it works | Best for |
|---|---|---|
| Direct S3 API | Container streams 64 MiB multipart uploads directly to R2 | Large instances and attachments (>100 MB archives) |
| Backup Relay Worker | Container streams to the Worker in deploy/cloudflare/backup-relay | Small instances without managing R2 S3 credentials |
Neither mode requires a Cloudflare Tunnel, public bucket, custom domain, or CORS rules.
Option A: Direct S3 mode
- Create a private, dedicated backup bucket in Cloudflare R2 with public access disabled.
- Create bucket-scoped R2 S3 credentials with object read/write access, separate from any live storage keys.
- In Cockpit → Integrations → Cloudflare R2, choose R2 S3 API credentials, save the access key and secret key first, then enter the endpoint, region (
auto), bucket, and prefix. Turn on Send backup copies to Cloudflare R2 and save.
To supply defaults or credentials in .env instead (Cockpit values override .env):
STELLARR_CLOUDFLARE_R2_ENABLED=true
STELLARR_CLOUDFLARE_R2_MODE=s3
STELLARR_CLOUDFLARE_R2_ENDPOINT=https://ACCOUNT_ID.r2.cloudflarestorage.com
STELLARR_CLOUDFLARE_R2_REGION=auto
STELLARR_CLOUDFLARE_R2_BUCKET=stellarr-backups
STELLARR_CLOUDFLARE_R2_ACCESS_KEY=YOUR_R2_ACCESS_KEY_ID
STELLARR_CLOUDFLARE_R2_SECRET_KEY=YOUR_R2_SECRET_ACCESS_KEY
STELLARR_CLOUDFLARE_R2_PREFIX=stellarrUse your bucket's R2 S3 endpoint (including any jurisdiction hostname), never an r2.dev public URL. Direct .NET deployments use the Cloudflare__R2__* prefix.
Option B: Backup Relay Worker
The Deploy to Cloudflare button deploys only the relay Worker. Stellarr itself continues running in your Docker container.
- Click Deploy to Cloudflare. Cloudflare clones
deploy/cloudflare/backup-relay, provisions theBACKUPSR2 bucket, and prompts forBACKUP_TOKEN. - Set
BACKUP_TOKENto a strong random secret (for example,openssl rand -hex 32). - In Cockpit → Integrations → Cloudflare R2, choose Backup relay Worker, enter the Worker URL and
BACKUP_TOKEN, keep the prefix, enable offsite copies, and save.
Or configure in .env:
STELLARR_CLOUDFLARE_R2_ENABLED=true
STELLARR_CLOUDFLARE_R2_MODE=worker
STELLARR_CLOUDFLARE_R2_ENDPOINT=https://stellarr-backup-relay.ACCOUNT.workers.dev
STELLARR_CLOUDFLARE_R2_WORKER_TOKEN=YOUR_LONG_RANDOM_TOKEN
STELLARR_CLOUDFLARE_R2_PREFIX=stellarrWorker limits
- The Worker uploads the whole archive in one
PUT /objectrequest. Cloudflare Workers limit request body size (about 100 MB on Free plans, 500 MB on Paid plans; verify current Cloudflare limits). Use Direct S3 mode if your archives exceed that. - The Worker exposes
PUT,HEAD, andGETon/objectand rejects conflicting SHA-256 overwrites with409. It has no list or delete route, so configure lifecycle rules and bucket locks in Cloudflare.
Upload behavior, retention, and security
- Object names:
<PREFIX>/<SERVER_UUID>/backup-<TIMESTAMP>-<UUID>.zip. Archives stream from disk rather than loading into RAM. - Verification: After upload, Stellarr sends a
HEADrequest to confirm file size and storedsha256metadata. Because this does not read back remote bytes, download and checksum a sample regularly. - Retention: Local copies follow Cockpit retention (14 days by default). Stellarr never deletes remote R2 objects, so add an R2 lifecycle expiration rule (for example, 90 days) and optionally bucket locks plus incomplete-multipart cleanup.
- Encryption: Archives are encrypted in transit and at rest by Cloudflare, not client-side encrypted. They contain uploads, session keys, and encrypted Cockpit secrets. Wrap them with a client-side encrypted tool such as
resticif your threat model requires keys outside Cloudflare. - Keep
.envseparately: Environment variables (STELLARR_CLOUDFLARE_R2_WORKER_TOKEN, S3 keys, and other.envsecrets) are excluded from backups. Keep.envin a separate recovery store.
References
Cloudflare documentation reviewed on 2026-11-13: