Skip to content
Chatto

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, rooms) 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 — each asset remembers which backend stores its bytes
  • URLs don’t change — the storage backend is an internal detail; asset URLs always use the same format
  • S3 prefixes are movable — Chatto stores prefix-free asset keys, so you can move objects to a different S3 prefix and update config without rewriting Chatto metadata

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:

Terminal window
CHATTO_CORE_ASSETS_STORAGE_BACKEND=s3
CHATTO_CORE_ASSETS_S3_ENDPOINT=s3.amazonaws.com
CHATTO_CORE_ASSETS_S3_BUCKET=chatto-assets
CHATTO_CORE_ASSETS_S3_PATH_PREFIX=production/chatto
CHATTO_CORE_ASSETS_S3_REGION=eu-central-1
CHATTO_CORE_ASSETS_S3_ACCESS_KEY_ID=your-access-key
CHATTO_CORE_ASSETS_S3_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”
SettingDefaultDescription
endpoint—S3 endpoint URL
bucket—Bucket name
path_prefix—Optional object key prefix for all S3 assets. Leading/trailing slashes are ignored.
region—AWS region (optional for non-AWS services)
access_key_id—Access key
secret_access_key—Secret key
use_ssltrueUse HTTPS for S3 connections
path_stylefalseUse 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.

Terminal window
CHATTO_CORE_ASSETS_STORAGE_BACKEND=s3
CHATTO_CORE_ASSETS_S3_ENDPOINT=your-account-id.r2.cloudflarestorage.com
CHATTO_CORE_ASSETS_S3_BUCKET=chatto-assets
CHATTO_CORE_ASSETS_S3_ACCESS_KEY_ID=your-access-key
CHATTO_CORE_ASSETS_S3_SECRET_ACCESS_KEY=your-secret-key
CHATTO_CORE_ASSETS_S3_PATH_STYLE=true

Switching 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 each asset records its storage backend. New uploads will go to NATS. You can also change path_prefix after moving or copying the S3 objects to the new prefix. Chatto stores logical, prefix-free asset keys in NATS, so no Chatto metadata rewrite is needed.

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
Environment Variables Full reference for all configuration options.