jester 5363cb9ab5 Update PROJECT_CONTEXT — dev containers current state, API routing, status model, session guidance

2026-03-15 22:02:59 +00:00

6.3 KiB

Raw Blame History

ZeroLagHub – Project Context

What It Is

Game server hosting platform targeting modded, indie, and emerging games. Competitive advantages: LXC containers (20-30% perf over Docker), custom agent architecture, open-source stack, developer-to-player pipeline that turns mod developers into a distribution channel.

System posture: stable, controlled expansion phase.

Naming Convention

zlh-* = core infrastructure (DNS, monitoring, backup, routing, artifacts)
zpack-* = game and dev server stack (portal, API, containers)

Infrastructure (Proxmox)

Active VMs

VM	Name	Role
104	zlh-monitor	Prometheus/Grafana monitoring
105	zlh-router	Core services router
300	zlh-velocity	Minecraft Velocity proxy
1001	zlh-dns	Technitium DNS
1002	zlh-proxy	Traefik — core/frontend SSL termination (portal traffic)
1003	zlh-artifacts	Runtime binaries + Minecraft server jars (agent install source)
1004	zlh-zpack-proxy	Traefik — game and dev server traffic
1005	zpack-api	Node.js API
1006	zlh-zpack-router	Game + dev server router
1100	zpack-portal	Next.js frontend
2001	zlh-back	PBS backup + Backblaze B2

Legacy / Reference Only (not active production)

VM	Name	Notes
100	zlh-panel	Old Pterodactyl panel — kept for reference
101	zlh-wings	Old Wings — kept for reference
103	zlh-api	Old API VM — kept for reference
1000	zlh-router	Not in use

Stack

API (zpack-api, VM 1005): Node.js ESM, Express 5, Prisma 6, MariaDB, Redis, BullMQ, JWT, Stripe, argon2, ssh2, WebSocket

Portal (zpack-portal, VM 1100): Next.js 15, TypeScript, TailwindCSS, Axios, WebSocket console. Sci-fi HUD aesthetic (steel textures, neon accents, beveled panels).

Agent (zlh-agent): Go 1.21, stdlib HTTP, creack/pty, gorilla/websocket. Runs inside every game/dev container. Only process with direct filesystem access. Pulls runtimes + server jars from zlh-artifacts (VM 1003).

Agent (Operational)

HTTP server on :18888, internal only — API is the only caller
Container types: game and dev
Lifecycle: POST /config triggers async provision + start pipeline
Filesystem: strict path allowlist for games, workspace-root sandbox for dev containers
Upload transport: raw http.request piping (req.pipe(proxyReq)), never fetch()
Console: PTY-backed WebSocket, one read loop per container
Self-update: periodic check + apply
Forge/Neoforge: automated 5-step post-install patch sequence
Modrinth mod lifecycle: install/enable/disable/delete — fully operational
Provenance: .zlh_metadata.json — source is null if not set, no curated inference currently implemented
Status transport model remains poll-based (/status), not push-based
/status content now includes richer dev/runtime/code-server fields
State transitions remain internal to agent: idle, installing, starting, running, stopping, crashed, error

Dev Containers (Current State)

supported runtimes: node, python, go, java, dotnet
runtime installs are artifact-backed and idempotent
runtime root: /opt/zlh/runtimes/<runtime>/<version>
dev identity: dev:dev
workspace root: /home/dev/workspace
code-server install path: /opt/zlh/services/code-server
code-server port: 6000
agent port: 18888

Confirmed during current validation:

code-server process launches inside the container
process binds to 0.0.0.0:6000
Traefik dynamic dev route is created by API during provisioning
frontend host/console state now updates correctly after API status endpoint work

Current unresolved item:

external browser access to code-server through Cloudflare → Traefik → dev container is still being finalized

API / Proxy Coordination (Current State)

Dev provisioning now includes an additive dev-only routing path.

Current behavior:

game publish flow remains untouched
if container type is dev and enable_code_server=true, API:
- creates Technitium A record
- creates Cloudflare A record
- writes Traefik dynamic config on zlh-zpack-proxy
remote Traefik file writes use SSH service account zlh
proxy SSH configuration is now service-account based, not tied to personal user

Frontend/API status behavior:

API still polls agent state
API now exposes server status back to frontend so host/console UI is accurate
portal is no longer relying on stale DB-only host state for console availability

Game Support

Production: Minecraft (vanilla/Fabric/Paper/Forge/Neoforge), Rust, Terraria, Project Zomboid

In Pipeline: Valheim, Palworld, Vintage Story, Core Keeper

Developer-to-Player Pipeline (Revenue Model)

LXC Dev Environment ($15-40/mo)
  → Game/mod creation + testing
  → Testing servers (50% dev discount)
  → Player community referrals (25% player discount)
  → Developer revenue share (5-10% commission)
  → Viral growth

Revenue multiplier: 1 developer → ~10 players → $147.50/mo total.

Open Threads

External dev IDE access — finalize end-to-end browser reachability for code-server
Curated provenance — tracking install origin (Modrinth, manual, etc.)
Dev routing cleanup — normalize hostname/domain generation and deletion cleanup
Optional future: config diff viewer, upload progress UI, upload cancellation, log search

Repo Registry

Repo	Purpose
zlh-grind	Execution workspace / continuity / active constraints
zlh-docs	API/agent/portal reference docs (read from source)
zpack-api	API source (mirror)
zpack-portal	Portal source (mirror)
zlh-agent	Agent source

All at git.zerolaghub.com/jester/<repo>

Session Guidance

zlh-grind is the execution continuity layer, not the architecture authority
zlh-docs has full agent documentation (routes, filesystem rules, provisioning pipeline)
Agent is the authority on filesystem enforcement — API must NOT duplicate filesystem logic
Portal does not enforce real policy — agent enforces
Portal never calls agents directly — all traffic through API
Upload transport uses raw http.request piping, never fetch()
VMs 100, 101, 103, 1000 are legacy/unused — not active production
Do not mark unresolved routing or TLS work as complete

6.3 KiB Raw Blame History Unescape Escape