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 tracks the migration from the legacy portal model to the **ZLH-native Portal v2**.
|
||||||
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.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Migration Scope
|
## Migration Summary
|
||||||
|
|
||||||
### In Scope
|
The portal is being rebuilt to support **heterogeneous workloads**:
|
||||||
* Authentication
|
- Game servers (Minecraft initially)
|
||||||
* Instance listing & detail views
|
- Development servers (LXC-based)
|
||||||
* Removal of legacy abstractions
|
- Future non-game services
|
||||||
* Alignment with APIv2 contracts
|
|
||||||
|
|
||||||
### Out of Scope (for now)
|
This required abandoning several legacy assumptions.
|
||||||
* Billing
|
|
||||||
* RBAC / roles
|
|
||||||
* Refresh tokens
|
|
||||||
* xterm / console auth (tracked separately)
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Phase 1 — Authentication Alignment ✅ (API-side complete)
|
## Key Architectural Shifts
|
||||||
|
|
||||||
### APIv2 Status
|
### 1. Pterodactyl is no longer the control plane
|
||||||
* JWT-based auth implemented
|
- No Docker-centric lifecycle assumptions
|
||||||
* `POST /api/auth/login`
|
- No monolithic server controllers
|
||||||
* `GET /api/auth/me`
|
- No HUD-style control surface
|
||||||
* 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
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Phase 2 — Portal Login Migration (REQUIRED)
|
### 2. Agent-first runtime model
|
||||||
|
- Each server/LXC runs a ZLH Agent
|
||||||
### Required Changes
|
- Agent is authoritative for:
|
||||||
* Login form must submit:
|
- runtime state
|
||||||
|
- service health
|
||||||
```json
|
- console output
|
||||||
{
|
- API v2 brokers access, not execution
|
||||||
"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
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Phase 3 — Instances Migration ✅ (API-side verified)
|
### 3. Dashboard redesign (Completed)
|
||||||
|
|
||||||
### APIv2 Contract
|
Dashboard is now:
|
||||||
* `GET /api/instances` returns:
|
- Read-only
|
||||||
|
- Awareness-focused
|
||||||
|
- Non-operational
|
||||||
|
|
||||||
```json
|
Features:
|
||||||
{
|
- System Health indicator (frontend ↔ backend connectivity)
|
||||||
"ok": true,
|
- Notices panel with expandable timeline
|
||||||
"rows": [ ... ]
|
- Resource summaries (no controls)
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### 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.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Phase 4 — Route Protection (UPCOMING)
|
### 4. Servers page redesign (In progress)
|
||||||
|
|
||||||
### Planned Behavior
|
Servers page now:
|
||||||
* Read routes will require auth:
|
- Groups servers by type (GAME / DEV)
|
||||||
* `GET /api/instances`
|
- Uses expandable cards
|
||||||
* `GET /api/instances/:vmid`
|
- Collapsed cards show:
|
||||||
* Write routes may remain internal initially
|
- status
|
||||||
|
- uptime
|
||||||
|
- identity
|
||||||
|
- Expanded cards show:
|
||||||
|
- runtime context
|
||||||
|
- metadata
|
||||||
|
- escalation action
|
||||||
|
|
||||||
### Portal Implications
|
Only action exposed:
|
||||||
* Portal must handle `401 Unauthorized`
|
- **System View** (observation-first)
|
||||||
* Portal must redirect to login on auth failure
|
|
||||||
* No retry loops using legacy logic
|
No start/stop/restart bulk actions exist.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Phase 5 — Legacy Removal (MANDATORY)
|
## Explicitly Removed Concepts
|
||||||
|
|
||||||
### Must Be Removed From Portal
|
- "Start All / Stop All / Restart All"
|
||||||
* APIv1 client code
|
- HUD-style control buttons
|
||||||
* Pterodactyl references
|
- Console buttons on dashboard
|
||||||
* CSRF utilities
|
- AWS-style terminal metaphors
|
||||||
* Cookie-based session logic
|
|
||||||
* Any fallback to "old behavior"
|
|
||||||
|
|
||||||
### Review Rule
|
These are intentional removals.
|
||||||
If a portal file references Pterodactyl or APIv1, it must be deleted or rewritten.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Verification Checklist (Use Before Merge)
|
## Migration Status
|
||||||
|
|
||||||
* [ ] Portal login uses `/api/auth/login`
|
- Auth v2: ✅ Complete
|
||||||
* [ ] Token stored only client-side
|
- Dashboard UX: ✅ Locked
|
||||||
* [ ] All API calls include Authorization header
|
- Servers page UX: 🔄 Active
|
||||||
* [ ] Dashboard loads with zero instances
|
- System View page: ⏳ Next
|
||||||
* [ ] No CSRF or cookies present
|
- Billing integration: ⏸ Deferred
|
||||||
* [ ] 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
|
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user