Ambitwin · source-available, not open source · © 2026 Nicolò Ghignatti
| Word | Meaning | Example |
|---|---|---|
| Compose file | A YAML list of containers, their images, ports and volumes | backend/telemetry/docker-compose.yml |
| Fragment | One service’s own compose file | backend/chat/docker-compose.yml |
| Dev override | A second file that changes a fragment for live editing | docker-compose.dev.yml |
include: | A Compose key that loads other compose files, each from its own folder | compose.runtime.yml |
| Project | The group of containers Compose starts together, under one name | ambitwin-integration-tests |
| Volume | Storage that outlives the container | telemetry-data |
| Watch | Compose copies changed files into a running container, or rebuilds it | develop.watch |
| Edge | The one entry point every browser request goes through | Caddy on port 80 |
forward_auth | Caddy asks another service “may this request pass?” before sending it on | claims-gateway /verify |
Locally the whole platform runs under Docker Compose. No single file lists every service: each service keeps its own compose file beside its code, and a small script joins them into one on every start.
| File | Holds | Example |
|---|---|---|
docker-compose.yml (root) | Shared parts only: gateway (Caddy), redis, kafka, keycloak, keycloak-db, prometheus, grafana; includes docker/rust-base | — |
backend/<svc>/docker-compose.yml | The service and its own database | telemetry, telemetry-db |
backend/<svc>/docker-compose.dev.yml | Changes for just stack dev: target: dev, watch rules, published database ports, database browsers | telemetry-db-gui |
backend/<svc>/docker-compose.test.yml | A throwaway stack for that service’s integration tests | telemetry-test |
backend/acceptance/docker-compose.*.yml | The cross-service acceptance stack | integration-tests |
docker/rust-base/docker-compose.yml | The Rust build image, scale: 0 | rust-base |
simulators/*/, devices/ap-collector/, frontend/ | Same base + dev pair | client |
networks:, so every container of a project joins Compose’s default network and reaches the others by service name: telemetry:3000, redis:6379.backend/agent holds 9 services: agent, agent-db, agent-ingester and the Langfuse stack (langfuse-web, langfuse-worker, langfuse-db, redis-langfuse, clickhouse, minio).just stack dev, step by stepsequenceDiagram
autonumber
participant U as Developer
participant J as just
participant E as "scripts/env, one script per area"
participant P as compose-run.py
participant D as docker compose
U->>J: just stack dev --no-agent
J->>E: env recipe, 11 scripts in order
E->>E: append missing secrets to the env file, rewrite RUST_VERSION
J->>P: python3 scripts/compose/compose-run.py dev --no-agent
P->>P: argparse, expand --no-agent to pattern agent
P->>P: add docker-compose.yml
P->>P: walk backend/, simulators/, devices/, skip excluded folders
P->>P: add frontend
P->>P: write compose.runtime.yml
P->>D: config --format json
P->>P: find stopped containers with a fixed name, docker rm -f them
P->>D: config --services, drop names matching agent
P->>D: up --watch --remove-orphans, with the kept service names
D->>D: build images, start containers in depends_on order, watch files| Step | What happens | Real value |
|---|---|---|
| 2 | create, vapid, token, config, langfuse, keycloak, controlplane, gateway-key, ingest-key, telemetry-db, rust | Each one skips a key already in .env |
| 3 | Only rust.sh rewrites a value every time | RUST_VERSION= the pin in .mise.toml |
| 5 | --no-agent becomes the substring agent | EXCLUDE_GROUPS["agent"] = ("agent",) |
| 7 | Each folder adds docker-compose.yml, and in dev also docker-compose.dev.yml | backend/agent skipped: printed excluded: backend/agent |
| 9 | One include: entry per folder; a pair becomes one entry with two paths | 16 entries: root, 10 backend, 3 simulators, ap-collector, frontend |
| 11 | A stopped container with a container_name would block up with a name clash | ambitwin-socket |
| 12 | The root file is always included, so its services can only be dropped by name | — |
| 13 | COMPOSE_BAKE=true: builds go through BuildKit Bake, in parallel | — |
The generated file looks like this:
# Auto-generated by scripts/compose/compose-run.py — do not commit.
include:
- path: docker-compose.yml
- path:
- backend/chat/docker-compose.yml
- backend/chat/docker-compose.dev.yml
- path:
- backend/claims-gateway/docker-compose.yml
- backend/claims-gateway/docker-compose.dev.ymlcompose.runtime.yml is in .gitignore.
include: and not several -f flagsWith -f a.yml -f b.yml, Compose resolves every relative path against the first file’s folder. build.context: ../.. in backend/telemetry/docker-compose.yml would then point two levels above the repo root. include: resolves each file against its own folder.
A pair of files is one entry because two separate entries may not define the same service: Compose stops with a conflict.
flowchart TD
A["argument"] --> F{"--no-group flag?"}
F -- yes --> G["its patterns from EXCLUDE_GROUPS"]
F -- no --> S["the argument itself, as a substring"]
G --> M{"mode is down or build?"}
S --> M
M -- yes --> N["ignored: everything is included"]
M -- no --> C["folder name contains it: whole fragment left out"]
C --> V["service name contains it: left out of the up list"]| Flag | Patterns | Leaves out |
|---|---|---|
--no-agent | agent | backend/agent, all 9 services |
--no-metrics | prometheus, grafana | Two root services, by name |
--no-simulators | simulator | The three simulator folders |
--no-devices | ap-collector | devices/ap-collector |
| bare word | itself | Anything whose folder or service name contains it |
Example. just stack dev chat:
backend/chat contains chat: its two files are not included.chat, so nothing else goes.Example of a trap. just stack dev db drops every service with db in its name: twin-db, telemetry-db, keycloak-db… and the stack cannot start.
| Recipe | Mode | Command |
|---|---|---|
just stack dev | dev | up --watch --remove-orphans |
just stack dev --build | dev | the same, plus --build |
just stack start | start | up --build -d --remove-orphans, production stages, in the background |
just stack down | down | down --remove-orphans, always everything |
just stack logs <svc> | — | docker compose -f compose.runtime.yml logs -f <svc> |
--dry-run | any | Prints the docker command and stops after writing the file |
gateway runs caddy:2.11.7 on ${BACKEND_PORT} (80), with the repo-root Caddyfile mounted read-only.
| Path | Goes to | Gated | Prefix removed |
|---|---|---|---|
/gateway/* | claims-gateway:3000 | no | yes |
/tenancy/*, /twin/*, /notification/*, /chat/*, /dashboard, /dashboard/*, /telemetry/* | the service | yes | yes |
/socket.io/* | socket:3000 | yes | no: Socket.IO expects its own path |
/agent/* | agent:3000 | no, and X-Gateway-Claims is removed | yes |
/telemetry/ingest, /telemetry/collector, /telemetry/observations | telemetry:3000 | no: the body is HMAC-signed and checked inside telemetry | /telemetry only |
/prometheus/*, /grafana/* | the tool | no | /prometheus only |
/<x>-db-gui/* | the database browser of each Mongo service and telemetry | no | no |
/langfuse* | redirect to port 3030 | — | — |
/chat/* adds flush_interval -1: answers stream as SSE, and buffering would deliver every token at the end.
sequenceDiagram
autonumber
participant B as Browser
participant C as Caddy
participant G as claims-gateway
participant T as digital-twin
B->>C: GET /twin/buildings, cookie authentication_token
C->>G: GET /verify, same headers
G->>G: RequireAuthentication: extractToken
G->>G: jwt.ParseWithClaims, RS256, issuer cv-gateway
alt token missing or bad
G-->>C: 401
C-->>B: 401, the service is never called
else valid
G->>G: verifyHandler: json.Marshal(claims), base64
G-->>C: 200, X-Gateway-Claims
C->>C: copy_headers X-Gateway-Claims, strip /twin
C->>T: GET /buildings, x-gateway-claims
T->>T: decode the header, run Cedar
T-->>B: 200
end| Step | Data |
|---|---|
| 1 | Cookie: authentication_token=eyJhbGciOiJSUzI1NiIs… |
| 3 | extractToken reads Authorization: Bearer … first, then the cookie |
| 4 | Signature checked against claims-gateway’s own public key; only RS256 accepted |
| 8 | {"sub":"ada","memberships":[…],"exp":…} as standard base64 |
| 10 | Path /twin/buildings becomes /buildings |
Why the edge checks once: the services behind it never verify a signature; they read the header. The cluster does the same with Istio, so a service runs unchanged in both places: Kubernetes & Istio.
gateway lists five services in depends_on with required: false: it starts even when they are left out, and finds them when they appear, because Caddy looks up each name per request.
.env: what just stack env writesEvery dev and start runs env first. Each script appends only what is missing, so a second run changes nothing except RUST_VERSION.
| Script | Writes |
|---|---|
create.sh | An empty .env, mode 600 |
vapid.sh | VAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY, VITE_VAPID_PUBLIC_KEY, a P-256 key pair; checks the lengths 87 and 43 |
token.sh | EVAL_JWT_SECRET, 32 random bytes, local evals only |
config.sh | BACKEND_PORT=80, FRONTEND_PORT=8080, DEV_URL=http://localhost; asks for OPENROUTER_API_KEY |
langfuse.sh | Langfuse keys, salt, passwords |
keycloak.sh | KEYCLOAK_ADMIN_PASSWORD, KEYCLOAK_DB_PASSWORD, empty Google client fields |
controlplane.sh | INTERNAL_SIGNING_SECRET, TENANCY_DB_PASSWORD, REGISTRY_DB_PASSWORD |
gateway-key.sh | secrets/gateway-dev-key.pem, a 2048-bit RSA key, only if missing |
ingest-key.sh | TELEMETRY_INGEST_SECRET, TELEMETRY_DEVICE_MASTER_KEY |
telemetry-db.sh | TELEMETRY_DB_PASSWORD |
rust.sh | RUST_VERSION, rewritten every run so a bump in .mise.toml reaches the build |
The RSA key is kept on disk, not regenerated: a new key would make every signed-in cookie invalid.
| Language | Watch rule | On a source change | On a dependency change |
|---|---|---|---|
| Rust | sync ./src | cargo watch -x run rebuilds the service crate only | Cargo.toml, Cargo.lock: rebuild the image |
| Go | sync ./ | air rebuilds and restarts | go.mod: rebuild |
agent | sync ./app | uvicorn --reload | pyproject.toml: rebuild |
frontend | sync ./src | Vite dev server, npm run dev | package.json: rebuild |
target/ volume. The dev image already holds a fresh build; a volume over target/ would hide it, and every dependency change would compile twice.go-mod-cache (/go/pkg/mod) and go-build-cache (/root/.cache/go-build). Go locks inside the cache folders, so four containers can use them at once.--wiredTigerCacheSizeGB 0.25. Without it each of the four instances may grow towards half the host’s memory.Only the dev overrides publish database ports. Two services on one host port stop the whole up.
| Port | Service |
|---|---|
| 80 | gateway |
| 8080 | client (frontend) |
| 5432, 5433, 5434, 5435 | telemetry-db, tenancy-db, registry-db, agent-db |
| 27017, 27019, 27020, 27021 | twin-db, notification-db, dashboard-db, chat-db |
| 6379, 9092, 8090 | redis, kafka, keycloak |
| 3001, 3002, 3003 | sensor-simulator, aq-simulator, ap-simulator |
| 3030 | langfuse-web |
just test <svc>-integrationsequenceDiagram
autonumber
participant J as just
participant S as test-integration.sh
participant D as docker compose
participant T as telemetry-test
J->>S: bash backend/telemetry/test-integration.sh
S->>S: RUST_VERSION from the mise pin
S->>S: trap down --volumes on EXIT
S->>D: -p telemetry-integration-tests up --build --exit-code-from telemetry-test
D->>D: start telemetry-db, telemetry-redis, telemetry-kafka
D->>T: target dev, run scripts/test/rust-integration-tests.sh
T-->>D: exit code
D-->>S: same exit code
S->>D: down --remove-orphans --volumes| Service | Project | Infra |
|---|---|---|
chat | chat-integration-tests | MongoDB |
digital-twin | digital-twin-integration-tests | MongoDB |
notification | notification-integration-tests | MongoDB, Redis, Kafka |
socket | socket-integration-tests | Redis |
telemetry | telemetry-integration-tests | TimescaleDB, Redis, Kafka |
dashboard | dashboard-integration-tests | MongoDB, Redis |
just stack dev.trap … EXIT: under set -e, a failed up would exit before a trailing down.just test integrationbackend/acceptance/run-integration-tests.sh writes compose.integration-tests.runtime.yml:
| Included file | Gives |
|---|---|
docker/rust-base/docker-compose.yml | The Rust build image |
backend/acceptance/docker-compose.infra.yml | redis, kafka |
backend/{telemetry,socket,dashboard}/docker-compose.yml | The three real services |
backend/acceptance/docker-compose.integration.yml | Stubs for digital-twin and claims-gateway (nginx), the real Caddy gateway, and the integration-tests runner |
Caddyfile is mounted, so backend/acceptance/edge/ tests the edge that ships.claims-gateway answers /verify with a fixed 401 and a marker, so a test can tell an edge refusal from a service one.just stack env.just stack dev does not rebuild by default. Only --build, or a watched rebuild file, rebuilds an image. A Dockerfile change needs --build.--no-simulators leaves telemetry’s SIMULATORS list as is. Starting a simulation then fails to reach them.prometheus, grafana, keycloak go only by name, which is why --no-metrics exists.container_name is global. ambitwin-socket is shared by the dev stack and the acceptance stack; the acceptance script removes a stopped one, never a running one.Related: Docker Images, Kubernetes & Istio, Build System.