Connecting storage on back(d)

AWS S3

Mon, 01 Jan 0001 00:00:00 +0000

storage:
 provider: aws
 region: eu-west-1  # the bucket's region; the endpoint is derived
 bucket: acme-files
 prefix: prod
 access_key: secret:STORAGE_ACCESS_KEY
 secret_key: secret:STORAGE_SECRET_KEY


Endpoint	`https://s3.<region>.amazonaws.com` (derived from `region`; if you write it, `region` must agree)
Addressing	virtual-hosted (`<bucket>.s3.<region>.amazonaws.com`)
Signed SHA-256 (direct uploads)	supported
Largest single PUT	5 GiB
Multipart uploads (files above 5 GiB)	supported, with a SHA-256 per part
`backd storage check` reads	CORS and default encryption

Setting it up

Create the bucket in the region you will name, with Block all public access on. The bucket is always private.

MinIO

Mon, 01 Jan 0001 00:00:00 +0000

storage:
 provider: minio
 endpoint: https://minio.internal.example:9000  # http://minio:9000 only with BACKD_DEV=true
 # public_endpoint: http://localhost:9000 # when browsers reach MinIO at another address
 bucket: acme-files
 prefix: prod
 access_key: secret:STORAGE_ACCESS_KEY
 secret_key: secret:STORAGE_SECRET_KEY


Endpoint	any `https://<host>[:port]` (plain `http` only when `BACKD_DEV=true`, for development)
Addressing	path style (`<endpoint>/<bucket>/…`)
Region	any; default `us-east-1`
Signed SHA-256 (direct uploads)	supported
Multipart uploads (files above 5 GiB)	supported, with a SHA-256 per part
Oldest version tested	`RELEASE.2025-09-07T16-13-09Z` (the repository’s tests run against Chainguard’s current build as well)
`backd storage check` reads	neither CORS nor encryption (MinIO doesn’t expose them to an S3 client): it says so

Development

Images: the MinIO project no longer publishes container images (the old minio/minio and quay.io/minio/minio repositories stopped being pullable). The repository’s stacks use Chainguard’s build (cgr.dev/chainguard/minio and cgr.dev/chainguard/minio-client); both have no shell, so the server can’t run a health check and one-shot jobs call mc directly. You can also build MinIO from its source. backd storage check tells whether whatever you run behaves.

Cloudflare R2

Mon, 01 Jan 0001 00:00:00 +0000

storage:
 provider: r2
 endpoint: https://<account id>.r2.cloudflarestorage.com  # no bucket in it
 bucket: acme-files
 prefix: prod
 access_key: secret:STORAGE_ACCESS_KEY
 secret_key: secret:STORAGE_SECRET_KEY


Endpoint	`https://<account id>.r2.cloudflarestorage.com` (also `.eu.` and `.fedramp.` for those jurisdictions). R2’s console shows it with the bucket’s name after it: write only the host, and the name in `bucket`.
Addressing	virtual-hosted
Region	always `auto`
Signed SHA-256 (direct uploads)	supported: R2 rejects an upload whose digest differs (confirmed by the provider smoke test)
Largest single PUT	5 GiB
Multipart uploads (files above 5 GiB)	supported, with a SHA-256 per part (confirmed by the provider smoke test)
`backd storage check` reads	neither CORS nor encryption: it says so

Setting it up

Create the bucket in the Cloudflare dashboard (R2 → Create bucket). Keep it private: don’t enable public access or a public domain.
Create an API token (R2 → Manage API tokens) with Object Read & Write limited to that bucket. R2 shows an Access Key ID and a Secret Access Key once: those are the two secrets.
Encryption at rest: R2 encrypts all objects at rest; there is nothing to set.
CORS, needed for direct uploads and cross-origin downloads: set it on the bucket (Settings → CORS policy) for your app’s origin, with GET, PUT and HEAD and the allowed headers Content-Type and x-amz-checksum-sha256. backd storage check can’t read it: try an upload from the app.
Set the secrets and run backd storage check --realm <realm>.

R2’s tokens limit the bucket, not a prefix: the prefix still keeps each backd instance’s files apart, but a key can reach the whole bucket, so give each instance sharing a bucket a token of its own only if you must trust no instance with another’s files; otherwise use a bucket per instance.

DigitalOcean Spaces

Mon, 01 Jan 0001 00:00:00 +0000

storage:
 provider: digitalocean
 region: nyc3  # the Space's region; the endpoint is derived
 bucket: acme-files
 prefix: prod
 access_key: secret:STORAGE_ACCESS_KEY
 secret_key: secret:STORAGE_SECRET_KEY


Endpoint	`https://<region>.digitaloceanspaces.com` (derived from `region`; if you write it, `region` must agree)
Addressing	virtual-hosted
Signed SHA-256 (direct uploads)	supported (documented in the Spaces API reference)
Largest single PUT	5 GiB
Multipart uploads (files above 5 GiB)	not enabled until the provider smoke test confirms a SHA-256 per part: `max_size` stays at 5 GiB
`backd storage check` reads	neither CORS nor encryption: it says so

Setting it up

Create the Space in the region you will name, with File listing restricted (private).
Create a Spaces access key (API → Spaces Keys), scoped to that Space with Read, Write and Delete. The key and its secret are the two realm secrets.
Encryption at rest: Spaces encrypts data at rest; there is nothing to set.
CORS, needed for direct uploads and cross-origin downloads: set it in the Space’s Settings for your app’s origin with GET, PUT and HEAD, and allow the headers Content-Type and x-amz-checksum-sha256. backd storage check can’t read it: try an upload from the app.
Set the secrets and run backd storage check --realm <realm>.

A Spaces key is scoped to a Space, not to a prefix: use a Space per backd instance, or keep prefix distinct and accept that a key can reach every prefix of its Space.

Connecting storage on back(d)

AWS S3

Setting it up#

MinIO

Development#

Cloudflare R2

Setting it up#

DigitalOcean Spaces

Setting it up#

Setting it up

Development

Setting it up

Setting it up