Skip to main content

​
Quickstart Guide

Get Spectra Server up and running in less than 5 minutes using Docker Compose. This guide will have you processing game data and streaming to frontends quickly.

​
Prerequisites

Docker

Docker Engine 20.10 or higher

Docker Compose

Docker Compose v2.0 or higher
No Node.js installation required when using Docker! The container includes all dependencies.

​
Quick Setup with Docker Compose

1

Create Project Directory

Create a dedicated directory for Spectra Server and SSL certificates:
mkdir -p spectra-server/keys
cd spectra-server
The keys folder will store SSL certificates (optional for development).
2

Create Docker Compose Configuration

Create a docker-compose.yml file in the spectra-server directory:
docker-compose.yml
---
services:
  valo-spectra-server:
    image: "ghcr.io/valospectra/server"
    ports:
      - "5100:5100"  # Incoming WebSocket (observer clients)
      - "5101:5101"  # REST API
      - "5200:5200"  # Outgoing WebSocket (frontends)
    volumes:
      - ./keys:/app/keys
    environment:
      - INSECURE=true  # Set to false for production with SSL
Port Mapping:
  • 5100: Incoming WebSocket for observer clients
  • 5101: REST API for status, previews, and team info
  • 5200: Outgoing WebSocket for frontends
3

Configure Environment Variables (Optional)

For development, the default INSECURE=true setting is sufficient. For production or custom configurations, create a .env file:
# Development mode (no SSL required)
INSECURE=true
REQUIRE_AUTH_KEY=false
Then update your docker-compose.yml to use the env file:
docker-compose.yml
services:
  valo-spectra-server:
    image: "ghcr.io/valospectra/server"
    ports:
      - "5100:5100"
      - "5101:5101"
      - "5200:5200"
    volumes:
      - ./keys:/app/keys
    env_file:
      - .env
For production deployments, always set INSECURE=false and provide valid SSL certificates in the keys folder. Self-signed certificates will be auto-generated if not provided.
4

Start the Server

Launch Spectra Server with Docker Compose:
docker compose up -d
The -d flag runs the container in detached mode (background).
To view logs in real-time: docker compose logs -f valo-spectra-server
5

Verify Server is Running

Check the server status using the REST API:
curl http://localhost:5101/status
You should receive a response like:
{
  "status": "UP",
  "matchesRunning": 0
}
The matchesRunning field shows the number of active matches currently being tracked by the server.

​
SSL Certificates (Production)

For production deployments with INSECURE=false, place your SSL certificates in the keys folder: 
spectra-server/
├── docker-compose.yml
├── .env
└── keys/
    ├── server.key
    └── server.crt
If you don’t provide SSL certificates, Spectra Server will automatically generate self-signed certificates. However, clients will need to accept the self-signed certificate.

​
Environment Variables Reference

VariableDefaultDescription
INSECUREtrueSet to false to enable HTTPS/WSS with SSL certificates
SERVER_KEYkeys/server.keyPath to SSL private key
SERVER_CERTkeys/server.crtPath to SSL certificate
REQUIRE_AUTH_KEYtrueRequire API key authentication for observer clients
AUTH_KEYDEBUG_REMOVE_MEMaster authentication key for development
USE_BACKENDfalseEnable backend integration for multi-org support
SUPPORTER_CHECK_URL-Backend endpoint for supporter verification
Never commit your .env file or production AUTH_KEY to version control!

​
Next Steps

Connect Observer Client

Set up Spectra Client on an observer machine

Connect Frontend

Configure Spectra Frontend to receive game state

API Reference

Explore REST endpoints and WebSocket events

Configuration

Advanced configuration and authentication setup

​
Testing the Connection

Once the server is running, you can test WebSocket connections: 
// Observer clients connect here
const socket = io('http://localhost:5100');

// Authenticate as observer
socket.emit('obs_logon', JSON.stringify({
  type: 'auth',
  obsName: 'Observer 1',
  groupCode: 'TEST01',
  groupSecret: 'secret123',
  key: 'DEBUG_REMOVE_ME',
  clientVersion: '0.3.2',
  leftTeam: { name: 'Team A', tricode: 'TMA', url: '', attackStart: true },
  rightTeam: { name: 'Team B', tricode: 'TMB', url: '', attackStart: false }
}));

​
Troubleshooting

Check the logs:
docker compose logs valo-spectra-server
Common issues:
  • Port already in use (5100, 5101, or 5200)
  • Invalid SSL certificate paths when INSECURE=false
  • Missing environment variables
Verify:
  • Server is running: docker compose ps
  • Ports are accessible: curl http://localhost:5101/status
  • Firewall rules allow connections on ports 5100, 5101, 5200
  • Client version is compatible with server version
Check:
  • REQUIRE_AUTH_KEY is set to false for testing, or
  • AUTH_KEY matches the key provided by the client
  • Client is sending proper authentication packet format
For development, set REQUIRE_AUTH_KEY=false in your environment to skip authentication and test connectivity quickly.

​
Running from Source (Development)

If you prefer to run from source instead of Docker:
1

Clone and Install

git clone https://github.com/ValoSpectra/Spectra-Server.git
cd Spectra-Server
yarn install
2

Configure Environment

Copy .env.example to .env and configure:
cp .env.example .env
# Edit .env with your settings
3

Start Development Server

yarn dev
This uses tsx watch for automatic reloading on code changes.
Running from source requires Node.js 18+ and Yarn 4.7.0+.

Build docs developers (and LLMs) love

Get started for freeTalk to us