/

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

Setting Up the Environment

Keywords on this page
WordMeaningExample
.envOne file at the repo root holding every local setting and secretBACKEND_PORT=80
SecretA random value two parts share, so each can trust the otherINTERNAL_SIGNING_SECRET
KeycloakThe sign-in serverLogin page at localhost:8090
VAPID keysThe key pair a browser uses to accept Web Push from notificationVAPID_PUBLIC_KEY
LangfuseA web page that shows every step the assistant tooklocalhost:3030
k3dA small Kubernetes cluster that runs inside DockerCluster ambitwin

From a clean machine to a signed-in user with a first domain. How each tool works is on the Toolchain pages; this page is the order to follow.


What a machine needs

ToolWhyInstalled by
justEvery command starts with itBy hand: https://just.systems/
miseInstalls the pinned languages and CLIsBy hand: https://mise.jdx.dev/
Docker with ComposeRuns the local stack. Compose must support include: and --watchBy hand
GitClone and branchesBy hand
opensslEvery .env script makes its keys with itBy hand, most systems ship it
Node, Python, Rust, Go, moon, uv, istioctlBuild, test and lintmise, pins in .mise.toml: Build System
QuarkdownOnly for just docs buildBy hand, at QUARKDOWN_VERSION from .mise.toml
k3d, kubectlOnly for the local clusterBy hand

Install

git clone https://github.com/NickGhignatti/ambitwin.git
cd ambitwin
just setup install
sequenceDiagram
    autonumber
    participant D as developer
    participant J as just
    participant M as mise
    participant Mo as moon
    participant L as npm, uv, cargo, go
    D->>J: just setup install
    J->>M: mise install
    M-->>J: pinned tools ready
    J->>Mo: moon run :deps
    Mo->>L: one deps task per project, in parallel
    L-->>D: libraries installed, lockfiles untouched
StepWhat happens
2mise downloads each tool in .mise.toml that is missing
4moon reads .moon/workspace.yml and starts every project’s deps task
5Node: npm ci. Python: uv sync --locked. Rust: cargo fetch. Go: go mod download

The .env file

just stack env

Eleven POSIX sh scripts in scripts/env/ run in order. Each one writes only a value missing from .env, so a second run changes nothing. just stack dev and just stack start run it first anyway.

ScriptWritesUsed by
create.shAn empty .env, if none existsevery other script
vapid.shVAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY, VITE_VAPID_PUBLIC_KEYnotification, frontend
token.shEVAL_JWT_SECRET, 256-bit hexagent evaluation runs
config.shBACKEND_PORT (80), FRONTEND_PORT (8080), DEV_URL (http://localhost), and asks for OPENROUTER_API_KEYCaddy, frontend, agent
langfuse.shLangfuse keys, its first-boot admin, the agent’s trace exporter settingsLangfuse, agent
keycloak.shKEYCLOAK_ADMIN_USER (admin), KEYCLOAK_ADMIN_PASSWORD, KEYCLOAK_DB_PASSWORD, empty GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRETKeycloak
controlplane.shINTERNAL_SIGNING_SECRET, TENANCY_DB_PASSWORD, REGISTRY_DB_PASSWORDthe four Go services
gateway-key.shA 2048-bit RSA key in secrets/gateway-dev-key.pem, not in .envclaims-gateway
ingest-key.shTELEMETRY_DEVICE_MASTER_KEY, TELEMETRY_INGEST_SECRETtelemetry, simulators, ap-collector
telemetry-db.shTELEMETRY_DB_PASSWORDthe cluster only: Compose uses the fixed password telemetry
rust.shRUST_VERSION, copied from .mise.tomlthe rust-base image build

What some of these values mean:

Example: a new key. A teammate loses their VAPID keys:

sed -i '/^VAPID_\|^VITE_VAPID_/d' .env   # drop the three lines
sh scripts/env/vapid.sh                  # one script writes them again

ENV_FILE=/path/to/other.env makes every script write to another file.


First start and first login

just stack dev
sequenceDiagram
    autonumber
    participant D as developer
    participant F as frontend, port 8080
    participant K as Keycloak, port 8090
    participant G as claims-gateway
    participant T as tenancy
    D->>F: open the page, sign in
    F->>K: hosted login page
    D->>K: register a new account
    K-->>F: back, with a Keycloak token
    F->>G: exchange it for the internal pass
    G-->>F: cookie, no domain yet
    D->>F: Domains page, create a domain
    F->>T: POST /tenancy/domains
    T-->>F: domain created, creator is its business_admin

A cold build loads the CPU, not memory

  • Measured on a 12-core, 16 GB laptop: just stack dev --build took 728 s, CPU pressure 88–96 % for about eight minutes, free memory never under 7.7 GB.
  • Build steps run under system.slice, so a CPUWeight on docker.slice does not slow them. sudo systemctl set-property user.slice CPUWeight=400 keeps the desktop responsive.
  • COMPOSE_PARALLEL_LIMIT has no effect: the runner always builds with COMPOSE_BAKE=true.

The local cluster, in short

The full path is on Kubernetes & Istio.

StepCommandNote
1Add 127.0.0.1 ambitwin.local to the hosts filejust k8s hosts prints the line. Linux and macOS: /etc/hosts. Windows: C:\Windows\System32\drivers\etc\hosts
2Optional: GHCR_USERNAME, GHCR_TOKEN in .envOnly for private images. The token needs read:packages
3just k8s setupk3d cluster with one server, Gateway API, Istio ambient, namespace, secrets from .env, every manifest
4Open http://ambitwin.localSame paths as Compose, Grafana included

Traps


Gaps