/

Ambitwin · source-available, not open source · © 2026 Nicolò Ghignatti

Docker Images

Keywords on this page
WordMeaningExample
ImageA frozen file system plus a start command, ready to run as a containerambitwin-telemetry
StageOne FROM block of a Dockerfile. Later stages copy files out of earlier onesplanner, builder, production
TargetThe stage a build stops attarget: dev in compose
Build contextThe folder whose files a Dockerfile may COPYThe repo root, .
Named contextAn extra build context, given a name a FROM can userust-base
Layer cacheDocker reuses a step when its inputs did not changeA cook skipped because recipe.json is the same
cargo-chefA tool that splits “build the dependencies” from “build the service”prepare, then cook
RecipeThe dependency list cargo-chef writes, with no source coderecipe.json
DistrolessA base image with no shell and no package managergcr.io/distroless/cc-debian12:nonroot
sccacheA compiler cache that keeps compiled crates between builds/sccache cache mount
TrivyA scanner that fails the build on known holes in OS packagesRun in ci-docker and cd-registry

Every deployable part ships as one image. Each service keeps its Dockerfile beside its code, and all images follow one of five patterns, one per language. The images are built in three places: by Compose on a laptop, by ci-docker on a pull request, and by cd-registry on master.


The images

PartPatternDockerfileBuild contextProduction basePort
telemetry, digital-twin, notification, socket, dashboard, chatRustbackend/<svc>/Dockerfilerepo rootgcr.io/distroless/cc-debian12:nonroot3000
claims-gateway, tenancy, registry, provisionerGobackend/<svc>/Dockerfilerepo rootgcr.io/distroless/static-debian12:nonroot3000
agentPython, two stagesbackend/agent/Dockerfilerepo rootpython:3.14.8-slim3000
aq-simulator, ap-simulator, ap-collectorPython, one stage<dir>/Dockerfileown folderpython:3.14.8-slim3000
frontendStatic sitefrontend/Dockerfilefrontend/nginx:1.31.5-alpine8080
sensor-simulatorNodesimulators/sensor-simulator/Dockerfileown foldernode:24.21.0-alpine3000

Why the repo root is the context for most of them: a service reads files that live outside its own folder.

