Add DEV_CONTAINER_SPEC.md — dev container architecture and provisioning spec
This commit is contained in:
parent
5394973e1b
commit
fc87aef69f
310
DEV_CONTAINER_SPEC.md
Normal file
310
DEV_CONTAINER_SPEC.md
Normal file
@ -0,0 +1,310 @@
|
||||
# ZeroLagHub Developer Container Architecture
|
||||
|
||||
This document describes how developer containers are provisioned and managed by the zlh-agent.
|
||||
|
||||
It is intended for engineers and AI assistants working on the ZeroLagHub platform.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Developer containers provide ephemeral development environments for building and testing software.
|
||||
|
||||
They support multiple runtimes and optional development tooling.
|
||||
|
||||
Provisioning is performed by the zlh-agent using an artifact-driven runtime system.
|
||||
|
||||
---
|
||||
|
||||
## Dev Container Lifecycle
|
||||
|
||||
Provisioning flow:
|
||||
|
||||
1. Portal sends dev container request
|
||||
2. API builds agent provisioning payload
|
||||
3. Agent validates request
|
||||
4. Agent creates dev environment
|
||||
5. Agent installs runtime from artifact server
|
||||
6. Agent optionally installs addons
|
||||
7. Agent marks container ready
|
||||
|
||||
High-level architecture:
|
||||
|
||||
```
|
||||
Portal
|
||||
↓
|
||||
zlh-api
|
||||
↓
|
||||
zlh-agent
|
||||
↓
|
||||
Artifact Server
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Dev Provisioning Payload
|
||||
|
||||
The API sends configuration to the agent via:
|
||||
|
||||
```
|
||||
POST http://<agent-ip>:18888/config
|
||||
```
|
||||
|
||||
Dev payload example:
|
||||
|
||||
```json
|
||||
{
|
||||
"container_type": "dev",
|
||||
"runtime": "node",
|
||||
"version": "22",
|
||||
"memory_mb": 2048,
|
||||
"enable_code_server": true
|
||||
}
|
||||
```
|
||||
|
||||
Fields:
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `container_type` | must be `"dev"` |
|
||||
| `runtime` | runtime id |
|
||||
| `version` | runtime version |
|
||||
| `memory_mb` | container memory |
|
||||
| `enable_code_server` | optional addon |
|
||||
|
||||
---
|
||||
|
||||
## Runtime Catalog
|
||||
|
||||
All dev runtimes are defined by the artifact server catalog.
|
||||
|
||||
Catalog location:
|
||||
|
||||
```
|
||||
http://<artifact-server>/devcontainer/_catalog.json
|
||||
```
|
||||
|
||||
Example catalog:
|
||||
|
||||
```json
|
||||
{
|
||||
"runtimes": [
|
||||
{ "id": "go", "versions": ["1.22", "1.25"] },
|
||||
{ "id": "java", "versions": ["17", "19", "21"] },
|
||||
{ "id": "node", "versions": ["20", "22", "24"] },
|
||||
{ "id": "python", "versions": ["3.10", "3.11", "3.12", "3.13"] },
|
||||
{ "id": "dotnet", "versions": ["8.0", "10.0"] }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
The agent validates runtime/version against this catalog before installation.
|
||||
|
||||
Invalid combinations cause provisioning to fail.
|
||||
|
||||
---
|
||||
|
||||
## Artifact Server Layout
|
||||
|
||||
Dev runtime artifacts:
|
||||
|
||||
```
|
||||
devcontainer/
|
||||
_catalog.json
|
||||
go/
|
||||
node/
|
||||
python/
|
||||
java/
|
||||
dotnet/
|
||||
```
|
||||
|
||||
Example runtime artifact:
|
||||
|
||||
```
|
||||
devcontainer/node/22/node-22.tar.xz
|
||||
```
|
||||
|
||||
Addon artifacts:
|
||||
|
||||
```
|
||||
addons/
|
||||
code-server/
|
||||
```
|
||||
|
||||
Artifacts are downloaded at provisioning time.
|
||||
|
||||
Nothing is preinstalled inside containers.
|
||||
|
||||
---
|
||||
|
||||
## Runtime Installation
|
||||
|
||||
Runtime install 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.
|
||||
|
||||
---
|
||||
|
||||
## Dev Environment
|
||||
|
||||
Every dev container has a dedicated development user.
|
||||
|
||||
```
|
||||
user: dev
|
||||
home: /home/dev
|
||||
workspace: /home/dev/workspace
|
||||
ownership: dev:dev
|
||||
```
|
||||
|
||||
The workspace is where developers store source code.
|
||||
|
||||
---
|
||||
|
||||
## Console Behavior
|
||||
|
||||
Dev console sessions run as the dev user.
|
||||
|
||||
Shell properties:
|
||||
|
||||
```
|
||||
user: dev
|
||||
cwd: /home/dev/workspace
|
||||
HOME=/home/dev
|
||||
TERM=xterm-256color
|
||||
```
|
||||
|
||||
This prevents root access in development environments.
|
||||
|
||||
---
|
||||
|
||||
## File System Access
|
||||
|
||||
Dev containers expose a file browser rooted at:
|
||||
|
||||
```
|
||||
/home/dev/workspace
|
||||
```
|
||||
|
||||
Portal displays this as `workspace/`.
|
||||
|
||||
Uploads and file operations are restricted to this directory.
|
||||
|
||||
Dev containers have unrestricted read/write access inside `/home/dev/workspace`. No allowlist. The only hard rule is the root sandbox — nothing can escape the workspace.
|
||||
|
||||
---
|
||||
|
||||
## Dotnet Runtime
|
||||
|
||||
Dotnet uses the official installer script.
|
||||
|
||||
Installer source:
|
||||
|
||||
```
|
||||
http://artifact-server/devcontainer/dotnet/dotnet-install.sh
|
||||
```
|
||||
|
||||
Installation:
|
||||
|
||||
```bash
|
||||
./dotnet-install.sh --channel 8.0
|
||||
```
|
||||
|
||||
Installed to:
|
||||
|
||||
```
|
||||
/opt/zlh/runtimes/dotnet/8.0
|
||||
```
|
||||
|
||||
Supported channels: `8.0`, `10.0`
|
||||
|
||||
---
|
||||
|
||||
## Code Server Addon
|
||||
|
||||
Code-server provides a browser IDE.
|
||||
|
||||
Enabled via provisioning flag:
|
||||
|
||||
```json
|
||||
"enable_code_server": true
|
||||
```
|
||||
|
||||
Artifact location:
|
||||
|
||||
```
|
||||
http://artifact-server/addons/code-server/code-server.zip
|
||||
```
|
||||
|
||||
Installed to:
|
||||
|
||||
```
|
||||
/opt/zlh/services/code-server
|
||||
```
|
||||
|
||||
Launched as:
|
||||
|
||||
```bash
|
||||
code-server --bind-addr 0.0.0.0:8080 /home/dev/workspace
|
||||
```
|
||||
|
||||
**Current blocker:** artifact currently contains source repository, not a compiled release. Artifact server must provide a runnable release archive with the following layout:
|
||||
|
||||
```
|
||||
code-server/
|
||||
bin/code-server
|
||||
lib/
|
||||
node_modules/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Security Model
|
||||
|
||||
Dev containers are isolated LXC containers.
|
||||
|
||||
Security controls:
|
||||
|
||||
- Runtime installs limited to `/opt/zlh`
|
||||
- File browser limited to workspace
|
||||
- Shell runs as non-root `dev` user
|
||||
- Artifacts fetched only from trusted artifact server
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
---
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
- Runtime checksum validation
|
||||
- Runtime upgrades / removal
|
||||
- Artifact metadata support
|
||||
- Service port auto-detection
|
||||
- Dev service routing / proxy exposure
|
||||
- IDE launch integration from portal
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Developer containers in ZeroLagHub provide isolated development environments with multiple runtime support, artifact-driven installs, optional browser IDE, and consistent reproducible provisioning.
|
||||
Loading…
Reference in New Issue
Block a user