For uploaded images and files to persist in production, the media collection must write to an object store rather than the local filesystem. ChaiBuilder uses Payload's official S3 storage plugin (@payloadcms/storage-s3), which works with any S3-compatible backend — AWS S3, Cloudflare R2, MinIO, DigitalOcean Spaces, Wasabi, and more.

Why this is required: on serverless and containerised hosts the local filesystem is ephemeral — files written at runtime disappear on redeploy and aren't shared across instances. Object storage keeps uploads durable and centralized. See Overview.

1. Provision a bucket

Create a bucket on your provider and an access key pair scoped to it. Note down:

• Bucket name
• Region
• Access key ID and secret access key
• Endpoint — the S3 API endpoint. For AWS this is inferred from the region; for S3-compatible providers (R2, MinIO, Spaces) it's an explicit URL.

2. Set environment variables

Add your credentials to the project's environment. ChaiBuilder's Payload config reads these:

# --- S3-compatible object storage (media uploads) ---
BUCKET_NAME=your-bucket
REGION=auto                         # e.g. us-east-1, or "auto" for Cloudflare R2
ACCESS_KEY_ID=your_access_key_id
SECRET_ACCESS_KEY=your_secret_access_key
ENDPOINT=https://<account>.r2.cloudflarestorage.com   # provider S3 API endpoint

Confirm the exact variable names against your generated project's .env.example — the S3 plugin block in payload.config.ts is what maps them, so those two files are the source of truth for your starter.

3. Wire the plugin (already in the starter)

The ChaiBuilder starter already registers the S3 plugin in payload.config.ts, pointing the media collection at your bucket. It looks like this:

import { s3Storage } from '@payloadcms/storage-s3'

export default buildConfig({
  // …
  plugins: [
    // …
    s3Storage({
      collections: {
        media: {
          prefix: `${getAppStoragePrefix()}/`,  // keeps each app's files namespaced
        },
      },
      bucket: process.env.BUCKET_NAME as string,
      config: {
        credentials: {
          accessKeyId: process.env.ACCESS_KEY_ID as string,
          secretAccessKey: process.env.SECRET_ACCESS_KEY as string,
        },
        region: process.env.REGION as string,
        endpoint: process.env.ENDPOINT as string,
        forcePathStyle: true,   // required by most S3-compatible providers (R2, MinIO, …)
      },
    }),
  ],
})

Notes:

• collections.media attaches the adapter to the media upload collection. Add other upload collections here the same way if you create them.
• prefix namespaces objects per app, so a shared bucket won't collide across projects.
• forcePathStyle: true is needed by R2, MinIO, and most non-AWS S3 APIs. On AWS S3 you can drop it and omit endpoint.

4. Restart and verify

Restart the app, open the media manager in the builder, and upload an image. Then:

• Confirm the image renders in the builder and on a published page.
• Check your bucket — the object should appear under the configured prefix.
• Redeploy and confirm existing images still load (the point of object storage).

Provider quick reference

Provider	ENDPOINT	REGION	Notes
AWS S3	omit (inferred)	e.g. us-east-1	forcePathStyle not required
Cloudflare R2	https://<account>.r2.cloudflarestorage.com	auto	forcePathStyle: true
MinIO	your MinIO URL	any	forcePathStyle: true
DigitalOcean Spaces	https://<region>.digitaloceanspaces.com	region slug	forcePathStyle: true

Troubleshooting

• Uploads succeed but images 404 after deploy — you're still on the local filesystem; the S3 env vars aren't set or aren't reaching the runtime.
• AccessDenied / signature errors — key pair lacks bucket permissions, wrong region, or wrong endpoint.
• Works locally, fails on the host — env vars not configured in the deployment platform's settings (they aren't read from a local .env in production).

Related

• Overview — how media and uploads work.
• Environment & License — where these vars sit alongside the rest of your configuration.
• Deploy to Cloudflare — pairs naturally with R2.