Architecture overview

HexaHost GameCloud is a self-hosted, multi-tenant platform for on-demand Minecraft servers.

High-level diagram

flowchart TB
    subgraph users [Users]
        Browser[Web Browser]
        MC[Minecraft Client]
    end

    subgraph control [Control Plane]
        Web[Next.js Web]
        API[NestJS API]
        Worker[BullMQ Worker]
        PG[(PostgreSQL)]
        Redis[(Redis)]
        S3[(S3 / MinIO)]
    end

    subgraph nodes [Game Nodes]
        Agent[Go Node Agent]
        Docker[Docker Engine]
        Server[Minecraft Containers]
    end

    subgraph future [Phase 8+]
        Edge[Edge Gateway]
    end

    Browser --> Web
    Web --> API
    API --> PG
    API --> Redis
    Worker --> Redis
    Worker --> PG
    Worker --> S3
    API <-->|mTLS WebSocket| Agent
    Agent --> Docker
    Docker --> Server
    MC --> Server
    MC -.-> Edge
    Edge -.-> API

Component responsibilities

Control plane

Runs on one or more VMs (Ubuntu 24.04 / Debian 13). Handles authentication, server metadata, scheduling decisions, billing projection, and job orchestration. Never mounts the Docker socket.

Game nodes

Dedicated Linux VMs with Docker Engine (cgroup v2). Each node runs the node-agent as a systemd service. The agent connects outbound to the API via mTLS WebSocket and executes signed lifecycle commands locally.

Data flow

User creates a server via the web UI.
API persists state in PostgreSQL and enqueues provisioning jobs.
Worker selects a node, reserves resources, and sends server.provision to the agent.
Agent creates an isolated container and reports server.state transitions.
Backups stream to S3; metadata stays in PostgreSQL.

Security boundaries

Boundary	Mechanism
User → API	HTTPS, session cookies, CSRF, rate limits
API → Agent	mTLS, node token, signed JSON messages
Agent → Docker	Local Unix socket only, no remote exposure
Game container → Internet	Egress rules, no internal network access by default

Repository layout

See ADR 0001 for the full monorepo structure.

Protocol

Agent communication uses versioned JSON envelopes over WebSocket. Message types include agent.hello, agent.heartbeat, server.start, and server.state. See apps/node-agent/internal/protocol/messages.go.

Deployment models

Environment	Mechanism
Local development	`deploy/compose/compose.dev.yml`
Production control plane	Docker Compose + Traefik
Game nodes	Ansible + systemd node-agent

Phase roadmap

Phase	Focus
0	Repository, infra, CI, docs
1	Authentication
2	Single-node vertical slice
3–7	Panel features, multi-node, idle shutdown
8	DNS, edge gateway, join-to-start
9	Billing, production hardening

2.9 KiB Raw Blame History Unescape Escape