Skip to content

Requirements & Prerequisites

This page lists everything you need to deploy and run QS-Bridge. Requirements are divided into infrastructure, software dependencies, build toolchain, and environment configuration.

Deployment model: QS-Bridge is designed for VPS-only deployment. It is not tested or supported in containerised, serverless, or shared-hosting environments. See Platform Overview for the rationale.

Infrastructure

Hardware Recommendations

QS-Bridge itself is lightweight, but the game server it manages will dominate resource consumption. The following recommendations assume a single VPS running one game server, the SpacetimeDB instance, the API gateway, and the admin panel.

Resource Minimum Recommended Notes
CPU 4 cores 8+ cores Game server is the primary consumer. SpacetimeDB benefits from additional cores for concurrent reducer execution.
RAM 8 GB 16–32 GB Game server memory varies by title. SpacetimeDB uses ~2 GB baseline for the platform + mod registry modules.
Disk 40 GB SSD 100 GB NVMe NVMe strongly recommended. SpacetimeDB WAL performance is directly tied to disk I/O latency.
Network 100 Mbps 1 Gbps Game server network requirements vary. SpacetimeDB WebSocket traffic is negligible by comparison.
OS Ubuntu 22.04 LTS Ubuntu 24.04 LTS Any systemd-based Linux distribution will work. Debian 12+, Fedora 39+, and Rocky Linux 9+ are also tested.

Multi-server deployments: When running N game servers on a single VPS, multiply the game server's CPU and RAM requirements by N. SpacetimeDB and QS-Bridge overhead scales sub-linearly.

Network Ports

Port Service Protocol Exposure
3000 SpacetimeDB HTTP/WebSocket Internal (localhost) or private network
3001 API Gateway HTTPS Public (reverse-proxied)
3002 Admin Panel (dev) HTTP Public (reverse-proxied) or localhost
7777–7800 Game Server(s) UDP Public
27015–27030 Steam Query UDP Public

Production note: In production, the API gateway and admin panel should sit behind a reverse proxy (e.g., Nginx, Caddy) with TLS termination. Never expose SpacetimeDB directly to the public internet.

Software Dependencies

Required

Dependency Version Purpose
Linux Ubuntu 22.04+ (kernel 5.15+) Host operating system. LD_PRELOAD injection requires a Linux environment.
systemd 249+ Process supervision, port allocation, health monitoring, and watchdog integration.
SpacetimeDB v2.x Central data store. Hosts the platform module, mod registry module, and game modules.
Node.js 20 LTS+ Runtime for the API gateway (Hono) and admin panel dev server (Vite).
npm 10+ Package manager for TypeScript dependencies. Ships with Node.js 20+.

Build Toolchain (C++ Bridge)

These are required only if you are building libqsbridge.so from source. Pre-built binaries are available for supported platforms.

Tool Version Purpose
CMake 3.20+ Build system generator.
GCC 12+ C++17 compiler. Clang 15+ is also supported but not the primary CI compiler.
GNU Make or Ninja Any recent Build executor. Ninja is faster for incremental builds.

Build Toolchain (STDB Modules)

These are required only if you are modifying or rebuilding the Rust-based SpacetimeDB modules (platform, mod registry, or game modules).

Tool Version Purpose
Rust 1.75+ (stable) Compiler for SpacetimeDB modules.
cargo Ships with Rust Rust package manager and build tool.
spacetime CLI Matches STDB v2.x CLI for publishing modules to a SpacetimeDB instance.

Optional

Dependency Purpose
Nginx or Caddy Reverse proxy with TLS termination for production deployments.
BisectHosting account Required only for hosting integration features (automated provisioning, billing hooks).
Git Source control. Required if cloning the repository.

Environment Variables

QS-Bridge components are configured via environment variables. These are typically set in systemd unit files or a .env file for development.

Bridge (libqsbridge.so)

Variable Required Default Description
QSB_SERVER_ID Yes — Human-readable server identifier (e.g., "us-east-1-pvp"). Must be unique within the deployment.
QSB_STDB_URI Yes — WebSocket URI for the SpacetimeDB instance (e.g., ws://localhost:3000).
QSB_STDB_MODULE No "qs-bridge" Name of the SpacetimeDB module to connect to.
QSB_SYNC_INTERVAL_MS No 100 Interval in milliseconds between background sync flushes. Lower values reduce latency at the cost of higher STDB write throughput.
QSB_LOG_LEVEL No "info" Logging verbosity. One of: trace, debug, info, warn, error.
QSB_CREDENTIAL_DIR No ~/.qsbridge/ Directory for storing STDB identity credentials.

API Gateway

Variable Required Default Description
QSB_HMAC_SECRET Yes — Secret key for signing JWT session tokens. Must be at least 32 characters.
QSB_STDB_URI Yes — WebSocket URI for SpacetimeDB (same instance as the bridge).
QSB_STEAM_API_KEY Yes — Steam Web API key for OpenID 2.0 assertion validation. Obtain from Steam Partner Portal.
QSB_GATEWAY_PORT No 3001 Port for the API gateway to listen on.
QSB_CORS_ORIGIN No "*" Allowed CORS origins. Set to the admin panel's URL in production (e.g., https://panel.example.com).

Admin Panel

Variable Required Default Description
VITE_API_URL Yes — URL of the API gateway (e.g., https://api.example.com or http://localhost:3001).
VITE_STDB_URI No — Direct SpacetimeDB URI for real-time subscriptions (optional; falls back to API gateway proxying).

SpacetimeDB Setup

Installation

Install the SpacetimeDB CLI and server following the official documentation:

# Install the SpacetimeDB CLI
curl -sSf https://install.spacetimedb.com | bash

# Verify installation
spacetime version

Starting the Server

For development:

spacetime start

For production, create a systemd unit:

# /etc/systemd/system/spacetimedb.service
[Unit]
Description=SpacetimeDB Server
After=network.target

[Service]
Type=simple
User=spacetimedb
ExecStart=/usr/local/bin/spacetime start
Restart=always
RestartSec=5
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

Node.js Setup

Installation (via nvm)

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# Install Node.js 20 LTS
nvm install 20
nvm use 20

# Verify
node --version  # v20.x.x
npm --version   # 10.x.x

Rust Toolchain Setup

Required only for building STDB modules from source.

# Install Rust via rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Verify
rustc --version  # 1.75.0+
cargo --version

C++ Build Toolchain Setup

Required only for building libqsbridge.so from source.

Ubuntu / Debian

sudo apt update
sudo apt install -y build-essential cmake gcc-12 g++-12

# Verify
cmake --version   # 3.20+
gcc-12 --version  # 12.x

Fedora / Rocky Linux

sudo dnf install -y cmake gcc gcc-c++ make

# Verify
cmake --version
gcc --version

Pre-Flight Checklist

Before proceeding to the Quick Start Guide, verify that all required components are available:

# Core dependencies
spacetime version        # SpacetimeDB v2.x
node --version           # v20.x.x+
npm --version            # 10.x.x+

# Build toolchain (if building from source)
cmake --version          # 3.20+
gcc --version            # 12+
rustc --version          # 1.75+
cargo --version

# Optional
nginx -v                 # For production reverse proxy
git --version            # For cloning the repository

All checks pass? Continue to the Quick Start Guide.