S3 Storage
By default, Chatto stores file attachments (images, videos, documents) inside NATS JetStream object stores. This works well for small to medium deployments, but can put pressure on your NATS storage as usage grows.
Switching to an S3-compatible backend offloads file storage to a dedicated object store while keeping all other data (messages, users, spaces) in NATS.
How It Works
Section titled “How It Works”- New uploads go to S3 when configured
- Existing attachments stored in NATS continue to work — Chatto checks both backends when serving files
- URLs don’t change — the storage backend is an internal detail; asset URLs always use the same format
This means you can enable S3 at any time without migrating existing data. Old NATS-stored files remain accessible alongside new S3-stored ones.
Configuration
Section titled “Configuration”Set the storage backend to s3 and provide your bucket credentials:
CHATTO_CORE_ASSETS_STORAGE_BACKEND=s3CHATTO_CORE_ASSETS_S3_ENDPOINT=s3.amazonaws.comCHATTO_CORE_ASSETS_S3_BUCKET=chatto-assetsCHATTO_CORE_ASSETS_S3_REGION=eu-central-1CHATTO_CORE_ASSETS_S3_ACCESS_KEY_ID=your-access-keyCHATTO_CORE_ASSETS_S3_SECRET_ACCESS_KEY=your-secret-key[core.assets]storage_backend = "s3"
[core.assets.s3]endpoint = "s3.amazonaws.com"bucket = "chatto-assets"region = "eu-central-1"access_key_id = "your-access-key"secret_access_key = "your-secret-key"Chatto creates the bucket automatically on startup if it doesn’t exist.
All S3 Options
Section titled “All S3 Options”| Setting | Default | Description |
|---|---|---|
endpoint | — | S3 endpoint URL |
bucket | — | Bucket name |
region | — | AWS region (optional for non-AWS services) |
access_key_id | — | Access key |
secret_access_key | — | Secret key |
use_ssl | true | Use HTTPS for S3 connections |
path_style | false | Use path-style URLs instead of virtual-hosted. Required for most S3-compatible services (Cloudflare R2, Wasabi, etc.). |
S3-Compatible Services
Section titled “S3-Compatible Services”Any service that implements the S3 API works with Chatto. Set path_style = true for services that don’t support virtual-hosted bucket URLs.
CHATTO_CORE_ASSETS_STORAGE_BACKEND=s3CHATTO_CORE_ASSETS_S3_ENDPOINT=your-account-id.r2.cloudflarestorage.comCHATTO_CORE_ASSETS_S3_BUCKET=chatto-assetsCHATTO_CORE_ASSETS_S3_ACCESS_KEY_ID=your-access-keyCHATTO_CORE_ASSETS_S3_SECRET_ACCESS_KEY=your-secret-keyCHATTO_CORE_ASSETS_S3_PATH_STYLE=trueCHATTO_CORE_ASSETS_STORAGE_BACKEND=s3CHATTO_CORE_ASSETS_S3_ENDPOINT=s3.eu-central-1.wasabisys.comCHATTO_CORE_ASSETS_S3_BUCKET=chatto-assetsCHATTO_CORE_ASSETS_S3_REGION=eu-central-1CHATTO_CORE_ASSETS_S3_ACCESS_KEY_ID=your-access-keyCHATTO_CORE_ASSETS_S3_SECRET_ACCESS_KEY=your-secret-keyCHATTO_CORE_ASSETS_S3_PATH_STYLE=trueCHATTO_CORE_ASSETS_STORAGE_BACKEND=s3CHATTO_CORE_ASSETS_S3_ENDPOINT=s3.us-west-004.backblazeb2.comCHATTO_CORE_ASSETS_S3_BUCKET=chatto-assetsCHATTO_CORE_ASSETS_S3_REGION=us-west-004CHATTO_CORE_ASSETS_S3_ACCESS_KEY_ID=your-access-keyCHATTO_CORE_ASSETS_S3_SECRET_ACCESS_KEY=your-secret-keyCHATTO_CORE_ASSETS_S3_PATH_STYLE=trueSwitching Storage Backends
Section titled “Switching Storage Backends”You can switch from S3 back to NATS at any time — just change storage_backend back to nats. Existing S3 files remain accessible because Chatto checks both backends when serving attachments. New uploads will go to NATS.
When to Use S3
Section titled “When to Use S3”Stay with NATS (the default) if:
- Your team is small and file uploads are infrequent
- You want the simplest possible setup with no extra services
- Total attachment storage stays under a few GB
Switch to S3 if:
- You expect significant file, image, or video uploads
- You want to separate compute (NATS) from bulk storage
- You need to leverage existing S3 infrastructure or CDN integration
- You’re running NATS with replication — S3 avoids tripling storage costs for large files