Server quick start
This guide sets up the default deployment: the relay owns public port 443, terminates TLS 1.3 itself and gets its certificate from Let’s Encrypt with the built-in ACME client. There is no port 80, no certbot and no proxy in front. For FreeBSD, see FreeBSD.
Requirements
Section titled “Requirements”- A Linux host with systemd and a public IPv4 or IPv6 address.
- A DNS name for the relay, such as
chat.example.com. - Public TCP port 443 reaching this host directly. A plain port forward is fine. TLS must terminate at the relay: a reverse proxy or CDN that terminates TLS in front of it breaks certificate issuance and every client connection.
1. Point DNS at the host
Section titled “1. Point DNS at the host”Create an A record, and an AAAA record if the host has IPv6:
chat.example.com. 300 IN A 203.0.113.10chat.example.com. 300 IN AAAA 2001:db8::10Check that it resolves before you continue:
dig +short chat.example.com2. Install the binary
Section titled “2. Install the binary”curl -fsSLO https://raw.githubusercontent.com/PDG-Global/rchat-core/v2.1.1/scripts/install.shsudo sh install.shThe script downloads the release binary for this host, verifies it against the release’s signed manifest, and installs it to /usr/local/bin/rchat-server. It also creates the rchat user, /var/lib/rchat (mode 0700) and /etc/rchat, and installs the systemd unit. It never overwrites an existing config, key or unit. Install covers its options, verifying a download by hand, and building from source.
3. Write the configuration
Section titled “3. Write the configuration”Generate a random WebSocket path. Only upgrades to this exact path reach the relay, and every other request gets a decoy website:
echo "/$(openssl rand -base64 24 | tr '+/' '-_')"Create /etc/rchat/server.toml:
[server]bind_addr = "0.0.0.0:443"websocket_path = "/paste-the-random-path-here"relay_identity_path = "/var/lib/rchat/relay_identity.key"
[server.acme]enabled = truedomains = ["chat.example.com"]cache_dir = "/var/lib/rchat/acme"staging = truesudo install -m 0640 -g rchat server.toml /etc/rchat/server.tomlSetting websocket_path is required. The repository’s template ships /CHANGE-ME-to-a-long-random-path, and the server refuses to start while the path contains CHANGE-ME. Every key must be spelled correctly: an unknown key stops the server.
staging = true gets an untrusted test certificate first, so a DNS or firewall mistake does not use up Let’s Encrypt’s production limits. You turn it off in step 7.
Messages for offline recipients are held for at most 72 hours. By default they stay in memory and nothing is written to disk. To change that, see Offline queue.
4. Create the relay identity
Section titled “4. Create the relay identity”The relay has a long-term identity key, separate from its TLS certificate. The app pins it on first connection. Create it once, as the service user, before the first start:
sudo -u rchat /usr/local/bin/rchat-server --config /etc/rchat/server.toml --init-relay-identityThis writes /var/lib/rchat/relay_identity.key and prints the relay’s pin (rk:1:…). A relay started from a config file refuses to start without the key, and --init-relay-identity never overwrites one. Back the key up like a TLS key. See Relay identity for publishing the pin and rotating the key.
5. Start the service
Section titled “5. Start the service”install.sh installed the systemd unit as /etc/systemd/system/rchat-server.service. It runs as the unprivileged rchat user, binds port 443 through CAP_NET_BIND_SERVICE and keeps /var/lib/rchat at mode 0700 (see Running as a service). Start it:
sudo systemctl daemon-reloadsudo systemctl enable --now rchat-serverOpen port 443/tcp in your firewall if it is not open already.
6. Watch the first issuance
Section titled “6. Watch the first issuance”journalctl -u rchat-server -fYou should see, in this order:
WARN ACME: no certificate cached yet. TLS handshakes will FAIL until Let's Encrypt issues one ...INFO WebSocket server listening on 0.0.0.0:443 (TLS 1.3)INFO ACME: certificate issued and deployed; TLS is readyUntil the last line appears, TLS handshakes fail. There is no temporary certificate. If issuance fails, the relay keeps running and retries; see TLS and certificates.
7. Switch to production
Section titled “7. Switch to production”When the staging certificate is issued, set staging = false in /etc/rchat/server.toml and restart:
sudo systemctl restart rchat-serverCheck the result:
openssl s_client -connect chat.example.com:443 -servername chat.example.com </dev/null 2>/dev/null \ | openssl x509 -noout -issuer -datesThe issuer should no longer contain STAGING. Renewal is automatic and needs no restart.
8. Connect the app
Section titled “8. Connect the app”Print the relay’s invite (set host under [server.decoy] first if you don’t use ACME) and scan it in the rChat app with Scan relay invite; see Inviting people to your relay below:
sudo -u rchat /usr/local/bin/rchat-server --config /etc/rchat/server.toml --print-inviteConnect once to check the deployment. If the app says “This server couldn’t prove its identity”, something in front of the relay is terminating TLS.
Without an invite, people can still choose Enter manually and type the server URL, your host plus the WebSocket path (wss://chat.example.com/paste-the-random-path-here). Give them the relay’s pin as well (--print-relay-pin), so they can enter it in Connection settings instead of trusting the first connection.
Inviting people to your relay
Section titled “Inviting people to your relay”An invite is one link, shown as a QR code, that sets up rChat for your relay: it carries the relay’s address (with the secret WebSocket path) and its identity pin. Print it as the service user:
sudo -u rchat /usr/local/bin/rchat-server --config /etc/rchat/server.toml --print-invite# FreeBSD:su -m rchat -c '/usr/local/bin/rchat-server --config /usr/local/etc/rchat/server.toml --print-invite'It prints the link (rchat://relay?u=…&pin=…) and draws the QR code in the terminal. The host name comes from host under [server.decoy], else the first [server.acme] domain; with neither, the command stops and asks you to set host. The port is left out when clients dial 443. Set public_port under [server] (or pass --public-port) when clients dial a different port from the one the relay binds, as behind NAT, a pf rdr rule or a jail; without it, the relay assumes 443 behind a PROXY-protocol front end and its own bind port otherwise.
In the app, people tap Scan relay invite (or Paste invite with the link) on the Connect screen, or under Settings, Connection. The app shows the relay’s host name and asks before it saves anything. It then pins the relay’s identity at once, so a relay that answers with a different identity is refused, even on the first connection. Anyone already connected can share the invite again from Settings, Connection, Invite someone to this relay.
Anyone with this invite can reach your relay. They can’t read messages. Share it with the people you want on your relay, and keep it out of public pages and logs: the relay never logs it, install.sh only prints the command, and provision.sh prints the invite only when it runs in a terminal (otherwise it prints the command).
Next steps
Section titled “Next steps”- Inviting people to your relay: one link or QR code with the address and pin.
- Relay identity: publishing the pin, backups and rotation.
- TLS and certificates: how ACME works, static certificates and troubleshooting.
- Configuration guide and the full reference.
- Resource limits and metrics
- What the relay logs and stores
- Security model