Files & Media
Members can upload files, images, avatars, and server branding images. Chatto also stores link-preview images and, when you enable it, processes videos and animated GIFs. By default, Chatto keeps these assets in NATS. For many or large files, use S3-compatible storage.
What Members Can Upload
Section titled “What Members Can Upload”| Asset type | Behavior |
|---|---|
| Images | Chatto serves resized WebP versions on request and caches them for seven days. |
| Documents and other files | Chatto serves them through signed URLs. |
| Videos | Chatto accepts them only when video.enabled = true. |
| Animated GIFs | Chatto stores them as images. When video uploads are enabled, it also converts them to video. |
| Avatars, logos, banners | Profile and administrator permissions control them. |
| Link-preview images | Chatto downloads, limits, and stores them in the asset storage. |
| Limit | Default | Setting |
|---|---|---|
| All uploaded files, including GIFs and videos | 25 MB | core.assets.max_upload_size |
GIF uploads above the image animation limits require video.enabled = true.
File size, image dimensions, and per-frame pixel limits still apply. These
GIFs play as converted video. Image previews of the original GIF keep the
image animation limits. GIFs sent to video processing use its thumbnail when
available. Chatto provides no thumbnail URL while processing is pending or
when processing ends without a thumbnail.
Set one limit for all files:
[core.assets]max_upload_size = "100MB"If you use video.max_upload_size or CHATTO_VIDEO_MAX_UPLOAD_SIZE, set the
desired limit in core.assets.max_upload_size or
CHATTO_CORE_ASSETS_MAX_UPLOAD_SIZE, then remove the old video size setting.
Until you remove it, the larger of the two limits applies to all files. If the
general limit is absent, its 25 MB default participates in this comparison.
The old implicit 100 MB video default no longer applies. Set the general limit
to 100MB to keep that allowance. Video upload enablement remains a separate
setting.
For operator-managed servers, set spec.assets.maxUploadSize to the desired
limit and remove spec.assets.maxVideoUploadSize when the operator supports
this migration. To keep one policy during a server rollout, set both fields to
the desired limit before you upgrade the server.
Browsers upload message attachments in chunks of up to 10 MiB. If your reverse proxy limits the request body size, allow at least 11 MiB for each request. Avatar and branding uploads can need larger request bodies.
Permission And Access Model
Section titled “Permission And Access Model”To attach a file, a member needs:
- room membership
message.post,message.post-in-thread, ormessage.post-in-interactions, and read access for thread repliesmessage.attach
Attachment URLs are signed for one user and expire. Each request also checks that this user can still read the room. When a member leaves the room or loses access, old URLs stop working for them.
Link Previews
Section titled “Link Previews”When a member writes a message with a URL, the Chatto server fetches the page
metadata and preview image. The linked site sees the server’s IP address, not
the member’s. The fetcher blocks private and special-use network addresses,
including shared-address space (100.64.0.0/10) and standard NAT64 ranges
(64:ff9b::/96 and 64:ff9b:1::/48). If your server uses only NAT64 to reach
a linked site, provide native IPv4 or IPv6 connectivity for previews. Results
are cached for a limited time. You do not need a separate worker.
Embedded Vimeo players connect the member’s browser directly to Vimeo, which receives the member’s IP address. This connection is separate from the server request for link-preview metadata.
For supported Bluesky and Mastodon previews, the server gets the post details and images. Clients show the stored preview without contacting those services.
Storage Backend Choice
Section titled “Storage Backend Choice”| Deployment | Storage |
|---|---|
| Small server, few uploads, a few GB in total | NATS (default) |
| Active community with many files or videos | S3-compatible storage |
| Replicated NATS cluster | S3-compatible storage, so that NATS does not copy large files to each node |
| Existing S3 or CDN infrastructure | S3-compatible storage |
Each asset records its storage backend. When you change the backend, new assets go to the new backend, and existing assets stay readable. Asset URLs do not change.
S3 Storage
Section titled “S3 Storage”[core.assets]storage_backend = "s3"
[core.assets.s3]endpoint = "s3.amazonaws.com"bucket = "chatto-assets"path_prefix = "production/chatto"region = "eu-central-1"access_key_id = "<generate-me>"secret_access_key = "<generate-me>"CHATTO_CORE_ASSETS_STORAGE_BACKEND=s3CHATTO_CORE_ASSETS_S3_ENDPOINT=s3.amazonaws.comCHATTO_CORE_ASSETS_S3_BUCKET=chatto-assetsCHATTO_CORE_ASSETS_S3_PATH_PREFIX=production/chattoCHATTO_CORE_ASSETS_S3_REGION=eu-central-1CHATTO_CORE_ASSETS_S3_ACCESS_KEY_ID=<generate-me>CHATTO_CORE_ASSETS_S3_SECRET_ACCESS_KEY=<generate-me>Chatto creates the bucket at startup if it does not exist.
Setting (core.assets.s3.*) | Default | Description |
|---|---|---|
endpoint | — | S3 endpoint host |
bucket | — | Bucket name |
path_prefix | — | Optional key prefix for all objects |
region | — | Region. Optional for services other than AWS. |
access_key_id, secret_access_key | — | Credentials |
use_ssl | true | Use HTTPS to connect to S3 |
path_style | auto | URL addressing. auto uses virtual-hosted URLs for AWS and path-style URLs for other endpoints. |
Any service with the S3 API works. Examples of endpoints:
| Provider | endpoint | region |
|---|---|---|
| Cloudflare R2 | <account-id>.r2.cloudflarestorage.com | — |
| Wasabi | s3.eu-central-1.wasabisys.com | eu-central-1 |
| Backblaze B2 | s3.us-west-004.backblazeb2.com | us-west-004 |
Change the storage configuration
Section titled “Change the storage configuration”- To go back to NATS, set
storage_backend = "nats". Files in S3 stay readable. - To change
path_prefix, first move or copy the objects to the new prefix. Chatto stores keys without the prefix, so it needs no other change.
chatto backup does not include S3 objects. Back them up with your storage
provider. See Backup & Restore.
Video Processing
Section titled “Video Processing”Video uploads are off by default. When you enable them, a worker makes a thumbnail and adaptive HLS renditions for each video and animated GIF.
If you run the Chatto binary outside Docker, install the ffmpeg package,
which provides both ffmpeg and ffprobe.
[video]enabled = true
[asset_processing]enabled = truemax_concurrent_jobs = 2CHATTO_VIDEO_ENABLED=trueCHATTO_ASSET_PROCESSING_ENABLED=trueCHATTO_ASSET_PROCESSING_MAX_CONCURRENT_JOBS=2video.enabled accepts video uploads and queues their processing.
asset_processing.enabled starts the worker inside chatto run.
| Setting | Default | Description |
|---|---|---|
video.enabled | false | Accept video uploads and queue processing |
core.assets.max_upload_size | 25 MB | Maximum size for all uploaded files |
asset_processing.enabled | false | Start the worker inside chatto run |
asset_processing.ffmpeg_path | from PATH | Path to ffmpeg |
asset_processing.ffprobe_path | from PATH | Path to ffprobe |
asset_processing.max_concurrent_jobs | 2 | Parallel jobs in each worker process |
asset_processing.temp_dir | system temp | Directory for temporary files |
Run workers separately
Section titled “Run workers separately”Transcoding uses much CPU. To keep this work away from the server processes, disable the built-in worker:
[video]enabled = true
[asset_processing]enabled = falsemax_concurrent_jobs = 4Then start one or more workers with the same configuration:
chatto asset-processing --config chatto.tomlThis command always runs the worker, independently of
asset_processing.enabled. The worker must reach the same NATS server and
asset storage. Set nats.client.url. If Chatto uses embedded NATS, expose its
client port to the trusted network only.
Workers share one queue. Each job goes to one worker. If a worker stops during a job, another worker does the job again. While no worker runs, members can still send messages, and their videos stay in processing.
Processing behavior
Section titled “Processing behavior”- Chatto stores the original upload immediately.
- The message shows the video as processing.
- A worker makes a thumbnail and six-second HLS segments. It converts audio to AAC stereo.
- The player starts adaptive playback. Seeking works with NATS and S3 storage.
A job can use 30 minutes. After that, Chatto records a failure and does not try again. If processing fails, for example with an unsupported codec, the member sees an error and can upload again. Videos from older Chatto versions keep their MP4 files.
Chatto stores the original, the thumbnail, and the HLS segments. Put
asset_processing.temp_dir on fast disk with space for the jobs that run at
the same time.
Active Document Safety
Section titled “Active Document Safety”Chatto streams original attachments with nosniff. It also adds a sandbox
policy and Referrer-Policy: no-referrer for all types except passive types:
PNG, JPEG, GIF, WebP, AVIF, video, audio, plain text, and PDF. Files with a
missing or malformed content type are served as application/octet-stream in
the sandbox. With S3 storage, only files of passive types can redirect to S3.
Chatto streams all other files itself, including large archives. This keeps the
sandbox headers in place.
See Environment Variables for all asset settings.
Asset Cache Upgrades
Section titled “Asset Cache Upgrades”Remove [core.assets.cache] and the CHATTO_CORE_ASSETS_CACHE_ENABLED and
CHATTO_CORE_ASSETS_CACHE_TTL environment variables from your configuration.
Caching is always enabled with a seven-day lifetime. During a rolling upgrade,
older replicas can still apply their configured cache lifetime. The fixed
lifetime takes full effect when the rollout completes.
After all replicas use the shared cache, you can delete the legacy NATS Object
Store bucket NEIGHBORHOOD_IMAGES. Chatto does not delete it automatically.
Neighborhood images can be temporarily unavailable while the cache rebuilds.