BunshipBunship
Integrations

S3-Compatible Storage

Practical storage setup for Bunship: exact env values, R2-first setup, and production validation steps.

If storage is wrong, Bunship will fail in visible places: avatar upload, CMS cover upload, and AI output URLs.

This page focuses on the fastest production-safe setup.

Use Cloudflare R2 first unless your team already runs on AWS.

  • lower egress risk in common CDN setups
  • fully S3-compatible with Bunship
  • quickest path to stable uploads

What Bunship Needs

Bunship only needs these 6 variables to run uploads end-to-end:

  • S3_ENDPOINT
  • S3_REGION
  • S3_ACCESS_KEY
  • S3_SECRET_KEY
  • S3_BUCKET
  • NEXT_PUBLIC_S3_URL_BASE

Use NEXT_PUBLIC_S3_URL_BASE (not S3_URL_BASE) as the public URL prefix used by the app.

Quick Setup: Cloudflare R2

1. Create bucket

Create one bucket, for example: bunship-prod.

2. Create API token

Create an R2 API token with read/write access to that bucket.

3. Get endpoint and public URL base

  • Endpoint format: https://<ACCOUNT_ID>.r2.cloudflarestorage.com
  • Public URL base:
    • your CDN/custom domain, or
    • R2 public domain (if enabled)

4. Fill environment variables

S3_ENDPOINT="https://<ACCOUNT_ID>.r2.cloudflarestorage.com"
S3_REGION="auto"
S3_ACCESS_KEY="<R2_ACCESS_KEY_ID>"
S3_SECRET_KEY="<R2_SECRET_ACCESS_KEY>"
S3_BUCKET="bunship-prod"
NEXT_PUBLIC_S3_URL_BASE="https://cdn.yourdomain.com"

5. Restart web and api services

After env changes, restart both services so upload clients reload config.

Production Validation (Must Pass)

  1. Upload an image from user flow.
  2. Upload/generate a CMS post cover from admin.
  3. Trigger an AI generation task and open returned file URL.

If all 3 succeed, your storage integration is basically healthy.

Common Misconfigurations

  1. 403 or signature mismatch: endpoint/region/key do not match same provider account.
  2. Upload succeeded but URL is broken: NEXT_PUBLIC_S3_URL_BASE is wrong or bucket is not public via CDN.
  3. Works locally but fails in production: web/api env variables are inconsistent.
  4. Sudden cost spike: no CDN caching policy + large media payloads.

When to Choose AWS S3 Instead

Choose S3 directly if you already have:

  • existing AWS networking and IAM policy setup
  • mandatory AWS compliance requirements
  • centralized AWS cost and logging workflows

Next Steps

Environment Config

Check all required env variables per app.

AI Image Workflow

AI output reliability depends on storage delivery.

Marketing Site and CMS

CMS assets and blog covers use the same storage base URL.

Task Queue

Pluggable task queue supporting Trigger.dev and BullMQ — auto-detected via environment variables.

Component Library and Blocks

Reusable component workspace for fast rebrand and consistent product/admin/marketing UI.

On this page

TL;DR (Recommended)
What Bunship Needs
Quick Setup: Cloudflare R2
1. Create bucket
2. Create API token
3. Get endpoint and public URL base
4. Fill environment variables
5. Restart web and api services
Production Validation (Must Pass)
Common Misconfigurations
When to Choose AWS S3 Instead
Next Steps