Media backends

Configure where uploaded files are stored. Switch backends in Settings → Media storage — no restart required.

blob (default)

Files are stored as BLOBs in _media.data in the pod. No external services, no config.

Good for small-to-medium sites with up to a few hundred images. For large media libraries, use one of the external backends.

local — filesystem

Files are written to a directory on the server. Useful for self-hosted VPS deployments where the disk persists.

media.backend     = local
media.local_path  = /var/data/media   (absolute or relative path)

Warning: If your server restarts and the directory is not mounted as a persistent volume, files will be lost. Use an absolute path to a persistent location.

github — GitHub + jsDelivr CDN

Files are uploaded via the GitHub Contents API and served from jsDelivr CDN — cdn.jsdelivr.net/gh/owner/repo@branch/path. No egress cost, cached globally.

media.backend        = github
media.github_repo    = owner/my-media-repo
media.github_branch  = main
media.github_dir     = media
media.github_token   = ghp_…   (falls back to the GitHub token in Settings → GitHub)

The token needs Contents: Read and write permission on the target repository. The repository can be different from your content repo.

On delete, Orbiter makes a DELETE request to the GitHub API to remove the file and create a deletion commit.

s3 — S3-compatible storage

Works with AWS S3, Cloudflare R2, Backblaze B2, MinIO, and any S3-compatible service.

media.backend       = s3
media.s3_bucket     = my-media-bucket
media.s3_region     = auto              (use "auto" for R2)
media.s3_endpoint   = https://xxxx.r2.cloudflarestorage.com  (blank for AWS)
media.s3_access_key = …
media.s3_secret_key = …
media.s3_public_url = https://media.example.com  (your public domain or CDN)

The bucket must be publicly readable. Set media.s3_public_url to your R2 public domain, a CloudFront distribution, or any CDN in front of the bucket. If left blank, Orbiter falls back to the default AWS S3 URL pattern.

Cloudflare R2: Set media.s3_region to auto and media.s3_endpoint to your R2 endpoint URL. Use your R2 public bucket URL or a custom domain as media.s3_public_url.

External link (no backend)

Not a backend configuration — it's a per-file option. Use the External link tab in the image picker to store a URL reference without downloading the file. See Media library.

Switching backends

Changing the backend in Settings affects only new uploads. Existing files remain where they are. If you want to migrate existing media, export and re-upload manually.