mirror of
https://github.com/shumaiOne/shumai.git
synced 2026-11-22 11:17:14 +00:00
126 lines
5.1 KiB
Plaintext
126 lines
5.1 KiB
Plaintext
---
|
|
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://<account-id>.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://<account-id>.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
|
|
}
|
|
]
|
|
```
|