218 lines
3.5 KiB
Markdown
218 lines
3.5 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
/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
|