Skip to main content

Deployment

The whole platform runs with Podman and podman-compose from deploy/compose.yaml, driven by deploy/deploy.sh.

First start​

cp deploy/.env.example deploy/.env

Edit deploy/.env: set JWT_KEY (32+ random characters), ADMIN_PASSWORD and SERVICE_API_KEY (16+ random characters). Then:

deploy/deploy.sh up

podman-compose prints many harmless errors when it re-creates containers; they go to deploy/.logs/deploy.log, and the script checks that every container really runs.

Start order​

Services retry their dependencies at run time (ingest waits for Kafka, the catalogue cache retries every 15 seconds), so the order mostly matters for a clean first start.

Commands​

CommandWhat it does
up [service]Build and start everything, or re-create one service
statusContainers, health of every service, ingest lag, VM disk and memory
doctorChecks the machine and the setup without changing anything
urls, logs [service], build, down, restart [service]As named; down keeps data volumes
pruneRemoves dangling images and build cache (never volumes or tagged images)
grow-diskGives the Podman VM the disk it was created with but never used (asks first)
kafka-reset [--wipe]Recreates Kafka and its dependants, optionally deleting its data
telemetry checkShows what the services send to the collector, without SigNoz
signoz up|down|status|logs|install-cli|resetLocal SigNoz
resetDeletes the data volumes (database, Kafka, Redis, captured pages)

Addresses​

PartURL
Web apphttp://localhost:5173
Taxonomy API (also the front door for GRE)http://localhost:8080
Activity, Simulator, Profile, Recommender, Ingesthttp://localhost:8081 to 8085
Kafka UI (no login, local only)http://localhost:8088
SigNoz (optional)http://localhost:8180

Development without containers​

Needs the .NET 10 SDK, Node.js and Postgres with pgvector on localhost:5434.

podman-compose -f deploy/compose.yaml up -d postgres
dotnet run --project src/Kaleido.Taxonomy.Api
cd web && npm install && npm run dev

Set Auth__JwtKey and Auth__AdminPassword for the API through user secrets or environment variables.

Tests​

dotnet test

GRE integration tests skip themselves unless pointed at infrastructure: TEST_PG, TEST_REDIS=localhost:6380, TEST_KAFKA=localhost:9094. deploy/run-tests.sh and deploy/verify.sh run tests and smoke checks against the container stack.

Production notes​

  • Use the organisation's own Kafka cluster with topics transactions, sessions and a compacted suppression, keyed by customer id. Configure it as an ingestion in Settings, Kafka ingestion.
  • Kafka retention is the longest outage a consumer can recover from on its own (7 days locally).
  • Redis runs with AOF (appendfsync everysec); it is rebuildable, so back it up for recovery speed, not for correctness.
  • Change POSTGRES_PASSWORD and keep ALLOW_PRIVATE_SOURCE_HOSTS=false outside local use. Never commit deploy/.env.