ServiceReads from outside its folderWhy
Rust servicesschemas/*-schemaPath dependencies in Cargo.toml, like telemetry-schema = { path = "../../schemas/telemetry-schema" }
telemetry, digital-twinbackend/libs/auth-policy, backend/libs/auth-contractsThe Cedar bundle and roles.json, read when compiling
Go servicesbackend/libs/*Go modules replaced by local paths
agentbackend/libs/auth-policy, backend/libs/auth-contractsapp/cedar_authz.py reads the policy files at run time, by a path relative to itself

A Docker build cannot COPY anything above its context. So a context of backend/telemetry could never reach schemas/.


.github/services.json

One file lists every package. CI reads it to know what to build and how.

FieldMeaningExample
keyShort nametwin
dirWhere the code livesbackend/digital-twin
langPicks the CI template and the Docker patternrust, go, python, node, frontend
imageImage name on GHCRambitwin-twin
cd_contextBuild context for ci-docker and cd-registry. . is the repo root; missing means dir.
dockerfileDockerfile path, from the repo root; missing means Dockerfile in the contextbackend/digital-twin/Dockerfile
depends_onFolders it builds or tests from; a change there rebuilds its image tootwin: schemas/twin-schema
needs_mongo, needs_redis, needs_kafka, needs_postgresWhich databases CI starts for the integration teststelemetry: Redis, Postgres, Kafka
cifalse keeps a package out of the CI gatethe three simulators

Two names break the “one name everywhere” rule here: digital-twin has key twin and image ambitwin-twin; sensor-simulator has image ambitwin-simulator.


Rust: one Dockerfile, five stages

All six Rust Dockerfiles have the same shape. telemetry is the example.

flowchart TD
    RB["rust-base<br/>toolchain, mold, cargo-chef, cargo-watch, sccache"] --> CH["chef<br/>WORKDIR /app/backend/telemetry"]
    CH --> PL["planner<br/>cargo chef prepare"]
    CH --> DV["dev<br/>cook debug, then cargo build"]
    CH --> BU["builder<br/>cook release, then cargo build --release"]
    PL -- "recipe.json" --> DV
    PL -- "recipe.json" --> BU
    BU -- "one binary, plus libz" --> PR["production<br/>distroless cc, nonroot"]
StageUsed byResult
plannerthe two belowrecipe.json
devjust stack dev (target: dev) and docker-compose.test.ymlA ready debug build and cargo watch -x run
testchat, socket, notification onlyDebug dependencies and the source, no build: integration tests compile once and exit
builderproductionThe release binary
productioncd-registry, just k8s build, just stack startThe image that runs

A release build, step by step

sequenceDiagram
    autonumber
    participant B as BuildKit
    participant RB as rust-base
    participant P as planner
    participant BU as builder
    participant PR as production
    B->>RB: FROM rust-base AS chef
    B->>P: COPY schemas/telemetry-schema, claims-schema, twin-schema
    B->>P: COPY backend/telemetry .
    P->>P: cargo chef prepare --recipe-path recipe.json
    B->>BU: COPY --from=planner recipe.json
    B->>BU: COPY the same three schemas again
    BU->>BU: cargo chef cook --release, dependencies only
    B->>BU: COPY backend/libs/auth-policy, auth-contracts
    B->>BU: COPY backend/telemetry .
    BU->>BU: cargo build --release
    B->>PR: FROM distroless/cc-debian12:nonroot
    PR->>PR: COPY libz.so.1 and target/release/telemetry
    PR->>PR: CMD /usr/local/bin/telemetry
StepWhat happensCached when
1Start from the shared toolchainrust-base unchanged
2–3Put the service and its schema crates where ../../schemas/... points—
4Write recipe.json: every dependency and its version, no source code—
5Only the recipe enters builder, not the sourcerecipe.json byte-identical
6The schema crates go in again: they are path dependencies, and cargo needs them on disk to cookschema files unchanged
7Compile every dependency: tokio, axum, sqlx, rdkafka…Steps 5–6 unchanged: a source edit keeps this layer
8Files read only by the service’s own code, like policy.cedar, come after the cook—
9–10Compile the service itselfNever, after a source change
11–13Copy only the binary and libz.so.1, which distroless lacks—

Example. A one-line change in src/kernel/ingest.rs:

Why the schemas are copied before each cook, not only before prepare. Each stage starts from chef, with an empty /app/schemas. prepare needs the crates to read their Cargo.toml. cook needs them again to build them. A crate missing at cook time stops the build half way, with cargo failing to read /app/schemas/<crate>/Cargo.toml.

The debug stage and sccache

dev, and debug-deps where it exists, cooks under sccache:

RUN --mount=type=cache,target=/sccache,sharing=shared \
    RUSTC_WRAPPER=sccache SCCACHE_DIR=/sccache CARGO_INCREMENTAL=0 \
    cargo chef cook --recipe-path recipe.json

Then dev runs a plain cargo build, with the same flags cargo run uses. A container then starts with nothing left to compile.

docker/rust-base

A build-only image every Rust Dockerfile starts from.

HoldsWhy
rust:${RUST_VERSION}-bookwormRUST_VERSION comes from the one pin in .mise.toml
mold, build-essentialmold links faster; a C compiler is needed because rdkafka-sys compiles librdkafka
cargo-chef 0.1.78, cargo-watch 8.5.3, sccache 0.17.0Prebuilt releases, each checked against a SHA-256 for amd64 and arm64. Compiling them in every image cost far more than downloading
RUSTFLAGS="-C link-arg=-fuse-ld=mold"Every stage that starts from it links with mold

How each builder finds it:

WhereHow FROM rust-base resolves
Composebuild.additional_contexts: rust-base: service:rust-base. docker/rust-base/docker-compose.yml declares it with scale: 0, so it is built but never run
cd-registrybuild-contexts: rust-base=docker-image://ghcr.io/<owner>/ambitwin-rust-base:<rust>-<hash>. The hash is the first 12 characters of the Dockerfile’s SHA-256, so an unchanged base is never rebuilt
Integration runnersInclude docker/rust-base/docker-compose.yml and export RUST_VERSION themselves

Go: four identical stages

tools  ->  base  ->  dev        (air, live reload)
              \->  builder  ->  production
StageWhat it does
toolsDownloads air 1.67.1, checks its SHA-256. The text is identical in all four Dockerfiles, so BuildKit builds it once
baseCopies the backend/libs/* modules the service uses, then the service, at their real repo paths. tenancy: all three. registry, provisioner: auth-contracts
devCopies air out of tools; runs air -c .air.toml
builderCGO_ENABLED=0 go build -o /out/<svc> ./cmd/<svc>: a static binary, no C library needed
productiondistroless/static-debian12:nonroot, the binary, and for tenancy and registry the migrations/ folder

The libraries keep their real paths because each service’s go.mod replaces them with ../libs/....


Python

ImageStagesHow dependencies are installedStart command
agentbuilder, productionuv pip install --system --prefix /install ., then the folder is copied into /usr/localalembic upgrade head && uvicorn app.main:app
aq-simulator, ap-simulatoroneuv sync --locked --no-dev: exactly what uv.lock saysuvicorn api:app
ap-collectorone—python -m app --config collector.json --dry-run

Node and the frontend

ImageStagesNotes
frontendbuild-stage: npm ci, npm run build with VITE_SERVER_URL, VITE_KEYCLOAK_URL. production-stage: nginx serves dist/VITE_* values are baked in at build time: one image per URL
sensor-simulatorbuilder: build dist/. production: npm ci --omit=dev and dist/Works in /repo/simulators/sensor-simulator, two levels deep, because the lockfile links ../../tooling/eslint-config. At /app the link would point above the file system root and npm ci refuses the lockfile

nginx serves the frontend because a static site needs no Node: about 64 MB against 167 MB, and it starts at once.


User, health and size

Who runs the process

ImagesUser
Rust, Gononroot, uid 65532, from the distroless tag
Python, Node, nginxroot: no USER line

Health checks

Distroless has no shell, so no curl and no wget. Two services check themselves:

WhereCheck
telemetry, socket production["CMD", "/usr/local/bin/<svc>", "--health"]: the binary calls its own /health and exits 0 or 1
Rust dev targetscurl -sf http://localhost:3000/health: the dev image is full Debian
Go dev targetswget … http://localhost:3000/health
agentA one-line Python urllib call
KuberneteshttpGet /health probes; no command inside the image

start_interval: 2s checks every 2 s while a container starts, so the services that wait on it start as soon as it answers.

Size

Real sizes of the local dev images, from docker images:

ImageSize
ambitwin-telemetry (dev)6.17 GB
ambitwin-digital-twin (dev)6.07 GB
ambitwin-socket (dev)3.47 GB
ambitwin-rust-base2.28 GB
Each Go service (dev)1.25 GB
ambitwin-agent449 MB
ambitwin-ap-simulator291 MB

A dev image holds the whole toolchain and a debug build. The production stage keeps only the binary on distroless, so it is a small fraction of that; no production size is recorded here.


The images CI builds

Every image on GHCR is the production stage of the Dockerfiles above. A PR and master use the same Dockerfile and context, so the image does not depend on which path published it.

sequenceDiagram
    autonumber
    participant PR as Pull request
    participant D as ci-docker
    participant G as GHCR
    participant CD as cd-registry
    PR->>D: a changed service with an image
    D->>D: build the service Dockerfile, production stage
    D->>D: Trivy, OS packages, HIGH and CRITICAL
    D->>G: push :pr-headsha
    PR->>CD: merged into master
    CD->>G: is :pr-headsha there?
    alt yes
        CD->>G: Trivy again, then an exact copy tagged :latest and :sha
    else no
        CD->>CD: build the service Dockerfile, production stage
        CD->>G: Trivy, then push :latest and :sha
    end

Traps

Related: Docker Compose, Kubernetes & Istio, CI.