Skip to main content
Spectra Server is configured primarily through environment variables defined in a .env file. This reference covers all available configuration options, organized by category.

​
Environment File Setup

Create a .env file in the project root: 
cp .env.example .env
Edit the file to match your deployment requirements. The server uses the dotenv package to load these variables at startup.

​
SSL/TLS Configuration

Configure secure connections using SSL/TLS certificates.
​
SERVER_KEY
string
default:"keys/server.key"
Path to SSL private key fileThe private key used for HTTPS and secure WebSocket (WSS) connections. This file should have restrictive permissions (600) to prevent unauthorized access.
.env
SERVER_KEY=keys/server.key
For Docker deployments, use /app/keys/server.key as the path.
​
SERVER_CERT
string
default:"keys/server.crt"
Path to SSL certificate fileThe SSL/TLS certificate corresponding to the private key. Can be a self-signed certificate for development or a CA-signed certificate for production.
.env
SERVER_CERT=keys/server.crt
Generate a self-signed certificate:
openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 \
  -nodes -keyout keys/server.key -out keys/server.crt -subj "/CN=spectra"
​
INSECURE
boolean
default:"true"
Enable insecure (HTTP/WS) modeWhen set to true, the server runs without SSL/TLS encryption using HTTP and plain WebSocket connections. When false, requires valid SERVER_KEY and SERVER_CERT.
.env
INSECURE=true  # For development
INSECURE=false # For production
Never use INSECURE=true in production. Always use proper SSL/TLS certificates for production deployments to protect data in transit.
Affected services:
  • REST API server (port 5101)
  • Incoming WebSocket server (port 5100)
  • Outgoing WebSocket server (port 5200)

​
Authentication Configuration

Control client authentication and access control.
​
REQUIRE_AUTH_KEY
boolean
default:"true"
Require authentication key for client connectionsWhen enabled, all client connections must provide a valid authentication key. Set to false to allow connections without authentication (not recommended).
.env
REQUIRE_AUTH_KEY=true
Authentication is validated during the obs_logon event when clients connect to the incoming WebSocket server (port 5100).
​
AUTH_KEY
string
default:"DEBUG_REMOVE_ME"
Static authentication keyThe authentication key that clients must provide to connect. Used when USE_BACKEND=false or as a fallback when backend authentication is unavailable.
.env
AUTH_KEY=your-secure-random-key-here
Change the default value DEBUG_REMOVE_ME before deployment. Use a strong, randomly generated key.
Generate a secure random key:
openssl rand -hex 32

​
Backend Integration

Configure integration with external backend services for advanced features.
​
USE_BACKEND
boolean
default:"false"
Enable backend service integrationWhen enabled, the server connects to a backend API for:
  • Advanced authentication and authorization
  • Multi-organization support
  • Supporter status verification
  • Match data persistence
.env
USE_BACKEND=true
Requires additional backend-related variables when enabled.
​
BACKEND_URL
string
Backend API base URLThe base URL of the backend service API. Used for organization verification, key validation, and data persistence.
.env
BACKEND_URL=https://api.example.com
Referenced in src/connector/databaseConnector.ts:114 for API requests.
​
BACKEND_TOKEN
string
Backend API authentication tokenThe authentication token sent as X-User-Token header for backend API requests.
.env
BACKEND_TOKEN=your-backend-api-token
This token authenticates the Spectra Server to the backend service, not the end clients.
​
SUPPORTER_CHECK_URL
string
Supporter status verification endpointThe URL for checking organization supporter status. Used to enable premium features for supporters.
.env
SUPPORTER_CHECK_URL=https://something.de/endpoint
The server appends /{orgId} to this URL when checking supporter status.
​
STATS_BACKEND_URL
string
Statistics backend API URLThe base URL for the statistics backend service, used for advanced analytics and data aggregation.
.env
STATS_BACKEND_URL=https://stats.example.com
​
STATS_BACKEND_TOKEN
string
Statistics backend authentication tokenThe authentication token sent as Authentication header for statistics backend API requests.
.env
STATS_BACKEND_TOKEN=your-stats-token
​
PLAYERCAM_URL
string
Player camera service URLThe URL for the player camera service integration, if available.
.env
PLAYERCAM_URL=https://playercam.example.com

​
Discord OAuth Integration

