--- title: S3 Compatible Storage description: Configure AWS S3 or any S3-compatible storage backend (Cloudflare R2, MinIO, Google Cloud Storage, etc.) for Shumai. --- Shumai uses Bun's high-performance native S3 client to store and serve creative assets. By utilizing standard S3 APIs, Shumai can connect to any S3-compatible storage provider, including AWS S3, Cloudflare R2, MinIO, Google Cloud Storage, and more. Using external S3 storage is highly recommended for production teams. It allows you to separate storage from the application server, scale storage capacity independently, and support distributed media transcoding. --- ## Configuration Variables To enable S3-compatible storage, update the following environment variables in your `.env` file or Docker Compose configuration: | Variable | Description | Required | Default / Example | | :------------------------- | :------------------------------------------------------------------------ | :------- | :----------------------------------- | | `STORAGE_BACKEND` | Set to `s3` to enable S3 compatible storage. | Yes | `s3` | | `S3_BUCKET` | The name of the S3 bucket where files will be stored. | Yes | `shumai-bucket` | | `S3_REGION` | The region of your S3 bucket. | No | `auto` | | `S3_ACCESS_KEY_ID` | The access key ID for your storage service. | Yes | `your-access-key-id` | | `S3_SECRET_ACCESS_KEY` | The secret access key for your storage service. | Yes | `your-secret-access-key` | | `AWS_ENDPOINT_URL_S3` | The endpoint URL of your S3 compatible storage provider. | Yes | `https://s3.us-east-1.amazonaws.com` | | `PRESIGNED_URL_EXPIRES_IN` | Duration in hours before generated presigned download/upload URLs expire. | No | `5` | --- ## Provider Examples Below are configuration templates for popular S3 providers. Add these variables to your `.env` file or under the `environment` section in your `docker-compose.yaml`. ### AWS S3 For standard AWS S3, configure the corresponding endpoint URL: ```env STORAGE_BACKEND=s3 S3_BUCKET=your-shumai-bucket S3_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE S3_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY AWS_ENDPOINT_URL_S3=https://s3.us-east-1.amazonaws.com ``` ### Cloudflare R2 Cloudflare R2 requires your Cloudflare account ID to construct the endpoint URL. Set the region to `auto`: ```env STORAGE_BACKEND=s3 S3_BUCKET=your-shumai-bucket S3_ACCESS_KEY_ID=your-r2-access-key-id S3_SECRET_ACCESS_KEY=your-r2-secret-access-key AWS_ENDPOINT_URL_S3=https://.r2.cloudflarestorage.com ``` ### MinIO (Self-Hosted) For local development or self-hosted environments using MinIO, set the endpoint to your MinIO server URL and port (usually `9000`): ```env STORAGE_BACKEND=s3 S3_BUCKET=shumai S3_ACCESS_KEY_ID=minioadmin S3_SECRET_ACCESS_KEY=minioadmin AWS_ENDPOINT_URL_S3=http://localhost:9000 ``` ### Google Cloud Storage (GCS) Google Cloud Storage provides an S3-compatible XML API. Configure your HMAC credentials and set the endpoint to standard GCS storage: ```env STORAGE_BACKEND=s3 S3_BUCKET=your-gcs-bucket S3_ACCESS_KEY_ID=GOOG1EXAMPLETOCKENKEY S3_SECRET_ACCESS_KEY=your-gcs-hmac-secret-access-key AWS_ENDPOINT_URL_S3=https://storage.googleapis.com ``` ### DigitalOcean Spaces For DigitalOcean Spaces, set the endpoint URL to match your space's region: ```env STORAGE_BACKEND=s3 S3_BUCKET=your-spaces-bucket S3_ACCESS_KEY_ID=your-spaces-access-key-id S3_SECRET_ACCESS_KEY=your-spaces-secret-access-key AWS_ENDPOINT_URL_S3=https://nyc3.digitaloceanspaces.com ``` ### Supabase Storage To connect to Supabase Storage via S3, ensure you have enabled S3 connection support in the Supabase Dashboard (`Settings > Storage > Enable connection via S3 protocol`). Copy the endpoint URL and region details from the same settings page: ```env STORAGE_BACKEND=s3 S3_BUCKET=your-supabase-bucket S3_REGION=us-east-1 S3_ACCESS_KEY_ID=your-supabase-access-key-id S3_SECRET_ACCESS_KEY=your-supabase-secret-access-key AWS_ENDPOINT_URL_S3=https://.supabase.co/storage/v1/s3 ``` --- ## CORS Configuration Since Shumai uploads files directly from the user's browser using presigned URLs, you must configure **Cross-Origin Resource Sharing (CORS)** on your storage bucket. Without CORS configuration, uploads will fail with network or origin errors. Ensure your bucket CORS policy allows the following rules from your Shumai application URL (e.g., `http://localhost:3000` or `https://app.shumai.one`): ### CORS JSON Policy Example (AWS S3, R2, GCS) ```json [ { "AllowedHeaders": ["*"], "AllowedMethods": ["GET", "PUT", "POST", "DELETE", "HEAD"], "AllowedOrigins": ["http://localhost:3000", "https://your-shumai-domain.com"], "ExposeHeaders": ["ETag"], "MaxAgeSeconds": 3000 } ] ```