S3 Source
The S3 source allows PreviewProxy to fetch images directly from an Amazon S3 bucket or any S3-compatible object storage (such as Cloudflare R2, or Backblaze B2).
Enabling the S3 Source
The S3 source is disabled by default. Set S3_ENABLED=true along with the required credentials to activate it.
Configuration
Required Variables
| Variable | Description |
|---|---|
S3_ENABLED | Set to true to enable the S3 source. |
S3_BUCKET | Name of the S3 bucket to fetch images from. |
S3_ACCESS_KEY_ID | AWS access key ID (or equivalent for S3-compatible storage). |
S3_SECRET_ACCESS_KEY | AWS secret access key (or equivalent for S3-compatible storage). |
Optional Variables
| Variable | Default | Description |
|---|---|---|
S3_REGION | us-east-1 | AWS region where the bucket is hosted. |
S3_ENDPOINT | (unset) | Custom endpoint URL for S3-compatible storage providers. |
Example Configuration
S3_ENABLED=true
S3_BUCKET=my-assets
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
S3_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
# For Cloudflare R2 or S3-compatible storage:
# S3_ENDPOINT=https://<account_id>.r2.cloudflarestorage.com
URL Scheme
To request an image from S3, use the s3: scheme in the image URL portion of the path. Note that the scheme uses a single slash after the colon (not two):
/800x600,webp/s3:/images/product/photo.jpg
The path after s3:/ is the object key within the configured bucket.
Examples
| Request | Object Key Fetched |
|---|---|
/w=400/s3:/banner.jpg | banner.jpg |
/800x600,webp/s3:/images/product/photo.jpg | images/product/photo.jpg |
/format=avif/s3:/2024/uploads/avatar.png | 2024/uploads/avatar.png |
Using with Cloudflare R2
To use PreviewProxy with Cloudflare R2, set S3_ENDPOINT to the S3 API address:
S3_ENABLED=true
S3_BUCKET=my-assets
S3_REGION=auto
S3_ACCESS_KEY_ID=<access_key>
S3_SECRET_ACCESS_KEY=<secret_key>
S3_ENDPOINT=https://<account_id>.r2.cloudflarestorage.com
The S3_ENDPOINT variable works with any S3-compatible API, not just AWS. You can use it for Cloudflare R2, Backblaze B2, DigitalOcean Spaces, and others by pointing it at their respective S3-compatible endpoint URLs.