Deployment Guide

Welcome to the Spokes Deployment Guide. Spokes is designed to be hosted on your own infrastructure.

Step 1: Planning Your Deployment

Before you spin up the container, you need to decide on your network ports, storage paths, and environment variables.

Network Ports

1. Server Public URL: Decide on the domain name your users will connect to (e.g., https://spokes.yourdomain.com). This is mostly important if your are planning to use the built-in identity provider, as the public URL will be embedded in the OIDC configuration.
2. Web UI Port: Decide which port on your host will map to the container’s internal 8080 port. This can be any port (e.g., 80, 8080, 37625).
3. LiveKit TCP Fallback Port: Decide which port to use for TCP voice traffic. This must map 1-to-1-to-1 between your router, your host and the container (default 7881).
4. LiveKit UDP Range: Decide which UDP ports to use for WebRTC voice and video. This must map 1-to-1-to-1 between your router, your host and the container (default 50000-50499).

Why 1-to-1-to-1 mapping?

Spokes embeds the LiveKit engine for real-time communication. LiveKit explicitly advertises its internal bound port to external clients during the WebRTC handshake. Because of this, the port mapping must be identical across your entire network path: Router Port = Host Port = Container Port.

For example, for the TCP fallback port: 7881 on your Router’s WAN IP must be forwarded to 7881 on your Host IP, which must be mapped to 7881 on your Container.

If your router translates ports (e.g., forwarding WAN port 40000 to internal host port 50000), the voice and video connection will instantly fail.

Paths & Storage

1. Data Directory: You must map a persistent host directory to the container’s /app/Data path. All databases, files, and settings are stored here. If you don’t map this, your data will be lost when the container stops.

Environment Variables

1. SPOKES_MASTER_PASSWORD (Required): This is the global master password for the server. It is used to manage encryption for public channels. By storing the password in a variable, it is never saved in the database and encrypted channels stay secure in case of databae leak. Do not lose this password, and generate it securely (e.g., a long random string).

Step 2: Choosing Your Platform

With your ports planned, the next step is to pull the Docker image and start the container.

Choose the guide for your preferred platform:

• Docker Compose
• Unraid
• Portainer
• CasaOS
• TrueNAS SCALE

Step 3: The Setup Wizard

Once your container is running, navigate to its local Web UI using your browser (e.g., http://your-server-ip:8080). You will be redirected to the Setup Wizard.

1. EULA Agreement: Review and accept the End User License Agreement.
2. Server Profile: Upload your server logo, icon, and set your server name. (Optional)
3. Licensing: Upload your .spokes-license file, or skip to run a demo server.
4. Network Settings:
   • Enter the Server Public URL you decided on in Step 1.
   • Confirm your LiveKit voice ports match the ones you configured in Step 2.
5. Identity Configuration: Choose between Built-in Identity (Casdoor) or an External OIDC Provider.
6. Administrator Accounts: If using the Built-in Identity, set up the Global Admin and the Spokes Organization Admin accounts.

Caution

If you select the Built-in Identity, the setup wizard will display your final administrator credentials at the end of the process. These will not be displayed again. Make sure you copy and save them securely before clicking Restart Server Now.

Step 4: Reverse Proxies (Web UI)

Now that your server is configured and running, you need to expose the Web UI securely to the internet using SSL and your Public URL.

Choose the guide for your preferred reverse proxy:

• Cloudflare Tunnels
• Nginx Proxy Manager

Step 5: Firewalls & Routers (Voice Traffic)

Standard reverse proxies (like Cloudflare or NPM) cannot route LiveKit’s UDP WebRTC traffic. You must manually forward the UDP and TCP fallback ports you planned in Step 1 directly through your router to your server’s IP.

Choose the guide for your router:

• pfSense
• UniFi

After completing Step 5, your Spokes server is fully operational!