docs: update portal migration - reflect Feb 2026 current state
This commit is contained in:
parent
7ef9bc63ad
commit
ccedde9b5c
@ -1,200 +1,31 @@
|
||||
# ZeroLagHub Portal Migration (v2)
|
||||
# Portal Migration — ZeroLagHub
|
||||
|
||||
This document tracks the migration from the legacy portal model to the **ZLH-native Portal v2**.
|
||||
This document tracks the transition from legacy console behavior to the current
|
||||
agent-driven, PTY-backed architecture.
|
||||
|
||||
---
|
||||
|
||||
## Migration Summary
|
||||
## Current State (Feb 2026)
|
||||
|
||||
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.
|
||||
- All server consoles are PTY-backed and agent-owned.
|
||||
- Frontend streams output via WebSocket (single writer).
|
||||
- Game and dev consoles are **route-separated** but share components.
|
||||
- Metrics and player presence are sourced server-side (API → agent).
|
||||
- No frontend log scraping or client-side metrics access.
|
||||
|
||||
---
|
||||
|
||||
## Key Architectural Shifts
|
||||
## Migration Notes
|
||||
|
||||
### 1. Pterodactyl is no longer the control plane
|
||||
- No Docker-centric lifecycle assumptions
|
||||
- No monolithic server controllers
|
||||
- No HUD-style control surface
|
||||
- Pterodactyl-style assumptions (polling logs, iframe dashboards) are explicitly not used.
|
||||
- Grafana is reserved for internal/admin use only.
|
||||
- Customer-facing metrics are API-mediated summaries.
|
||||
- Game-specific context is additive and isolated to game routes.
|
||||
|
||||
---
|
||||
|
||||
### 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
|
||||
## Remaining Migration Work
|
||||
|
||||
---
|
||||
|
||||
### 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.
|
||||
|
||||
---
|
||||
|
||||
## Architectural Boundaries (CRITICAL)
|
||||
|
||||
### What Frontend MUST NOT Do
|
||||
|
||||
**Never Call Agents Directly**
|
||||
- Frontend cannot reach container IPs
|
||||
- Frontend has no network path to agents
|
||||
- All agent access flows through API
|
||||
- This is non-negotiable architecture
|
||||
|
||||
**Why This Matters**
|
||||
- Container IPs are internal-only (10.x network)
|
||||
- No CORS headers on agents (they're not web services)
|
||||
- Direct calls would fail and break the security model
|
||||
- API enforces auth, rate limits, and access control
|
||||
|
||||
**Correct Flow**
|
||||
```
|
||||
User Action → Frontend → API → Agent → Response
|
||||
```
|
||||
|
||||
**Incorrect Flow (FORBIDDEN)**
|
||||
```
|
||||
User Action → Frontend → Agent (FAILS - no network path)
|
||||
```
|
||||
|
||||
### What Can Break This
|
||||
|
||||
**AI Coding Tools**
|
||||
- May suggest "quick fixes" that call agents directly
|
||||
- May treat agents as HTTP APIs with CORS
|
||||
- May generate code that "just works" in wrong way
|
||||
|
||||
**Convenience Changes**
|
||||
- Adding CORS headers to agents (never do this)
|
||||
- Exposing agent ports through proxy (breaks security)
|
||||
- Creating frontend → agent shortcuts (breaks architecture)
|
||||
|
||||
### Enforcement
|
||||
|
||||
If a change violates these boundaries:
|
||||
- The change must be reverted
|
||||
- The documentation takes precedence
|
||||
- AI tools must be corrected
|
||||
|
||||
These constraints override convenience.
|
||||
- Final UI polish and UX consistency checks
|
||||
- Concurrent provisioning validation
|
||||
- Formal GA readiness checklist
|
||||
|
||||
Loading…
Reference in New Issue
Block a user