Skip to content

Deployment Prerequisites

What you need before deploying QS-Bridge.

Infrastructure Requirements

QS-Bridge runs on a VPS (Virtual Private Server) that you control. This is a deliberate architectural decision — not a limitation. VPS-only deployment unlocks first-class process management: mods become systemd services with auto-restart, health monitoring, resource limits, port allocation, and log aggregation.

Not supported: Docker, shared hosting, or serverless environments. The platform needs direct access to the filesystem, systemd, and process management.

Minimum Hardware

Resource Minimum Recommended
CPU 2 cores 4+ cores
RAM 4 GB 8+ GB
Disk 20 GB SSD 50+ GB SSD
Network 100 Mbps 1 Gbps
OS Ubuntu 22.04+ / Debian 12+ Ubuntu 24.04 LTS

RAM scales with the number of game servers and installed mods. Each ProcessService mod consumes additional memory.

Software Dependencies

Required

Software Version Purpose
SpacetimeDB v1.1+ Database engine (tables, reducers, subscriptions)
Rust 1.75+ Build STDB WASM modules
Node.js 22 LTS API gateway, panel build, wiki tooling
Git 2.x Version control, deployment

Optional (depending on features)

Software Version Purpose
Nginx 1.27+ Reverse proxy, TLS termination
Wiki.js 2.x Documentation wiki (wiki.qs-zuq.com)
PostgreSQL 15+ Wiki.js database
MinIO Latest Mod registry file storage (S3-compatible)
GCC / Clang 11+ / 14+ Build libqsbridge.so (C++17)
CMake 3.20+ Bridge build system

Install Commands (Ubuntu 24.04)

# System packages
sudo apt update && sudo apt install -y \
  build-essential cmake git curl wget \
  nginx certbot python3-certbot-nginx

# Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup target add wasm32-unknown-unknown

# Node.js 22 LTS
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# SpacetimeDB
curl -sSf https://install.spacetimedb.com | sh

Network Requirements

Ports

Port Service Protocol Access
3000 SpacetimeDB WebSocket + HTTP Internal (or panel clients)
3081 API Gateway HTTPS Panel clients
443 Nginx (TLS) HTTPS Public
80 Nginx (redirect) HTTP Public (→ 443)
3001 Wiki.js (via nginx) HTTPS Public
8900-9899 ProcessService mods TCP Internal

DNS Records

Record Type Value
panel.qs-zuq.com A VPS IP
wiki.qs-zuq.com A VPS IP
api.qs-zuq.com A VPS IP (optional, if gateway is separate)

Hosting Provider Integration

BisectHosting (Primary Target)

QS-Bridge integrates with BisectHosting's Starbase API for server lifecycle management. You need:

Requirement How to Get
BisectHosting account bisecthosting.com
API key BisectHosting control panel → API section
Server UUID(s) Listed in your BisectHosting dashboard

The API key maps to one account that owns all servers. ServerRegistry.hosting_id links each QS-Bridge server row to its BisectHosting server UUID.

Security: The API key is stored server-side in the gateway's .env file. The React panel never touches hosting secrets — all lifecycle actions go through the API gateway.

Environment Variables

Create a .env file for each service. See Configuration Reference for the complete list.

Essential variables:

# SpacetimeDB
STDB_HOST=ws://localhost:3000
STDB_MODULE=qs-bridge

# API Gateway
GATEWAY_PORT=3081
GATEWAY_URL=https://panel.qs-zuq.com
JWT_SECRET=<generate-a-64-char-random-string>
STDB_HOST=ws://localhost:3000
STDB_TOKEN=<spacetimedb-auth-token>

# BisectHosting (optional)
BISECT_API_KEY=<your-api-key>

# Bridge (.so)
QSB_SERVER_ID=server-01
QSB_STDB_HOST=ws://localhost:3000
QSB_STDB_MODULE=qs-bridge
QSB_HMAC_SECRET=<generate-a-64-char-random-string>