jester/zlh-grind
1
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases Wiki Activity
cf29e91ebe
zlh-grind/PORTAL_MIGRATION.md

3.2 KiB
Raw Blame History

ZeroLagHub Portal Migration (v2)

This document tracks the migration from the legacy portal model to the ZLH-native Portal v2.

Migration Summary

The portal is being rebuilt to support heterogeneous workloads:

  • Game servers (Minecraft initially)
  • Development servers (LXC-based)
  • Future non-game services

This required abandoning several legacy assumptions.

Key Architectural Shifts

1. Pterodactyl is no longer the control plane

  • No Docker-centric lifecycle assumptions
  • No monolithic server controllers
  • No HUD-style control surface

2. Agent-first runtime model

  • Each server/LXC runs a ZLH Agent
  • Agent is authoritative for:
    • runtime state
    • service health
    • console output
  • API v2 brokers access, not execution

3. Dashboard redesign (Completed)

Dashboard is now:

  • Read-only
  • Awareness-focused
  • Non-operational

Features:

  • System Health indicator (frontend ↔ backend connectivity)
  • Notices panel with expandable timeline
  • Resource summaries (no controls)

4. Servers page redesign (In progress)

Servers page now:

  • Groups servers by type (GAME / DEV)
  • Uses expandable cards
  • Collapsed cards show:
    • status
    • uptime
    • identity
  • Expanded cards show:
    • runtime context
    • metadata
    • escalation action

Only action exposed:

  • System View (observation-first)

No start/stop/restart bulk actions exist.

Explicitly Removed Concepts

  • "Start All / Stop All / Restart All"
  • HUD-style control buttons
  • Console buttons on dashboard
  • AWS-style terminal metaphors

These are intentional removals.

Migration Status

  • Auth v2: ✅ Complete
  • Dashboard UX: ✅ Locked
  • Servers page UX: 🔄 Active
  • System View page: ⏳ Next
  • Billing integration: ⏸ Deferred

Live Status Model (Finalized)

The portal consumes aggregated live state from the API. It does not directly query agents, Proxmox, or exporters.

Status Layers

Host / Agent Health

  • Source: GET /health on agent
  • Cached in Redis
  • Determines host availability

Service Runtime

  • GAME:
    • Source: GET /status
    • Reflects actual game server lifecycle
  • DEV:
    • No service runtime
    • Status inferred from host availability

UI Mapping

Container Type Host Online Agent State UI Status
DEV true n/a running
DEV false n/a offline
GAME true running running
GAME true idle stopped
GAME false n/a offline

Notes

  • "Idle" does not mean broken
  • Offline means host unreachable
  • UI refresh reflects Redis state, not instant agent changes

This model intentionally mirrors Pterodactyl semantics.

Console Responsibility Split (Authoritative)

Agent

  • Owns PTY lifecycle
  • Owns process execution
  • Owns security boundary
  • Owns WebSocket console endpoint

API

  • Authenticates console access
  • Provides server metadata (vmid, type)
  • Does NOT proxy PTY traffic

Portal

  • Renders terminal UI
  • Sends raw input bytes
  • Displays streamed output
  • Must not assume process state

This split is intentional and enforced to prevent drift.