Standalone Binary

Caution

For production deployments, Docker Compose is the recommended approach. It handles service orchestration, automatic restarts, and makes it easy to add LiveKit for voice and video calls. The standalone binary approach described here is best suited for development, testing, or minimal single-server setups.

Chatto ships as a single binary with an embedded NATS server and built-in Let’s Encrypt TLS. No reverse proxy, no external database — just one process serving everything.

Architecture

The Chatto binary includes an embedded NATS server with JetStream for storage. All chat data is stored in the ./data/ directory. The built-in TLS support handles certificate provisioning and renewal automatically via Let’s Encrypt.

Prerequisites

• A server with the Chatto binary (download from GitHub Releases)
• A domain pointing to your server (e.g., chat.example.com)
• Firewall allowing inbound TCP 80 and 443

Setup

By the end of this section, your deployment directory will look like this:

• chatto (binary)
• chatto.toml
• Directorydata/ (created automatically)

  • …
• Directory.chatto/certs/ (created automatically)

  • …

1. Create chatto.toml

   [webserver]
   url = "https://chat.example.com"
   cookie_signing_secret = "<generate-me>"
   
   [webserver.tls]
   enabled = true
   domain = "chat.example.com"
   email = "admin@example.com"
   
   [core.assets]
   signing_secret = "<generate-me>"

   Replace all <generate-me> values with output from openssl rand -hex 32.

   When TLS is enabled and no port is specified, Chatto defaults to port 443 for HTTPS and port 80 for ACME challenges.

2. Grant port binding privileges

   Ports 80 and 443 require elevated privileges on Linux. Instead of running as root, grant the binary the CAP_NET_BIND_SERVICE capability:

   sudo setcap cap_net_bind_service=ep ./chatto

   Note

   This capability is tied to the binary file itself. You’ll need to re-run this command after updating the Chatto binary.

   On macOS, setcap is not available. Use sudo to run the binary, or run on higher ports behind a reverse proxy.

3. Start Chatto

   ./chatto run -c chatto.toml

   Chatto will start the embedded NATS server, obtain a TLS certificate from Let’s Encrypt, and begin serving on port 443. Visit https://chat.example.com to create your first account.

Running as a systemd Service

For production use on Linux, create a systemd unit to manage the process:

/etc/systemd/system/chatto.service

[Unit]
Description=Chatto
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=chatto
Group=chatto
WorkingDirectory=/opt/chatto
ExecStart=/opt/chatto/chatto run -c chatto.toml
Restart=always
RestartSec=5
AmbientCapabilities=CAP_NET_BIND_SERVICE

[Install]
WantedBy=multi-user.target

sudo systemctl enable --now chatto

Tip

Using AmbientCapabilities=CAP_NET_BIND_SERVICE in the unit file grants the capability at runtime, so you don’t need to setcap the binary separately. This is the preferred approach when using systemd.

Persistent Data

All data is stored by the embedded NATS server in the data/ directory (configurable via CHATTO_NATS_EMBEDDED_DATA_DIR). Back up this directory regularly.

TLS certificates are cached in .chatto/certs/ (configurable via CHATTO_WEBSERVER_TLS_CACHE_DIR). These are automatically re-fetched if deleted, but caching avoids unnecessary Let’s Encrypt requests.

Using Higher Ports

If you can’t use ports 80/443 (e.g., another service already binds them), configure higher ports:

[webserver]
port = 8443

[webserver.tls]
http_port = 8080

Caution

Let’s Encrypt HTTP-01 validation requires port 80 to be publicly reachable. If you use a different HTTP port, you’ll need to redirect external port 80 to your configured http_port (e.g., via iptables or a load balancer).

Adding Voice and Video Calls

The standalone binary doesn’t include LiveKit. To add voice and video calls, you have two options:

1. Switch to Docker Compose (recommended) — the Docker Compose guide includes LiveKit out of the box.
2. Run LiveKit separately — install and run a LiveKit server alongside Chatto, then configure the LiveKit environment variables.

Docker Compose Recommended production deployment with LiveKit and Caddy.

Environment Variables Full reference for all configuration options.

Backup & Restore How to back up and restore your Chatto data.