diff --git a/PROJECT_CONTEXT.md b/PROJECT_CONTEXT.md index 91b1292..e19a9e0 100644 --- a/PROJECT_CONTEXT.md +++ b/PROJECT_CONTEXT.md @@ -29,9 +29,9 @@ System posture: stable, controlled expansion phase. | 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 | +| 1004 | zlh-zpack-proxy | Traefik — game server traffic only | | 1005 | zpack-api | Node.js API | -| 1006 | zlh-zpack-router | Game + dev server router | +| 1006 | zlh-zpack-router | Game server router | | 1100 | zpack-portal | Next.js frontend | | 2001 | zlh-back | PBS backup + Backblaze B2 | @@ -72,10 +72,9 @@ access. Pulls runtimes + server jars from zlh-artifacts (VM 1003). - 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` +- Provenance: `.zlh_metadata.json` — source is `null` if not set +- Status transport model: poll-based (`/status`), not push-based +- State transitions: `idle`, `installing`, `starting`, `running`, `stopping`, `crashed`, `error` --- @@ -90,38 +89,74 @@ access. Pulls runtimes + server jars from zlh-artifacts (VM 1003). - code-server port: `6000` - agent port: `18888` -Confirmed during current validation: +Confirmed: -- 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 +- code-server process launches and binds to `0.0.0.0:6000` +- frontend host/console state updates correctly via API status endpoint --- -## API / Proxy Coordination (Current State) +## Dev Container Access Model -Dev provisioning now includes an additive dev-only routing path. +Dev containers provide two access methods. -Current behavior: +### Browser IDE (Primary) -- 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 +``` +Browser + ↓ +Portal + ↓ +API proxy + ↓ +container:6000 +``` -Frontend/API status behavior: +URL format: `/dev//ide` -- 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 +Benefits: + +- no DNS automation +- no Traefik routing +- no TLS per container +- portal JWT controls access +- ownership validated by API before proxying + +### Local Developer Access (Advanced) + +Advanced users connect via **Tailscale / Headscale**. + +Benefits: + +- SSH +- VS Code Remote +- local tooling + +Headscale server: `zlh-ctl` (status to be confirmed) + +Constraints: + +- no exit nodes +- `magic_dns: false` +- no DNS takeover on customer machine + +### Removed Approach + +The previous model used DNS record per container, Traefik dynamic routes, +and subdomain IDE access. This was removed due to operational complexity, +TLS issues, and per-container DNS automation overhead. + +Code paths to remove from API: `createDevRouting()`, proxy SSH writes, +Traefik dynamic file creation. + +--- + +## API / Frontend Status + +- API polls agent `/status` +- API exposes polled state back to frontend via server status endpoint +- Portal no longer relies on stale DB-only state for console availability +- Game publish flow remains untouched — dev routing changes are additive only --- @@ -151,10 +186,10 @@ Revenue multiplier: 1 developer → ~10 players → $147.50/mo total. ## Open Threads -1. External dev IDE access — finalize end-to-end browser reachability for code-server -2. Curated provenance — tracking install origin (Modrinth, manual, etc.) -3. Dev routing cleanup — normalize hostname/domain generation and deletion cleanup -4. Optional future: config diff viewer, upload progress UI, upload cancellation, log search +1. Implement browser IDE proxy (`/dev/:id/ide`) in API +2. Confirm Headscale `zlh-ctl` VM status +3. Curated provenance — tracking install origin +4. Optional future: config diff viewer, upload progress UI, log search --- @@ -181,4 +216,5 @@ All at `git.zerolaghub.com/jester/` - 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 +- Do not mark unimplemented work as complete +- Game publish flow must never be modified by dev routing changes