Deep dive

Cloudflare R2 configuration and setup

This page is the in-depth setup reference for Step 1 in the self-hosting guide. It includes exact UI path guidance, credential mapping, and a post-deployment CORS step.

Back To Main Guide Jump To Post-Deployment CORS

Values you need

1. R2_ACCOUNT_ID
2. R2_BUCKET
3. R2_ACCESS_KEY_ID
4. R2_SECRET_ACCESS_KEY
5. R2_PUBLIC_BASE_URL

Part 1

Open R2 and create your bucket

1. Open Cloudflare dashboard.
2. Go to Storage and databases, then R2 Object Storage, then Overview.
3. Click Create bucket.
4. Name the bucket (example: fircle-media) and create it.

Cloudflare R2 overview with the Storage and databases section highlighted — 1. R2 overview and bucket entry point

Cloudflare R2 create bucket form with bucket name field highlighted — 2. Create bucket form

Part 2

Create API access keys

1. In the Account Details panel, find API Tokens.
2. Click Manage.
3. Create an access key pair with bucket read and write permissions for your R2 bucket.
4. Save Access Key ID and Secret Access Key immediately.

Cloudflare R2 account API tokens page with Create Account API token highlighted — 1. Open Account API Tokens

Cloudflare R2 create account API token page with token name field highlighted — 2. Start token creation

Cloudflare R2 token permissions and bucket selection section — 3. Pick Object Read & Write permissions

Cloudflare R2 create token page with Create Account API Token button highlighted — 4. Create the API token

Cloudflare R2 successful API token creation page showing access key ID and secret access key — 5. Copy the access key values

Part 3

Map values to environment variables

1. Copy Account ID from Account Details to R2_ACCOUNT_ID.
2. Use your bucket name for R2_BUCKET.
3. Map Access Key ID to R2_ACCESS_KEY_ID.
4. Map Secret Access Key to R2_SECRET_ACCESS_KEY.
5. Set R2_PUBLIC_BASE_URL to your public object URL base.

R2_ACCOUNT_ID="[ACCOUNT_ID]"
R2_BUCKET="fircle-media"
R2_ACCESS_KEY_ID="[ACCESS_KEY_ID]"
R2_SECRET_ACCESS_KEY="[SECRET_ACCESS_KEY]"
R2_PUBLIC_BASE_URL="https://[PUBLIC_BUCKET_DOMAIN]"

Part 4

Post-deployment CORS policy

Configure CORS after deployment so you can use your final app domain. Copy the policy below, replace the domain placeholder, and paste it into the CORS settings for the bucket.

[
  {
    "AllowedOrigins": [
      "[DOMAIN URL]"
    ],
    "AllowedMethods": [
      "GET",
      "PUT",
      "HEAD"
    ],
    "AllowedHeaders": [
      "content-type"
    ]
  }
]

1. Deploy the app first and confirm final URL/domain.
2. Open Cloudflare R2 bucket settings and find CORS policy.
3. Replace [DOMAIN URL] with your deployed origin (for example, https://your-domain.com).
4. Keep the allowed methods as GET, PUT, and HEAD for Fircle uploads and reads.
5. Keep the allowed header as content-type.
6. Save, then re-test upload from the deployed app.

Cloudflare R2 CORS settings page before adding the final policy — 1. Open the CORS policy editor

Cloudflare R2 CORS policy editor with the JSON policy pasted in — 2. Paste the policy and replace the domain

Cloudflare R2 CORS policy saved with the final domain — 3. Save the completed CORS policy

Why this is post-deployment

CORS should reference the final deployed origin. Setting it too early can leave placeholder domains that fail in production.