Skip to main content
tavrn Docs

Install with Docker Compose

The compose setup runs the node next to PostgreSQL; these steps take a fresh host to a running node whose first account is the node admin.

  1. Put deploy/docker-compose.yml and deploy/.env.example into a directory on the host, and copy .env.example to .env there.

  2. In .env, set at least TAVRN_DOMAIN and POSTGRES_PASSWORD (long and random), and decide on TAVRN_REGISTRATION (invite by default). If the node is served on another host than its identity domain, set TAVRN_PUBLIC_URL as well (delegation).

  3. Start it:

    Terminal window
    docker compose up -d
    docker compose logs -f tavrn      # the node validates its configuration and names every problem

  4. Point the reverse proxy at 127.0.0.1:8080 with WebSocket support (Reverse proxy and TLS; examples in deploy/nginx.conf.example and deploy/Caddyfile.example).

  5. Open the firewall for voice: the UDP range TAVRN_RTC_UDP_PORT_RANGE (default 61000-61100) and TAVRN_RTC_TCP_PORT (default 7881), published 1:1 and forwarded by the router.

  6. Open https://<your domain> and register: the first account becomes node admin (as does every account named in TAVRN_ADMIN_USERS).

  7. Check the configuration: docker compose exec tavrn tavrn-node check-config prints the effective configuration and checks the LiveKit binary and, with SSO, the provider. Then verify the proxy and run the connection test in the web client (Settings → Voice & video → Test connection).

  8. Set up backups (Keys and backups) before the node gets users.

What the compose file does:

  • tavrn: the image ghcr.io/just-tavrn/tavrn-node:${IMAGE_TAG:-latest} (pin a release line with IMAGE_TAG, see Upgrade and rollback), HTTP published on 127.0.0.1:${TAVRN_HOST_PORT:-8080} only (for a proxy on the same host; if the proxy runs as a container on the same Docker network, drop that line and use tavrn:8080 as the target), the UDP media range and the ICE/TCP port published 1:1, the TURN lines commented out. It reads .env, builds TAVRN_DATABASE_URL from POSTGRES_PASSWORD unless you set it, mounts ./data at /data, and runs with a read-only root file system and a tmpfs on /tmp. The image runs as the unprivileged user tavrn (uid 10001) under tini.
  • db: postgres:17-alpine with its data in ./pgdata and a health check; the node starts once it is healthy. For an external database remove this service and set TAVRN_DATABASE_URL in .env.
  • valkey (commented out): only for several instances (Scaling with Valkey).
  • networks (commented out): an IPv6 subnet for the default network, for voice over IPv6 (Voice and video).
  • TAVRN_REFERENCE_NODES=tavrn.org in .env.example lists the node in the official directory and pulls its node list; leave it empty to be in no directory (Getting listed in the directory).

Many published UDP ports make Docker’s userland proxy slow; with large ranges consider network_mode: host.

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.