Developer documentation

Local Development

Compose smokes and the local MVP workflow.

The Compose environment is the fastest way to exercise the product shape locally. It is not just a collection of containers; it is a compact proof of the same boundaries used by the full design: control-plane state, LDAP identity, workspace runtime, public edge routing, and integration workers.

Use it when you need to prove behavior across planes before moving to Kubernetes or production-like storage.

Start The Stack

docker compose -f dev/docker-compose.yml up --build

Focused Smokes

Each smoke proves a product boundary, not only a code path. Edge smokes prove assigned-cache routing. Nextcloud smokes prove file visibility across systems. CGI and service smokes prove controlled dynamic exposure. Matomo smokes prove log-based public analytics.

python3 dev/smoke_mvp4_edges.py
python3 dev/smoke_mvp5_alias_cdn.py
python3 dev/smoke_mvp6_nextcloud.py
python3 dev/smoke_mvp7_cgi.py
python3 dev/smoke_mvp8_runit_services.py
python3 dev/smoke_mvp9_matomo.py

Control Plane Tests

Control-plane tests should focus on state, authorization, route contracts, and API behavior. They are the fastest check for durable system decisions before running the broader integration stack.

docker compose -f dev/docker-compose.yml run --rm --build --no-deps \
  -v "$PWD/control-plane:/app" control-plane pytest -q tests/test_app.py

The control plane applies Alembic migrations at startup. API changes should also refresh the checked-in OpenAPI snapshot.