/

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

Run the Application

Keywords on this page
WordMeaningExample
StackEvery container of Ambitwin running together on one machineCaddy, Redis, Kafka, the services
WatchCompose copies a saved file into the running container, or rebuilds itEdit src/main.rs, telemetry restarts
Runtime filecompose.runtime.yml, written at each start, listing the compose files keptThe input of every just stack and just db recipe
ExcludeA word that leaves out every folder or service whose name contains itsimulator
DetachedContainers run in the background; the terminal is freejust stack start

How to start, look at, reset and stop Ambitwin on one machine, and on the local cluster. First-time setup comes before: Setting Up the Environment. How Compose is wired: Docker Compose.


Start and stop

CommandRunsFiles usedTerminal
just stack devEverything, with watcheach docker-compose.yml plus each docker-compose.dev.ymlStays attached
just stack startEverything, rebuilt, no watcheach docker-compose.yml onlyDetached
just stack downStops and removes every container, ignoring any exclusionthe last runtime fileReturns
just stack logs [service]Follows the logs, all or onethe last runtime fileStays attached

Both dev and start run just stack env first. What just stack dev does, step by step: Docker Compose.

The dev files add, per service: the watch rules, a database port on the host, and a web page to browse the database.


Leaving parts out

Flag or wordLeaves out
--no-agentThe backend/agent folder: agent, agent-db and Langfuse
--no-metricsprometheus, grafana
--no-simulatorssensor-simulator, aq-simulator, ap-simulator
--no-devicesap-collector
Any bare wordEvery folder and service whose name contains it
--buildNothing: rebuilds the images first
--dry-runNothing: prints the docker compose command and stops

Example. just stack dev --no-simulators frontend:

A mistyped word is silent

A mistyped flag stops the run: unrecognized arguments: --no-metrcs. A mistyped word matches nothing, and every service starts. --dry-run shows the list before anything starts.


Addresses

PageAddressWhen
Frontendhttp://localhost:8080Always
Edge, every APIhttp://localhostAlways
Keycloak, sign-in and admin consolehttp://localhost:8090Always
Langfusehttp://localhost:3030, or http://localhost/langfuse, which redirects thereWithout --no-agent
Grafanahttp://localhost/grafana/Without --no-metrics
Prometheushttp://localhost/prometheus/Without --no-metrics
digital-twin database, Mongo Expresshttp://localhost/twin-db-gui/dev only
telemetry database, pgwebhttp://localhost/telemetry-db-gui/dev only
notification database, Mongo Expresshttp://localhost/notification-db-gui/dev only
dashboard database, Mongo Expresshttp://localhost/dashboard-db-gui/dev only
chat database, Mongo Expresshttp://localhost/chat-db-gui/dev only
Simulatorslocalhost:3001 sensor, :3002 air quality, :3003 routersWithout --no-simulators

Every database port on the host: Docker Compose.


Resetting data

CommandDoes
just db clearDrops the chat, digital-twin and notification databases. Empties the agent’s documents and chunks
just db clear-telemetryEmpties the telemetry tables: readings, thresholds, sensors, rooms, buildings

The local cluster

First creation: Setting Up the Environment. Everything else: Kubernetes & Istio.

Running a local change in the cluster

sequenceDiagram
    autonumber
    participant D as developer
    participant Dk as docker
    participant K3 as k3d
    participant K as kubectl
    D->>Dk: docker build, tag ghcr.io/nickghignatti/ambitwin-twin:latest
    D->>K3: just k8s load
    K3-->>K3: images copied into the cluster nodes
    D->>K: just k8s restart digital-twin
    K-->>D: new pod with the new image
    D->>K: just k8s rollout digital-twin
    K-->>D: rollout finished
StepCommand
1docker build -t ghcr.io/nickghignatti/ambitwin-twin:latest -f backend/digital-twin/Dockerfile .
2just k8s load: imports all twelve images, so each must exist locally
4just k8s restart digital-twin
6just k8s rollout digital-twin

Day to day

CommandDoes
just k8s stopPauses the cluster. Pods, volumes and secrets stay
just k8s startResumes it
just k8s statusLists pods, deployments, services, StatefulSets
just k8s logs digital-twinFollows one service’s logs
just k8s applyApplies every manifest again. Safe to repeat
just k8s restart-allRestarts every deployment, after a secret changes
just k8s deleteDeletes the ambitwin namespace and all its data. The cluster stays
k3d cluster delete ambitwinDeletes the cluster itself

When something goes wrong

What is seenCauseFix
502 from localhostCaddy reached a service that is not listening yet, or crashedjust stack logs <service>. A Rust service compiles for minutes on the first start
A left-out service starts anywayThe word was mistyped--dry-run, or the flag
compose.runtime.yml not foundNo just stack run started this stackStart it with just stack dev
A new variable is empty.env predates itjust stack env: it adds only what is missing
just k8s secrets: namespaces not foundThe namespace does not exist yetkubectl apply -f k8s/namespace.yml, then again
Pods in ImagePullBackOffThe cluster tries to pull an image it does not haveBuild it, then just k8s load
Windows: kubectl cannot connect after just k8s startThe load balancer came back on another portdocker ps --filter name=k3d-ambitwin-serverlb, then kubectl config set-cluster k3d-ambitwin --server=https://127.0.0.1:<port>
Sign-in fails in the clusterKeycloak is not deployed therePoint claims-gateway at a reachable Keycloak

Other commands

ForPage
Tests, one service or allTesting Tools
Lint and formatLinting & Formatting
Lockfiles and security checksDependencies & Security
Every recipeBuild System, or just with no argument
This sitejust docs build
Loading the docs into the assistantjust agent ingest, after editing documentation/

Gaps