Skip to content

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.

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

Create an A record, and an AAAA record if the host has IPv6:

chat.example.com. 300 IN A 203.0.113.10
chat.example.com. 300 IN AAAA 2001:db8::10

Check that it resolves before you continue:

Terminal window
dig +short chat.example.com
Terminal window
curl -fsSLO https://raw.githubusercontent.com/PDG-Global/rchat-core/v2.1.1/scripts/install.sh
sudo sh install.sh

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

Generate a random WebSocket path. Only upgrades to this exact path reach the relay, and every other request gets a decoy website:

Terminal window
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 = true
domains = ["chat.example.com"]
contacts = ["mailto:[email protected]"]
cache_dir = "/var/lib/rchat/acme"
staging = true
Terminal window
sudo install -m 0640 -g rchat server.toml /etc/rchat/server.toml

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

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:

Terminal window
sudo -u rchat /usr/local/bin/rchat-server --config /etc/rchat/server.toml --init-relay-identity

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

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:

Terminal window
sudo systemctl daemon-reload
sudo systemctl enable --now rchat-server

Open port 443/tcp in your firewall if it is not open already.

Terminal window
journalctl -u rchat-server -f

You 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 ready

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

When the staging certificate is issued, set staging = false in /etc/rchat/server.toml and restart:

Terminal window
sudo systemctl restart rchat-server

Check the result:

Terminal window
openssl s_client -connect chat.example.com:443 -servername chat.example.com </dev/null 2>/dev/null \
| openssl x509 -noout -issuer -dates

The issuer should no longer contain STAGING. Renewal is automatic and needs no restart.

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:

Terminal window
sudo -u rchat /usr/local/bin/rchat-server --config /etc/rchat/server.toml --print-invite

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

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:

Terminal window
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).