Overview
Hyperscape uses Docker for:
- Asset CDN: nginx serving game assets
- PostgreSQL: Database for player data
- Development services: Local infrastructure
Prerequisites
- Docker Desktop (macOS/Windows)
- Or Docker Engine on Linux:
apt install docker.io
CDN Container
Start CDN
This starts an nginx container serving assets from packages/server/world/assets/ on port 8080.
Stop CDN
Automatic Start
The CDN starts automatically with bun run dev. Only run manually if using services separately.
PostgreSQL Container
PostgreSQL starts automatically when the server runs via Docker Compose.
Configuration
Default connection:
Host: localhost
Port: 5432
Database: hyperscape
User: postgres
Password: postgres
Manual Control
cd packages/server
docker-compose up postgres # Start PostgreSQL
docker-compose down postgres # Stop PostgreSQL
Docker Compose
The server package includes docker-compose.yml:
services:
postgres:
image: postgres:15
ports:
- "5432:5432"
environment:
POSTGRES_DB: hyperscape
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
volumes:
- postgres-data:/var/lib/postgresql/data
cdn:
image: nginx:alpine
ports:
- "8080:80"
volumes:
- ./world/assets:/usr/share/nginx/html:ro
Production Docker Images
Server Image
The server Dockerfile includes all dependencies for production deployment:
FROM node:20-bookworm-slim
# Install system dependencies
RUN apt-get update && apt-get install -y \
build-essential \
git-lfs \
python3 \
python3-pip \
unzip
# Install Bun
RUN curl -fsSL https://bun.sh/install | bash
# Set CI=true to skip asset download
ENV CI=true
# Copy application
COPY . /app
WORKDIR /app
# Install dependencies and build
RUN bun install
RUN bun run build
# Start server
CMD ["bun", "start"]
- bookworm-slim: Debian 12 base for Python 3.11+ support
- build-essential: Required for native module compilation (PhysX, etc.)
- git-lfs: Asset validation and checks
- CI=true: Skips asset download in production (assets served from CDN)
Vast.ai Keeper Image
The vast-keeper package uses a specialized image for GPU instance provisioning:
FROM node:20-bookworm-slim
# Install Python 3.11+ and vastai SDK
RUN apt-get update && apt-get install -y \
python3 \
python3-pip \
build-essential \
git-lfs \
unzip
# Install vastai SDK with --break-system-packages for Debian 12 (PEP 668)
RUN pip3 install --break-system-packages vastai
# Generate SSH keys for secure instance access
RUN ssh-keygen -t rsa -b 4096 -f /root/.ssh/id_rsa -N ""
# Install Bun
RUN curl -fsSL https://bun.sh/install | bash
# Copy application
COPY . /app
WORKDIR /app
# Install dependencies
RUN bun install
# Start keeper service
CMD ["bun", "run", "start"]
- Python 3.11+: Required for vastai-sdk (needs Python 3.10+)
- —break-system-packages: Required for pip3 on Debian 12 due to PEP 668
- SSH key generation: Enables secure access to provisioned instances
- vastai CLI: Installed as Python package (not binary)
Resetting Containers
Reset Database
This deletes all local data (characters, inventory, progress).
# Stop containers
docker stop hyperscape-postgres
docker rm hyperscape-postgres
# Remove volumes
docker volume rm hyperscape-postgres-data
docker volume rm server_postgres-data
# Verify
docker volume ls | grep hyperscape
# Restart
bun run dev
Reset CDN
docker stop hyperscape-cdn
docker rm hyperscape-cdn
bun run cdn:up
No Docker Alternative
If you can’t run Docker locally:
External PostgreSQL
Use a hosted database (e.g., Neon):
# packages/server/.env
DATABASE_URL=postgresql://user:pass@host.neon.tech:5432/db
External CDN
Host assets on cloud storage:
# packages/server/.env and packages/client/.env
PUBLIC_CDN_URL=https://your-cdn.example.com
Container Status
Check running containers:
Expected output when running:
CONTAINER ID IMAGE PORTS
abc123 postgres:15 0.0.0.0:5432->5432/tcp
def456 nginx:alpine 0.0.0.0:8080->80/tcp
Logs
View container logs:
docker logs hyperscape-postgres
docker logs hyperscape-cdn
