Replace PORTAL_MIGRATION.md - Portal v2 migration, agent-first model, dashboard/servers redesign, removed concepts
This commit is contained in:
parent
282ccc6211
commit
e7f91b8152
@ -1,158 +1,89 @@
|
||||
# Portal Migration — APIv1/Pterodactyl → APIv2
|
||||
# ZeroLagHub Portal Migration (v2)
|
||||
|
||||
## Purpose
|
||||
This document defines the required migration steps for moving the ZeroLagHub portal from APIv1 / Pterodactyl assumptions to APIv2.
|
||||
|
||||
It exists to:
|
||||
* Prevent silent regressions
|
||||
* Provide a shared checklist for Codex, Claude, and humans
|
||||
* Make architectural intent explicit
|
||||
|
||||
This file is authoritative.
|
||||
This document tracks the migration from the legacy portal model to the **ZLH-native Portal v2**.
|
||||
|
||||
---
|
||||
|
||||
## Migration Scope
|
||||
## Migration Summary
|
||||
|
||||
### In Scope
|
||||
* Authentication
|
||||
* Instance listing & detail views
|
||||
* Removal of legacy abstractions
|
||||
* Alignment with APIv2 contracts
|
||||
The portal is being rebuilt to support **heterogeneous workloads**:
|
||||
- Game servers (Minecraft initially)
|
||||
- Development servers (LXC-based)
|
||||
- Future non-game services
|
||||
|
||||
### Out of Scope (for now)
|
||||
* Billing
|
||||
* RBAC / roles
|
||||
* Refresh tokens
|
||||
* xterm / console auth (tracked separately)
|
||||
This required abandoning several legacy assumptions.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 — Authentication Alignment ✅ (API-side complete)
|
||||
## Key Architectural Shifts
|
||||
|
||||
### APIv2 Status
|
||||
* JWT-based auth implemented
|
||||
* `POST /api/auth/login`
|
||||
* `GET /api/auth/me`
|
||||
* Stateless, header-based auth
|
||||
* No CSRF
|
||||
* No cookies
|
||||
|
||||
### Portal Requirements
|
||||
* Portal must not attempt credential validation
|
||||
* Portal must not implement CSRF
|
||||
* Portal must send `Authorization: Bearer <token>`
|
||||
* Portal must treat APIv2 as source of truth
|
||||
### 1. Pterodactyl is no longer the control plane
|
||||
- No Docker-centric lifecycle assumptions
|
||||
- No monolithic server controllers
|
||||
- No HUD-style control surface
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 — Portal Login Migration (REQUIRED)
|
||||
|
||||
### Required Changes
|
||||
* Login form must submit:
|
||||
|
||||
```json
|
||||
{
|
||||
"identifier": "<email or username>",
|
||||
"password": "<password>"
|
||||
}
|
||||
```
|
||||
|
||||
* Token must be stored in `sessionStorage`
|
||||
* Token must be attached to all API requests
|
||||
|
||||
### Forbidden Patterns
|
||||
* Cookies for auth
|
||||
* CSRF tokens
|
||||
* Legacy `/api/v1/*` calls
|
||||
* Pterodactyl login flows
|
||||
### 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
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 — Instances Migration ✅ (API-side verified)
|
||||
### 3. Dashboard redesign (Completed)
|
||||
|
||||
### APIv2 Contract
|
||||
* `GET /api/instances` returns:
|
||||
Dashboard is now:
|
||||
- Read-only
|
||||
- Awareness-focused
|
||||
- Non-operational
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"rows": [ ... ]
|
||||
}
|
||||
```
|
||||
|
||||
### Portal Expectations
|
||||
* Portal dashboard must:
|
||||
* Handle empty arrays gracefully
|
||||
* Not assume instances always exist
|
||||
* Render based on API response only
|
||||
|
||||
### Explicit Rule
|
||||
If the portal cannot render with an empty `rows` array, the portal is incorrect.
|
||||
Features:
|
||||
- System Health indicator (frontend ↔ backend connectivity)
|
||||
- Notices panel with expandable timeline
|
||||
- Resource summaries (no controls)
|
||||
|
||||
---
|
||||
|
||||
## Phase 4 — Route Protection (UPCOMING)
|
||||
### 4. Servers page redesign (In progress)
|
||||
|
||||
### Planned Behavior
|
||||
* Read routes will require auth:
|
||||
* `GET /api/instances`
|
||||
* `GET /api/instances/:vmid`
|
||||
* Write routes may remain internal initially
|
||||
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
|
||||
|
||||
### Portal Implications
|
||||
* Portal must handle `401 Unauthorized`
|
||||
* Portal must redirect to login on auth failure
|
||||
* No retry loops using legacy logic
|
||||
Only action exposed:
|
||||
- **System View** (observation-first)
|
||||
|
||||
No start/stop/restart bulk actions exist.
|
||||
|
||||
---
|
||||
|
||||
## Phase 5 — Legacy Removal (MANDATORY)
|
||||
## Explicitly Removed Concepts
|
||||
|
||||
### Must Be Removed From Portal
|
||||
* APIv1 client code
|
||||
* Pterodactyl references
|
||||
* CSRF utilities
|
||||
* Cookie-based session logic
|
||||
* Any fallback to "old behavior"
|
||||
- "Start All / Stop All / Restart All"
|
||||
- HUD-style control buttons
|
||||
- Console buttons on dashboard
|
||||
- AWS-style terminal metaphors
|
||||
|
||||
### Review Rule
|
||||
If a portal file references Pterodactyl or APIv1, it must be deleted or rewritten.
|
||||
These are intentional removals.
|
||||
|
||||
---
|
||||
|
||||
## Verification Checklist (Use Before Merge)
|
||||
## Migration Status
|
||||
|
||||
* [ ] Portal login uses `/api/auth/login`
|
||||
* [ ] Token stored only client-side
|
||||
* [ ] All API calls include Authorization header
|
||||
* [ ] Dashboard loads with zero instances
|
||||
* [ ] No CSRF or cookies present
|
||||
* [ ] No APIv1 endpoints referenced
|
||||
|
||||
---
|
||||
|
||||
## Anti-Drift Statement
|
||||
|
||||
Any deviation from this document must:
|
||||
1. Be explicitly discussed
|
||||
2. Be documented in `SESSION_LOG.md`
|
||||
3. Update `CONSTRAINTS.md` and/or `ANTI_DRIFT.md`
|
||||
|
||||
Silent changes are not allowed.
|
||||
|
||||
---
|
||||
|
||||
## Ownership
|
||||
|
||||
* **Portal Team**: Implementation
|
||||
* **APIv2**: Contract stability
|
||||
* **zlh-grind**: Enforcement and truth anchor
|
||||
|
||||
---
|
||||
|
||||
## Status
|
||||
|
||||
* **Created**: 2025-12-28
|
||||
* **State**: Active
|
||||
* **Next Update**: After route-level auth enforcement
|
||||
- Auth v2: ✅ Complete
|
||||
- Dashboard UX: ✅ Locked
|
||||
- Servers page UX: 🔄 Active
|
||||
- System View page: ⏳ Next
|
||||
- Billing integration: ⏸ Deferred
|
||||
|
||||
Loading…
Reference in New Issue
Block a user