Skip to content
Chatto v0.5.0

Docker Compose

Docker Compose is the quickest way to run the complete Chatto stack on one server. The example includes Chatto, NATS for persistent data, LiveKit for calls, and Caddy for automatic HTTPS.

You need Docker with Compose v2, a server with a public IP address, and an SMTP or JMAP provider. The commands below use chat.example.com for Chatto and livekit.chat.example.com for calls.

The LiveKit hostname is only an example. You can use any hostname you control, such as calls.example.com; pass your Chatto hostname to init-env.sh, then set CHATTO_LIVEKIT_URL and the matching proxy route to your chosen LiveKit hostname.

  1. Get the example

    Terminal window
    git clone --depth 1 https://github.com/chattocorp/chatto.git
    cd chatto/examples/dockercompose
  2. Point both domains at your server

    Create DNS records for chat.example.com and livekit.chat.example.com. Allow inbound TCP 80, 443, and 7881 plus UDP 3478 and 7882 in your host and cloud firewalls.

  3. Generate the configuration

    Terminal window
    ./init-env.sh chat.example.com admin@example.com

    Replace chat.example.com with your Chatto domain and admin@example.com with the email address you will use for the first account. The script generates .env and livekit.generated.yaml with matching NATS, Chatto, and LiveKit secrets. It also prepares the local backup directory.

  4. Configure transactional email

    Edit .env and replace the CHATTO_SMTP_* placeholders with your provider settings. SMTP is the default transport. Direct email/password registration, email verification, and password reset require transactional email; you can instead configure JMAP as described in Identity & Login.

    The SMTP example uses STARTTLS submission on port 587. For providers that require SMTPS on port 465, set CHATTO_SMTP_TLS=implicit.

    Set CHATTO_OWNERS_EMAILS to the email address you will use for the first account. Registration sends a code by email and creates the account with that email already verified; if it matches this list, Chatto assigns the owner role automatically.

  5. Start Chatto

    Terminal window
    docker compose up -d

    All services use the unless-stopped restart policy, so Docker restarts them after a failure or host reboot unless you stopped them manually.

    Caddy will automatically obtain TLS certificates for both domains. Visit https://chat.example.com to complete the first-run wizard. Choose a server name and create a local owner account, then sign in. Email delivery is not required. Restrict access until setup is complete: the first visitor can create the owner. For automated provisioning, set CHATTO_CORE_SKIP_SETUP_WIZARD=true and use the local operator API instead. Existing servers skip the wizard automatically.

That is enough for a complete single-server deployment. The remaining sections explain how the pieces fit together and how to customize them.

DOCKER NETWORK BrowserSvelteKit SPA :443CaddyTLS · Load Balancer :4222NATSJetStream · KV Store :4000ChattoConnectRPC · WebSocket :7880LiveKitWebRTC Media HTTPS WSS TCP :7881 · UDP :3478, :50000–50200
  • Chatto serves the web app and APIs.
  • NATS stores Chatto’s persistent data. Running it separately is the recommended production topology: you can restart or replace Chatto without restarting its data store, run multiple Chatto replicas against the same data, and grow into a NATS cluster later. The included nats-server.conf uses sync_interval: always because the example starts a single NATS server. NATS syncs each JetStream write to disk before it acknowledges the write. This policy reduces write throughput and protects recent acknowledged writes if the host stops without a normal shutdown.
  • LiveKit provides voice and video calls. Remove it if you do not need calls.
  • Caddy provides automatic HTTPS and reverse proxying. Replace it if you already use another proxy.

The standalone-binary setup embeds NATS inside Chatto, which is wonderfully simple for one process. Compose runs the same NATS JetStream storage as its own small container. This keeps the app and its data lifecycle separate and avoids a migration before adding Chatto replicas or zero-downtime app updates.

This choice does not lock in your data. chatto backup creates a portable JetStream archive that chatto restore can load into either embedded or external NATS. You can therefore move between the standalone-binary, Compose, and clustered deployment models without rebuilding your community. See Backup & Restore for the commands and key handling guidance.

You usually do not need to: init-env.sh generates the secrets and config files for you. If you manage secrets elsewhere, start with .env.example, fill in its placeholders, and make sure the LiveKit key and secret are the same in .env and livekit.yaml. Also prepare the backup directory:

Terminal window
mkdir -p backups
chmod 700 backups

The image runs Chatto as a non-root user. By default that user is 1000:1000; set PUID and PGID in your shell or Compose environment if the files mounted into /config or /data are owned by a different host user or group. The entrypoint does not recursively change ownership of mounted directories, so make sure writable mounts are owned by the configured IDs.

The generated .env also enables Chatto’s local operator API socket at /tmp/chatto/operator.sock inside the app container. Run operator commands with docker compose exec as the chatto user, and use list --search to find a stable user ID before mutating an account:

