Files
Let documents carry files, kept in the realm's own S3-compatible object storage: how a realm connects its storage, and what backd checks.
backd itself stores no files. A realm that wants documents to carry files (an avatar, receipts, attachments) brings its own S3-compatible storage, from a closed list of providers: AWS S3, MinIO, Cloudflare R2 and DigitalOcean Spaces. The bucket stays private: files are only ever reached through backd, under the same access rules as the document they belong to.
Pages: connecting storage, file fields, uploads and downloads, rules for files, keeping storage tidy, files in apps, security, and files in functions.
The ideas
- Every file belongs to a document field. There is no file area outside documents: a public asset or a personal file space is an ordinary collection whose documents carry the file.
- Storage is a realm’s concern. Each realm declares its own bucket, with its own keys; there is no instance-wide storage.
- A closed list of providers. What each provider can do is data in one place in
backd: a provider that isn’t on the list fails the configuration check instead of failing in production, andbackdnever probes a service to find out what it supports. - Only what every provider has: put, get (with ranges), head, delete, listing (for a manual reconcile only) and presigned links, all signed with AWS Signature Version 4.
- Encryption at rest is the bucket’s default, set at the provider.
backdsends no encryption headers and has no setting for it;backd storage checkreports the bucket’s status where the provider exposes it.
Start with Connecting storage and the page of your provider, then File fields, Uploads and downloads and Rules for files.
storage: in realm.yaml, the access keys as realm secrets, the prefix each backd instance needs, and backd storage check.
AWS S3Set up an S3 bucket and a least-privilege key for a backd realm.
MinIOUse a self-hosted MinIO as a realm’s storage, in development and in production.
Cloudflare R2Use a Cloudflare R2 bucket as a realm’s storage.
DigitalOcean SpacesUse a DigitalOcean Space as a realm’s storage.
File fieldsfiles: in collection.yaml: which fields of a document carry files, their limits, and what backd keeps in them.
Uploads and downloadsUpload a file into a document, download it, remove it, and give an app links to show files.
Rules for filesHow access rules decide who uploads, removes and downloads files, and how to reserve a file field for functions.
Keeping storage tidyWhat happens to a file’s object when its document changes or is deleted, erasing users, usage totals, backups, and backd storage usage and reconcile.
Files in appsShowing, uploading and downloading files from a web app: links for pictures, download buttons that fetch a fresh link on click, and the pitfalls.
Security of filesHow backd protects files, what it trusts, what links and tokens allow, and what you are responsible for: bucket, prefix, links, caches and the content you accept.