Remove moved root reference docs after relocation to docs/reference
This commit is contained in:
parent
b8174d3b71
commit
f5006521d9
@ -1,217 +0,0 @@
|
|||||||
# 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
|
|
||||||
Loading…
Reference in New Issue
Block a user