Configure Discord OAuth for supporter verification (requires USE_BACKEND=true).
​
DISCORD_CLIENT_ID
string
Discord application client IDThe OAuth2 client ID from your Discord application settings.
.env
DISCORD_CLIENT_ID=123456789012345678
Get this from the Discord Developer Portal.
​
DISCORD_CLIENT_SECRET
string
Discord application client secretThe OAuth2 client secret for token exchange.
.env
DISCORD_CLIENT_SECRET=your-discord-client-secret
Keep this secret secure. Never commit it to version control.
​
DISCORD_REDIRECT_URI
string
Discord OAuth callback URLThe redirect URI configured in your Discord application for OAuth callbacks.
.env
DISCORD_REDIRECT_URI=https://yourdomain.com/client/oauth-callback
This must match exactly with the redirect URI in Discord Developer Portal.
​
DISCORD_OAUTH_URL
string
Discord OAuth token endpointThe Discord API endpoint for exchanging authorization codes for access tokens.
.env
DISCORD_OAUTH_URL=https://discord.com/api/oauth2/token
​
DISCORD_USER_URL
string
Discord user info endpointThe Discord API endpoint for retrieving user information.
.env
DISCORD_USER_URL=https://discord.com/api/users/@me
​
SPECTRA_CLIENT_DEEPLINK
string
Spectra client deep link URLThe deep link URL scheme for redirecting users to the Spectra client after authentication.
.env
SPECTRA_CLIENT_DEEPLINK=spectra://auth
Query parameters userId, username, and avatar are appended automatically.

​
Tebex Integration

Configure Tebex e-commerce integration for supporter packages (requires USE_BACKEND=true).
​
TEBEX_BASE_URL
string
Tebex API base URLThe base URL for Tebex API requests.
.env
TEBEX_BASE_URL=https://plugin.tebex.io
​
TEBEX_STORE_ID
string
Tebex store identifierYour Tebex store ID for package retrieval.
.env
TEBEX_STORE_ID=your-store-id
​
TEBEX_EXTENSION_ID
string
Tebex extension identifierThe extension ID for Tebex integration.
.env
TEBEX_EXTENSION_ID=your-extension-id

​
Configuration Examples

​
Minimal Development Setup

For local development without SSL or backend:
.env
SERVER_KEY=keys/server.key
SERVER_CERT=keys/server.crt
INSECURE=true

REQUIRE_AUTH_KEY=true
AUTH_KEY=dev-auth-key-12345

​
Production with SSL

For production deployment with SSL certificates:
.env
SERVER_KEY=/app/keys/production.key
SERVER_CERT=/app/keys/production.crt
INSECURE=false

REQUIRE_AUTH_KEY=true
AUTH_KEY=<generate-secure-random-key>

​
Full Backend Integration

For production with all backend features enabled:
.env
# SSL Configuration
SERVER_KEY=/app/keys/production.key
SERVER_CERT=/app/keys/production.crt
INSECURE=false

# Authentication
REQUIRE_AUTH_KEY=true
AUTH_KEY=<fallback-auth-key>

# Backend Integration
USE_BACKEND=true
BACKEND_URL=https://api.valospectra.com
BACKEND_TOKEN=<backend-api-token>
SUPPORTER_CHECK_URL=https://api.valospectra.com/supporter
STATS_BACKEND_URL=https://stats.valospectra.com
STATS_BACKEND_TOKEN=<stats-api-token>

# Discord OAuth
DISCORD_CLIENT_ID=123456789012345678
DISCORD_CLIENT_SECRET=<discord-secret>
DISCORD_REDIRECT_URI=https://yourdomain.com/client/oauth-callback
DISCORD_OAUTH_URL=https://discord.com/api/oauth2/token
DISCORD_USER_URL=https://discord.com/api/users/@me
SPECTRA_CLIENT_DEEPLINK=spectra://auth

# Tebex Integration
TEBEX_BASE_URL=https://plugin.tebex.io
TEBEX_STORE_ID=<store-id>
TEBEX_EXTENSION_ID=<extension-id>

​
Security Best Practices

  • Never commit .env files to version control
  • Add .env to .gitignore
  • Use strong, randomly generated keys and tokens
  • Rotate secrets regularly
  • Use different credentials for development and production
  • Use certificates from a trusted Certificate Authority in production
  • Set appropriate file permissions (600) for private keys
  • Regularly renew certificates before expiration
  • Never use INSECURE=true in production environments
  • Generate cryptographically secure random keys
  • Use at least 32 bytes (256 bits) of entropy
  • Never use default values like DEBUG_REMOVE_ME
  • Implement key rotation procedures
  • Store backend tokens securely
  • Use environment-specific tokens
  • Monitor token usage and revoke compromised tokens
  • Implement least-privilege access

​
Validation and Testing

Verify your configuration after setup:
1

Validate Environment File

Ensure all required variables are set:
cat .env | grep -v "^#" | grep -v "^$"
2

Test Server Startup

Start the server and check for configuration errors:
yarn start
Look for:
  • SSL certificate loading messages
  • Port binding confirmations
  • Backend connection status
3

Verify SSL Configuration

If INSECURE=false, test SSL certificate:
openssl s_client -connect localhost:5101
4

Test Authentication

Verify authentication is working:
curl http://localhost:5101/status
Should return server status.

​
Next Steps

Docker Deployment

Deploy with Docker using these configuration options

Local Development

Set up your local development environment

Build docs developers (and LLMs) love

Get started for freeTalk to us