Requirements
Everything an operator needs to run a tavrn node, in the order you need it: from the requirements and the installation through configuration, the reverse proxy, keys and backups, voice, federation, scaling and monitoring to upgrades and a hardening checklist. Read it top to bottom once; later, jump to a section.
The commands below run in the directory that holds your docker-compose.yml and .env, with the container
named tavrn as in deploy/docker-compose.yml. Protocol references
(FEDERATION.md, VOICE.md, …) point to the tavrn-protocol
repository, which is the protocol/ submodule of this repository.
A node needs a Linux host with Docker, a domain, a reverse proxy with TLS, PostgreSQL and a data volume; voice needs a few open ports, and SMTP and Valkey are optional.
| What | Details |
|---|---|
| A Linux host with Docker | Docker Engine with the Compose plugin, on x86-64 (amd64) or 64-bit ARM (arm64, for example Ampere or Graviton servers): the image is published for both and docker pull picks the right one. The node is one Rust process; the image adds livekit-server (voice and video) and a minimal static ffmpeg (media conversion). Hardware needs are modest; voice traffic is the part that grows with use. |
| A domain | TAVRN_DOMAIN is the identity of the node and part of every address (alice@chat.example.org). Addresses cannot be renamed later, so choose it with care. The node may run on another host than its identity domain (delegation). |
| A reverse proxy with TLS | Any proxy that terminates TLS and passes WebSockets: examples for Caddy, nginx, Nginx Proxy Manager, Traefik, Apache and HAProxy ship with the repository. The node speaks plain HTTP only and never terminates TLS; nodes federate over HTTPS only. See Reverse proxy and TLS. |
| PostgreSQL | The compose file runs postgres:17-alpine next to the node; any existing PostgreSQL server or managed service works too (TAVRN_DATABASE_URL). SQLite exists only for development (--dev). See Database. |
| A data volume | ./data, mounted at /data: the node’s keys and the uploaded files. Back it up together with the database (Keys and backups). |
| Ports for voice | A UDP range (default 61000-61100) and one TCP port (default 7881) reachable from the internet, published 1:1 to the container and forwarded by the router. Optional: UDP 3478 for TURN, and TURN over TLS on 443 through the proxy. Voice can be switched off (TAVRN_VOICE_ENABLED=false). See Voice and video. |
| Outbound HTTPS | Federation with other nodes, the reference nodes of the directory, link previews, web push to the browser vendors’ push services, the SSO provider and the captcha or GIF provider when configured. |
| Optional: SMTP | E-mail confirmation, password resets and legal notices (TAVRN_SMTP_URL). Without it the node works without e-mail: “Forgot password” answers 503 mail.unavailable (a node admin resets the second factor or the account instead), and mails are not sent (the log notes the recipient and subject, never the body; only development nodes log whole mails). |
| Optional: Valkey or Redis ≥ 7 | Only to run one node as several instances behind a load balancer (Scaling with Valkey). |
This page is generated from tavrn-node/docs/HANDBOOK.md (AGPL-3.0-only) when the website is built; its links were adapted for this site.