Docker Compose (Manual)

Deploying via Docker Compose is the standard and most flexible way to host Spokes on any Linux machine.

Prerequisites

• A Linux host with Docker and Docker Compose installed.
• A static IP assigned to your host machine on your local network (LAN).
• You have decided which ports you want to use for the Web UI and LiveKit.

Configure Docker for Low-RAM Hosts (Optional)

By default, Docker launches a docker-proxy process for every single port mapped in your docker-compose.yml. Because Spokes requires 500 UDP ports for LiveKit, Docker will spawn 500 proxy processes, which can consume over 1GB of RAM and crash small servers.

If your server has less than 2GB of RAM, you should disable this feature and force Docker to use iptables routing instead (which uses virtually zero RAM).

Create or edit /etc/docker/daemon.json and add:

{
  "userland-proxy": false,
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "50m",
    "max-file": "3"
  }
}

This configuration also sets up automatic log rotation so that Docker logs don’t silently consume your entire hard drive over time!

Then restart Docker: sudo systemctl restart docker.

docker-compose.yml

Recommended Deployment Method

Before proceeding, we strongly recommend using our All-in-One Docker Compose guide instead. It includes an automatic Caddy reverse proxy for SSL and a Watchtower container that allows you to update your server with a single click in the UI.

Only proceed with this manual guide if you intend to configure your own custom reverse proxy (like Nginx, Traefik, or Cloudflare Tunnels).

Create a docker-compose.yml file in an empty directory on your server and paste the following configuration. Replace the mapped ports with your custom ports if they differ from the defaults:

version: '3.8'

services:
  spokes:
    image: ghcr.io/pcbeeqc/spokes:latest
    container_name: spokes_server
    restart: unless-stopped
    ports:
      # Web UI and API (Can be mapped to any host port, e.g., "80:8080")
      - "8080:8080"

      # LiveKit TCP Fallback (Must be mapped 1-to-1)
      - "7881:7881"

      # LiveKit UDP Range (Must be mapped 1-to-1)
      - "30000-30499:30000-30499/udp"
    volumes:
      # Persistent data storage (databases, configuration, uploads)
      - ./spokes-data:/data
    environment:
      # Required: The master password used to encrypt secure channels escrow
      - SPOKES_MASTER_PASSWORD=YourSecureMasterPasswordHere

Important

The LiveKit UDP range and the TCP fallback port mapped in your docker-compose.yml must map 1-to-1 between the host and the container. The Web UI port (8080) can be mapped to any port you want.

Start the Server

Run the following command to pull the latest image and start the container in the background:

docker compose up -d

Once the container is running, navigate to the web interface (e.g., http://your-server-ip:8080) to complete the Setup Wizard!

---

Next Steps

Now that your Spokes container is running, it’s time to secure it and configure your network:

• Reverse Proxy Setup: Expose Spokes securely via HTTPS using Cloudflare Tunnels or Nginx Proxy Manager.
• Network Routing: Configure port forwarding for LiveKit voice and video.
• The Setup Wizard: Complete the initial configuration and set up your identity provider.