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

3.5 KiB
Raw Permalink Blame History

ZeroLagHub Developer Container Architecture

This document describes how developer containers are provisioned and accessed.

Overview

Developer containers provide ephemeral development environments.

Provisioning is performed by the zlh-agent using runtime artifacts.

Supported runtimes:

  • node
  • python
  • go
  • java
  • dotnet

Dev Container Lifecycle

Provisioning flow:

  1. Portal sends dev request
  2. API builds provisioning payload
  3. Agent installs runtime
  4. Agent installs addons
  5. Agent marks container ready

Architecture:

Portal
  ↓
zpack-api
  ↓
zlh-agent
  ↓
Artifact Server

Dev Environment

user:      dev
home:      /home/dev
workspace: /home/dev/workspace

Console sessions run as the dev user.

Runtime Installation

Runtime path:

/opt/zlh/runtimes/<runtime>/<version>

Examples:

/opt/zlh/runtimes/node/22
/opt/zlh/runtimes/python/3.12
/opt/zlh/runtimes/go/1.25
/opt/zlh/runtimes/dotnet/8.0

Install guards prevent reinstall — if the directory already exists, installation is skipped.

Code Server Addon

Code-server provides browser IDE access.

Install location:

/opt/zlh/services/code-server

Port: 6000

Observed process:

/opt/zlh/services/code-server/lib/node /opt/zlh/services/code-server \
  --bind-addr 0.0.0.0:6000 \
  --auth password \
  /home/dev/workspace

Dev IDE Access Model

The previous model using Cloudflare DNS, Traefik, and per-container subdomains has been removed.

Browser IDE Access (Primary)

IDE is accessed through the API proxy.

Browser
  ↓
Portal
  ↓
API
  ↓
container:6000

URL format: /dev/<vmid>/ide

code-server launch flags required:

--base-path /dev/<vmid>/ide --auth none

Portal JWT authentication gates access. The API verifies container ownership before proxying.

WebSocket support is mandatory — code-server is heavily WebSocket-based:

  • http-proxy-middleware with ws: true
  • server.on('upgrade', proxy.upgrade) must be wired up

Local Development Access (Advanced Users)

Advanced users may connect via Headscale/Tailscale.

Benefits:

  • SSH
  • VS Code Remote
  • full local tooling

Implementation:

  • dev container installs tailscaled as an addon
  • API generates Headscale auth key on provisioning
  • customer joins tailnet once, gets stable container IP

Restrictions:

  • no exit nodes
  • magic_dns: false
  • no DNS takeover on customer machine

Headscale server: zlh-ctl (status to be confirmed)

Security Model

  • Portal authentication controls IDE access
  • API verifies container ownership before proxying
  • Containers are never exposed directly to the public internet
  • Shell runs as non-root dev user
  • File browser limited to workspace root

File Browser

Workspace root: /home/dev/workspace

Portal displays this as workspace/.

Uploads cannot escape this directory.

Agent Status

Status is polled by API via /status. Agent does not push state.

Dev fields in /status:

  • workspaceRoot
  • runtimeInstallPath
  • runtimeInstalled
  • codeServerInstalled
  • codeServerRunning

Design Principles

  1. No local runtime assumptions
  2. All runtimes are artifact-driven
  3. Runtime catalog is the source of truth
  4. Installs must be idempotent
  5. Containers must remain reproducible
  6. Dev services are never publicly exposed directly

Future Enhancements

  • Runtime checksum validation
  • Runtime upgrades / removal
  • Artifact metadata support
  • Tailscale addon implementation
  • Headscale auth key portal UI