HexaHost GameCloud

Selbstgehostete, mandantenfähige Plattform für On-Demand-Minecraft-Server.

Der Projektname HexaHost GameCloud ist ein Arbeitstitel und zentral über APP_NAME / NEXT_PUBLIC_APP_NAME konfigurierbar.

Voraussetzungen

Tool	Version
Node.js	≥ 22
pnpm	9.15.x (corepack enable)
Docker	für lokale Infrastruktur
Go	1.23+ (Node Agent)

Schnellstart (lokal)

# Abhängigkeiten installieren
corepack enable
pnpm install

# Umgebung vorbereiten
cp .env.example .env
# SESSION_SECRET und ENCRYPTION_KEY auf mindestens 32 Zeichen setzen

# Infrastruktur (PostgreSQL, Redis, MinIO, Mailpit)
pnpm dev:infra

# Datenbankschema anwenden
pnpm db:push

# Entwicklungsserver (API, Worker, Web parallel)
pnpm dev

Dienste (Entwicklung)

Dienst	URL
Web	http://localhost:3000
API	http://localhost:3001/api/v1
OpenAPI	http://localhost:3001/api/v1/docs
Worker Health	http://localhost:3002/health
Mailpit	http://localhost:8025
MinIO Console	http://localhost:9001

Optional für Docker Compose mit Traefik-Netzwerk:

docker network create traefik-network

Monorepo-Struktur

apps/
  web/           Next.js Weboberfläche
  api/           NestJS API (Fastify)
  worker/        BullMQ Hintergrundjobs
  node-agent/    Go-Daemon auf Game-Nodes
  edge-gateway/  Go TCP/UDP Gateway (Phase 8)
packages/
  database/      Prisma Schema & Client
  contracts/     Zod-Schemas & API-Verträge
  config/        Typisierte Konfiguration
  auth/          Authentifizierungslogik
  ui/            Gemeinsame UI-Komponenten
deploy/          Docker Compose, systemd, Ansible
docs/            Architektur, ADR, Betrieb
integrations/    WHMCS-Modul (`hexagamecloud`)

Befehle

pnpm build          # Alle Pakete bauen
pnpm lint           # Linting
pnpm typecheck      # TypeScript-Prüfung
pnpm test           # Unit-Tests
pnpm db:generate    # Prisma Client generieren
pnpm db:migrate     # Migrationen ausführen

Go Node Agent:

cd apps/node-agent
make test
make build

Aktueller Stand

Phase 9 (WHMCS & Produktion) — abgeschlossen.

Siehe docs/IMPLEMENTATION_STATUS.md für Details.

Server-Verwaltung im Panel

Tab	Funktion
Übersicht	Status, Start/Stop/Restart, Verbindungsadresse
Konsole	Live-Logs, RCON-Befehle
Dateien	Verzeichnisliste, Dateien bearbeiten
Eigenschaften	server.properties
Spieler	Online-Spieler, Whitelist
Welten	Welten anzeigen, Upload/Download (Server gestoppt)
Backups	Manuell/geplant, Restore, Retention
Add-ons	Modrinth-Suche, Paper-Plugins / Fabric-Mods installieren

Minecraft-Server lokal testen

pnpm dev:infra
pnpm db:migrate    # oder db:push bei frischer DB
pnpm db:seed       # Free-Plan + Dev-Node
pnpm dev

# Separates Terminal — Node Agent (Go 1.23 + Docker Desktop)
cd apps/node-agent
# NODE_ID, NODE_TOKEN, NODE_AGENT_PUBLIC_URL aus .env.example setzen
make run

1. Registrieren / einloggen unter http://localhost:3000
2. Server erstellen unter /servers/new
3. Starten — Adresse localhost:<port> im Panel
4. Minecraft: Multiplayer → localhost:<port>

Auth lokal testen

cp .env.example .env
pnpm dev:infra
pnpm db:migrate
pnpm dev

# Admin anlegen (keine Default-Zugangsdaten)
pnpm bootstrap:admin -- --email admin@localhost --password 'min-12-chars-here'

Flow	URL
Registrierung	http://localhost:3000/register
Login	http://localhost:3000/login
E-Mails (Dev)	http://localhost:8025 (Mailpit)

Lizenz

Proprietär — siehe Repository-Eigentümer.