Terminal window
docker compose exec -u chatto chatto /chatto operator user list
docker compose exec -u chatto chatto /chatto operator user list --search admin@example.com
docker compose exec -u chatto chatto /chatto operator user set-password USER_ID

Do not mount or publish the operator socket unless the target container or host is fully trusted; socket access is root-equivalent Chatto authority.

If you set a memory limit on the Chatto container, Chatto sets the Go memory limit to 90% of it. Go then frees unused memory before the container reaches its limit. To use a different value, set the GOMEMLIMIT environment variable, for example GOMEMLIMIT=900MiB. Do not mount /tmp as a memory-backed tmpfs: uploads write temporary files there, and these files count against the container memory limit.

StorageContents
nats_data volumeNATS and JetStream data
caddy_data volumeTLS certificates from Let’s Encrypt
caddy_config volumeCaddy runtime configuration cache
CHATTO_BACKUP_DIR bind mountChatto backup archives; defaults to ./backups

Use chatto backup to back up NATS and JetStream data. Do not copy the live nats_data volume. By default, Chatto also stores file attachments and media in NATS. For heavier usage, you can move them to S3-compatible storage. You must back up S3 data separately.

The passphrase is optional. Run docker compose run --rm chatto backup to create an unencrypted backup without encryption keys. We recommend encrypted backups. Always use encryption when you include encryption keys or store a backup outside the server.

Create an encrypted backup while Chatto is running:

Terminal window
docker compose run --rm chatto backup \
--encrypt \
--include-keys

This command starts a temporary container from the existing chatto service. The container uses the same image, environment, and private NATS connection as the running server. Chatto prompts you to enter and confirm the passphrase. It then writes a timestamped archive to the host directory selected by CHATTO_BACKUP_DIR.

Copy the archive to storage on a different host. Also keep separate copies of the passphrase, .env, and livekit.generated.yaml. If you use S3 storage, back up that storage separately.

Stop all Chatto replicas before you restore an archive. Keep NATS running:

Terminal window
docker compose stop chatto
docker compose run --rm chatto restore \
/backups/2026-09-04T12-00-00Z.tar.gz.age
docker compose up -d chatto

Chatto detects whether an archive is encrypted and prompts for its passphrase. An unencrypted archive does not require a passphrase.

Restore fails by default if the target contains a backed-up stream. Add --conflict=overwrite only when you intend to replace the existing data. If you previously scaled Chatto, include the required scale when you start it again, for example docker compose up -d --scale chatto=5.

See Backup & Restore for retention, automation, conflict handling, S3 data, and complete recovery guidance.

Already running Caddy, nginx, Apache, Traefik, or another user-facing web server? You can keep it. Chatto needs only two HTTP reverse-proxy routes:

  • Your Chatto HTTPS hostname routes to Chatto on port 4000.
  • Your chosen LiveKit secure WebSocket hostname routes to LiveKit on port 7880.

For example, the hostnames could be chat.example.com and calls.example.com. They do not need to share a parent domain or use the name livekit. Both need publicly trusted TLS certificates.

If your proxy joins the Compose network, route directly to chatto:4000 and livekit:7880. If it runs on the Docker host, replace those services’ expose entries with loopback-only mappings such as 127.0.0.1:4000:4000 and 127.0.0.1:7880:7880. Then remove the caddy service and its volumes from compose.yml.

If you do not already have a proxy, the included Caddy configuration obtains certificates, creates both routes, and load-balances Chatto replicas:

chat.example.com {
reverse_proxy {
dynamic a chatto 4000 {
refresh 5s
versions ipv4
}
lb_policy round_robin
}
}
livekit.chat.example.com {
reverse_proxy livekit:7880
}

The first route carries the Chatto web app, APIs, realtime connections, and LiveKit webhooks. The second carries LiveKit’s API and WebSocket signaling. Caddy handles WebSocket upgrades automatically.

The dynamic DNS upstream discovers each scaled Chatto container separately. Caddy refreshes the list and distributes new requests across healthy replicas; existing realtime connections stay with the replica that accepted them.

The example publishes LiveKit’s Layer 4 media ports directly from its container to the host:

Public portDestinationProtocol and purpose
TCP 80CaddyHTTP redirect and ACME HTTP challenge
TCP 443CaddyHTTPS and secure WebSocket traffic for both domains
TCP 7881LiveKit 7881WebRTC media fallback when UDP is unavailable
UDP 3478LiveKit 3478Embedded TURN/STUN relay
UDP 7882LiveKit 7882Direct WebRTC media

The standard Caddy image does not include the optional Caddy L4 plugin, and this single-host setup does not need it. Open the matching host and cloud firewall rules, and do not expose NATS port 4222 publicly.

LiveKit also needs DNS and outbound UDP for STUN-based public-IP discovery. See Voice & Video Calls for private STUN and fixed-IP alternatives.

