Skip to content

Installation

A guide to installing Relay on your own server with Docker Compose and completing first-time setup.

Overview

Relay ships as a Docker Compose stack — an app container (the Node.js server plus a version-pinned Chrome per number) and an nginx container that terminates HTTPS. You run it on a Linux server you control. This guide takes you from a bare server to a signed-in Super-admin ready to create the first workspace.

Note: This is the detailed walk-through. The repository README has the same steps in condensed form.

Before you start

You'll need:

  • A Linux server (Ubuntu 22.04 / Debian 12) on local, block-attached disk — not an NFS/network file share, which doesn't reliably support the file locking the database needs. Size it at 4 GB RAM base + 1.5 GB per WhatsApp number (minimum 8 GB), 2 CPU cores base + 1 additional core per ~3–4 numbers (minimum 4 cores for 5+ numbers), and ~50 GB disk. This is a padded estimate — validate it against your own real usage (docker stats, free -h) once numbers are connected and adjust as needed.
  • Docker 24+ with Compose v2.
  • A domain name pointing at the server, and ports 80 and 443 open.
  • A TLS certificate for that domain (a free Let's Encrypt certificate is fine).

Steps

  1. Get the code and enter the folder. bash git clone <your-relay-repo-url> relay cd relay

  2. Create your environment file. Copy the example and set a strong session secret. bash cp .env.example .env Edit .env and set SESSION_SECRET to a long random value: bash openssl rand -hex 32

  3. Add your TLS certificate. Place the certificate and key in ./ssl/: ssl/ fullchain.pem privkey.pem To get a free certificate with Certbot: bash certbot certonly --standalone -d your-domain.com cp /etc/letsencrypt/live/your-domain.com/fullchain.pem ssl/ cp /etc/letsencrypt/live/your-domain.com/privkey.pem ssl/

  4. Start the stack. bash docker compose up -d The first build downloads the pinned browser, so it takes a few minutes. Check both services are up with docker compose ps.

  5. Complete first-time setup. Open https://your-domain.com/admin in a browser. On a fresh install you're taken to first-time setup — create the Super-admin username and password, then scan the TOTP QR code with an authenticator app (Google Authenticator, Authy, 1Password, …). First-time setup: create the administrator account The TOTP QR code shown during first-time setup

Note: Keep the authenticator safe — you'll need a fresh 6-digit code every time you sign in to the Admin panel. If you lose it, see Troubleshooting → Locked out of the admin panel.

  1. Confirm it's healthy. bash curl -sf https://your-domain.com/healthz # → relay-ok

Next steps

You're signed in as the Super-admin. Next, create a workspace and its Admin account. For backups and updates, see Operations.