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
| Command | What it does |
|---|---|
up [service] | Build and start everything, or re-create one service |
status | Containers, health of every service, ingest lag, VM disk and memory |
doctor | Checks the machine and the setup without changing anything |
urls, logs [service], build, down, restart [service] | As named; down keeps data volumes |
prune | Removes dangling images and build cache (never volumes or tagged images) |
grow-disk | Gives 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 check | Shows what the services send to the collector, without SigNoz |
signoz up|down|status|logs|install-cli|reset | Local SigNoz |
reset | Deletes the data volumes (database, Kafka, Redis, captured pages) |
Addresses
| Part | URL |
|---|---|
| Web app | http://localhost:5173 |
| Taxonomy API (also the front door for GRE) | http://localhost:8080 |
| Activity, Simulator, Profile, Recommender, Ingest | http://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,sessionsand a compactedsuppression, 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_PASSWORDand keepALLOW_PRIVATE_SOURCE_HOSTS=falseoutside local use. Never commitdeploy/.env.