Direct Registration and Transactional Email

Section titled “Direct Registration and Transactional Email”

The setup above enables direct email/password registration, which requires transactional email because Chatto sends registration codes by email. The provided .env uses SMTP, the default transport. You can instead configure JMAP as described in Identity & Login. Transactional email is also used for email verification and password reset.

If you do not want public email/password registration after the first owner exists, set CHATTO_AUTH_DIRECT_REGISTRATION=false. Existing users can still sign in with passwords or configured SSO providers. For an SSO-only deployment, configure and test a provider first, then also set CHATTO_AUTH_DIRECT_LOGIN=false on every replica.

For notifications when the browser is closed. Generate VAPID keys with npx web-push generate-vapid-keys, then add to .env:

Terminal window
CHATTO_PUSH_ENABLED=true
CHATTO_PUSH_VAPID_PUBLIC_KEY=BNx...
CHATTO_PUSH_VAPID_PRIVATE_KEY=...
CHATTO_PUSH_VAPID_SUBJECT=admin@example.com

The official Chatto Docker image includes ffmpeg. To allow video uploads and run the built-in asset-processing worker, add to .env:

Terminal window
CHATTO_VIDEO_ENABLED=true
CHATTO_ASSET_PROCESSING_ENABLED=true
# Optional tuning
# CHATTO_ASSET_PROCESSING_MAX_CONCURRENT_JOBS=2
# CHATTO_CORE_ASSETS_MAX_UPLOAD_SIZE=100MB
# CHATTO_ASSET_PROCESSING_TEMP_DIR=/tmp

If you don’t need voice and video calls, simplify the stack by:

  1. Removing the livekit service from compose.yml
  2. Deleting the selected LiveKit config (livekit.generated.yaml or livekit.yaml)
  3. Removing the livekit.* block from the Caddyfile
  4. Removing the CHATTO_LIVEKIT_* variables from .env

You won’t need the livekit.* subdomain, TCP 7881, or the LiveKit UDP ports.

The default setup exposes LiveKit’s muxed direct UDP media port and its embedded TURN/UDP relay:

ports:
- "7882:7882/udp"
- "7881:7881/tcp"
- "3478:3478/udp"

The generated and checked-in LiveKit configs enable the matching TCP fallback and relay:

rtc:
tcp_port: 7881
udp_port: 7882
turn:
enabled: true
udp_port: 3478

Direct UDP provides the best media path. TCP 7881 gives LiveKit an ICE/TCP fallback when UDP is unavailable, while TURN/UDP helps with symmetric NATs and many mobile, Firefox, and restrictive-network failures. This keeps the Compose example certificate-free beyond the HTTPS certificates managed by Caddy.

Networks that block UDP entirely still need TURN/TLS.

See Voice & Video Calls for the full TURN tradeoffs, including when to use a dedicated TURN server.

Chatto can’t connect to NATS — Ensure NATS_TOKEN and CHATTO_NATS_CLIENT_TOKEN match in .env.

Registration says email delivery is not configured — Direct email/password registration requires transactional email. For SMTP, set CHATTO_SMTP_ENABLED=true and configure CHATTO_SMTP_HOST, CHATTO_SMTP_PORT, CHATTO_SMTP_TLS, and CHATTO_SMTP_FROM. Use CHATTO_SMTP_TLS=implicit for SMTPS providers on port 465. For JMAP, set CHATTO_EMAIL_TRANSPORT=jmap, CHATTO_EMAIL_JMAP_SESSION_URL, CHATTO_EMAIL_JMAP_ACCESS_TOKEN, and CHATTO_EMAIL_JMAP_FROM.

The first account is not an owner — Make sure CHATTO_OWNERS_EMAILS contains the verified email address for that account. For an already-verified account, restart Chatto after updating the variable; Chatto applies matching owner roles on boot.

Caddy not getting certificates — Verify DNS records point to your server and ports 80/443 are open. Check docker compose logs caddy for ACME errors.

Calls don’t connect — Verify the LiveKit API key/secret in .env matches the selected LiveKit config (livekit.generated.yaml or livekit.yaml). Ensure CHATTO_LIVEKIT_URL uses the public wss://livekit.* subdomain (browsers connect to it directly). Check that TCP 7881 and UDP 3478 and 7882 are open in your firewall. For a LAN-only host without an external IP address, set rtc.use_external_ip: false in livekit.generated.yaml before starting or restarting LiveKit.

LiveKit reports could not resolve external IP — Allow DNS and outbound UDP from the LiveKit container to every endpoint in rtc.stun_servers. If public STUN is not acceptable, configure private STUN servers or set a stable public rtc.node_ip with rtc.use_external_ip: false.

Calls fail for some users — Confirm the built-in TURN/UDP relay is reachable on UDP 3478. Users behind firewalls that block UDP entirely need TURN/TLS. See TURN server for restrictive networks.