Skip to content
Chatto v0.5.0

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.

Asset typeBehavior
ImagesChatto serves resized WebP versions on request and caches them for seven days.
Documents and other filesChatto serves them through signed URLs.
VideosChatto accepts them only when video.enabled = true.
Animated GIFsChatto stores them as images. When video uploads are enabled, it also converts them to video.
Avatars, logos, bannersProfile and administrator permissions control them.
Link-preview imagesChatto downloads, limits, and stores them in the asset storage.
LimitDefaultSetting
All uploaded files, including GIFs and videos25 MBcore.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.

To attach a file, a member needs:

  • room membership
  • message.post, message.post-in-thread, or message.post-in-interactions, and read access for thread replies
  • message.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.

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.

DeploymentStorage
Small server, few uploads, a few GB in totalNATS (default)
Active community with many files or videosS3-compatible storage
Replicated NATS clusterS3-compatible storage, so that NATS does not copy large files to each node
Existing S3 or CDN infrastructureS3-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.

[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 creates the bucket at startup if it does not exist.

Setting (core.assets.s3.*)DefaultDescription
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_ssltrueUse HTTPS to connect to S3
path_styleautoURL 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:

Providerendpointregion
Cloudflare R2<account-id>.r2.cloudflarestorage.com—
Wasabis3.eu-central-1.wasabisys.comeu-central-1
Backblaze B2s3.us-west-004.backblazeb2.comus-west-004
  • 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 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 = true
max_concurrent_jobs = 2

video.enabled accepts video uploads and queues their processing. asset_processing.enabled starts the worker inside chatto run.

SettingDefaultDescription
video.enabledfalseAccept video uploads and queue processing
core.assets.max_upload_size25 MBMaximum size for all uploaded files
asset_processing.enabledfalseStart the worker inside chatto run
asset_processing.ffmpeg_pathfrom PATHPath to ffmpeg
asset_processing.ffprobe_pathfrom PATHPath to ffprobe
asset_processing.max_concurrent_jobs2Parallel jobs in each worker process
asset_processing.temp_dirsystem tempDirectory for temporary files

Transcoding uses much CPU. To keep this work away from the server processes, disable the built-in worker:

[video]
enabled = true
[asset_processing]
enabled = false
max_concurrent_jobs = 4

Then start one or more workers with the same configuration:

Terminal window
chatto asset-processing --config chatto.toml

This 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.

  1. Chatto stores the original upload immediately.
  2. The message shows the video as processing.
  3. A worker makes a thumbnail and six-second HLS segments. It converts audio to AAC stereo.
  4. 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.

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.

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.