Skip to main content
Get started with local development of Spectra Server. This guide covers environment setup, dependency installation, SSL certificate generation, and running the development server.

​
Prerequisites

Before starting, ensure you have the required tools installed:

Node.js

Version: 22.x or higherDownload Node.js

Yarn

Package Manager: Yarn (Yarn Berry)Install Yarn
Spectra Server uses Yarn Berry (v4.7.0) via Corepack. The packageManager field in package.json ensures the correct version is used.

​
Setup Steps

1

Clone the Repository

Clone the Spectra Server repository from GitHub:
git clone https://github.com/ValoSpectra/Spectra-Server.git
Navigate to the project directory:
cd Spectra-Server
2

Install Dependencies

Install all required Node.js packages using Yarn:
yarn install
This will install:
  • Production dependencies (Express, Socket.IO, etc.)
  • Development dependencies (TypeScript, ESLint, tsx, etc.)
  • Optional dependencies for WebSocket performance optimization
3

Generate SSL Certificates (Optional)

For local HTTPS/WSS testing, generate self-signed certificates:
openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 \
  -nodes -keyout keys/server.key -out keys/server.crt -subj "/CN=spectra"
This creates:
  • keys/server.key - Private key (4096-bit RSA)
  • keys/server.crt - Self-signed certificate (valid for 10 years)
Self-signed certificates will trigger browser warnings. For development, you can use INSECURE=true mode instead.
4

Configure Environment Variables

Create a .env file from the example template:
cp .env.example .env
Edit the .env file to match your setup:
SERVER_KEY=keys/server.key
SERVER_CERT=keys/server.crt
INSECURE=false

REQUIRE_AUTH_KEY=true
AUTH_KEY=your-dev-auth-key
If you haven’t generated SSL certificates, set INSECURE=true to run the server without TLS.
5

Start the Development Server

Run the server in development mode with hot-reload:
yarn start
The server will start with:
  • Port 5100 - Incoming WebSocket server (client connections)
  • Port 5101 - REST API server (status, previews, etc.)
  • Port 5200 - Outgoing WebSocket server (overlay/observer connections)
You should see output similar to:
Extras available on port 5101
WebSocket server listening on port 5100
Outgoing WebSocket server listening on port 5200

​
Available Scripts

Spectra Server provides several npm scripts for development and testing:

​
Development Scripts

​
yarn start
command
Start development server - Runs yarn dev with hot-reload using tsx watch mode
​
yarn dev
command
Development mode - Uses tsx watch ./src/index.ts for automatic restart on file changes
​
yarn start_single
command
Single run mode - Starts the server once using tsx ./src/index.ts (no watch mode)

​
Build Scripts

​
yarn build
command
Compile TypeScript - Transpiles TypeScript to JavaScript using tsc

​
Code Quality Scripts

# Check for linting errors
yarn lint

# Auto-fix linting errors
yarn lint-fix
​
yarn lint
command
Run ESLint - Checks code for style and potential errors
​
yarn lint-fix
command
Fix ESLint issues - Automatically fixes auto-fixable linting problems
​
yarn format
command
Format with Prettier - Formats all source files according to Prettier rules

​
Replay Scripts

For testing with recorded match data:
​
yarn replay
command
Replay match data - Runs the replay utility for testing
​
yarn replay_instant
command
Instant replay - Replays match data as fast as possible (no delays)
​
yarn replay_delay
command
Delayed replay - Replays match data with artificial delays
​
yarn replay_timestamps
command
Timestamp replay - Replays using original timestamps from recorded data
​
yarn replay_manual
command
Manual replay - Step through replay events manually
​
yarn replay_file
command
Custom file replay - Replay a specific game file: yarn replay_file -- -game customGameTest.replay

​
Development Workflow

​
Hot Reload Development

The yarn dev command uses tsx watch to monitor file changes: 
yarn dev
Any changes to TypeScript files in the src/ directory will automatically restart the server.

​
Testing API Endpoints

Once the server is running, test the REST API: 
curl http://localhost:5101/status
Expected response: 
{
  "status": "UP",
  "matchesRunning": 0
}

​
Connecting with WebSocket Clients

Test WebSocket connectivity: 
// Client connection
const io = require('socket.io-client');
const socket = io('http://localhost:5100');

socket.on('connect', () => {
  console.log('Connected to incoming WebSocket');
});

​
Project Structure

Key directories and files: 
Spectra-Server/
├── src/
│   ├── index.ts                 # Main entry point
│   ├── connector/
│   │   ├── websocketIncoming.ts # Client WebSocket server (5100)
│   │   ├── websocketOutgoing.ts # Observer WebSocket server (5200)
│   │   └── databaseConnector.ts # Backend integration
│   ├── controller/
│   │   └── MatchController.ts   # Match lifecycle management
│   ├── model/
│   │   ├── Match.ts             # Match data model
│   │   └── eventData.ts         # Event type definitions
│   └── util/
│       ├── Logging.ts           # Logging utility
│       └── previews/            # Preview generation
├── keys/                        # SSL certificates (gitignored)
├── .env                         # Environment config (gitignored)
├── .env.example                 # Environment template
├── package.json                 # Dependencies and scripts
├── tsconfig.json                # TypeScript configuration
└── Dockerfile                   # Container configuration

​
Troubleshooting

If ports 5100, 5101, or 5200 are already in use:
# Check what's using the port
lsof -i :5100
lsof -i :5101
lsof -i :5200

# Kill the process
kill -9 <PID>
If you encounter SSL/TLS errors:
  1. Verify certificate files exist: 
    ls -la keys/
  2. Set INSECURE=true in .env for development
  3. Regenerate certificates if corrupted: 
    rm keys/server.key keys/server.crt
openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 \
  -nodes -keyout keys/server.key -out keys/server.crt -subj "/CN=spectra"
If you see module import errors:
# Clear node_modules and reinstall
rm -rf node_modules
yarn install

# Clear Yarn cache if needed
yarn cache clean
Ensure you’re using the correct TypeScript version:
# Check TypeScript version
yarn tsc --version

# Should be 5.8.x or higher

# Run type checking
yarn build

​
Next Steps

Configuration

Learn about all environment variables and configuration options

Docker Deployment

Deploy with Docker for production environments

Build docs developers (and LLMs) love

Get started for freeTalk to us