Run the Application

CrowdVision can be run in two distinct modes: Docker Compose for everyday local development, and Kubernetes for production-like environments. Both modes are managed via just recipes from the monorepo root.

Docker Compose Mode

Development (Hot-Reloading)

For active development with live code reloading, use:

just stack dev

What happens:

1. just stack env runs first to verify your .env and generate any missing keys (see Setting Up the Environment for the full list of what it generates).
2. A runtime compose file is generated that includes all service compose files.
3. Docker Compose launches with --watch — saving a file triggers an instant hot-reload inside the running container.
4. All services start: Caddy proxy, Redis, Keycloak, every service’s own database (MongoDB or Postgres, depending on the service), all backend microservices, and the Vue frontend.

Excluding Services

Run a lighter stack by excluding services you are not working on:

# Named flags for the common groups:
just stack dev --no-simulators
just stack dev --no-agent --no-metrics

# Raw substring for anything without a flag:
just stack dev frontend

# Combine them:
just stack dev --no-simulators frontend

# See what would run, without running it:
just stack dev --no-agent --dry-run

Accessing the Application (Docker mode)

Production / Detached Mode

just stack start

Runs the stack using the base compose configuration in detached mode (-d). No hot-reloading, no database GUIs. Same exclude= syntax works here too.

Stopping & Resetting

# Graceful shutdown — stops all containers and removes orphans:
just stack down

# Follow logs for all services:
just stack logs

# Follow logs for one service:
just stack logs digital-twin

# Drop the chat, twin, notification and agent databases (destructive):
just db clear

# Truncate only the telemetry tables:
just db clear-telemetry

Bootstrapping (First-Time Provisioning)

Login and registration are Keycloak’s hosted UI now — there is no seed script for an admin account. To bootstrap a fresh stack: register through the frontend’s normal sign-in flow (redirects to Keycloak), then create your own domain through the Domains page (POST /tenancy/domains); the creator automatically becomes that domain’s business_admin. The old scripts/ops/provision.js (which called auth-service’s /business/register) has been removed along with auth-service — enterprise self-registration has no current equivalent, see Identity & Tenancy Architecture.

Kubernetes Mode

See the Kubernetes Configuration page for the full reference. Quick summary:

First Time: Creating the Cluster

just k8s create

See Kubernetes Configuration for exactly what this creates and why (single-server k3d, Traefik disabled — Istio’s Gateway API is the local ingress path instead).

Deploying (Production images from GHCR)

# First-time full setup (create cluster → Gateway API + Istio → namespace → secrets → manifests):
just k8s setup

# Subsequent deploys — re-apply manifests:
just k8s apply

Deploying with Locally Built Images (k3d dev)

just k8s build      # build all images locally
just k8s load       # import into k3d — no GHCR needed
just k8s apply      # apply manifests

Updating a Single Service

# After code changes — rebuild the image, then rolling restart:
docker build -t ghcr.io/nickghignatti/crowdvision-twin:latest -f backend/digital-twin/Dockerfile .
just k8s load
just k8s restart digital-twin

# Watch the rollout:
just k8s rollout digital-twin

Managing Cluster Lifecycle

# Pause the cluster (preserves all pods, volumes, and secrets):
just k8s stop

# Resume from exactly where you left off (~30 seconds):
just k8s start

# Verify everything came back up:
just k8s status

# Destroy the cluster completely (data is permanently lost):
just k8s delete

Verifying Cluster Health

# All pods should show 1/1 Running:
just k8s status

# Check persistent volumes are Bound:
kubectl get pvc -n crowdvision

# Check the Gateway and its routes are accepted (there is no Ingress — Istio's
# Gateway API is the only k8s ingress path):
kubectl get gateway,httproute -n crowdvision

# Tail logs for a service:
just k8s logs digital-twin

# Describe a pod for detailed events (useful for debugging):
kubectl describe pod <pod-name> -n crowdvision

Testing

# Run all unit tests across all services (moon caches results — unchanged services are instant):
just test all

# Run only tests for services touched by your current branch:
just test affected

# Per-service unit tests:
just test chat
just test twin
just test telemetry
just test notification
just test socket
just test frontend
just test agent

# Agent-only Python integration suite (separate from the backend integration tests below):
just test agent-integration

# Full backend integration tests (spins up a composed stack, then tears it down):
just test integration

Auditing & Dependency Checks

Two recipes run a security audit and a lockfile-sync check across every project. Both delegate to moon (moon run :audit / :deps), so they are cached and accept --affected to scope to the projects changed on your branch. See The Toolchain: mise & moon for how these tasks are defined.

# Security audit — npm audit (--audit-level=high --omit=dev) + uv audit + cargo audit:
just setup audit

# Lockfile-sync check — npm ci + uv sync --locked + cargo check:
just setup deps-check

# Scope either to only the projects changed on your branch:
mise exec -- moon run :audit --affected

Full Just Reference — Docker Compose

Debugging Tips

A service is responding with 502 Bad Gateway

The Caddy proxy forwards to the service container but nothing is listening. Most common causes:

1. The dev script in package.json points to a non-existent file. Every Node.js/TypeScript service must reference src/index.ts via ts-node/esm, not a compiled .js file. Check the service’s package.json:

# Correct pattern (all TypeScript services):
"dev": "nodemon --watch src --exec node --no-warnings=ExperimentalWarning --loader ts-node/esm src/index.ts"

If it says src/index.js and that file does not exist, nodemon exits silently and the service never starts — manifesting as 502.

2. Environment variable is empty or wrong. Open the service logs: just stack logs <service-name>. Look for connection errors to MongoDB or Redis at startup.

3. Missing .env variable. Run just stack env to fill any gaps. The script skips variables already present, so it is safe to re-run.

A service is starting that I asked to exclude

Check the spelling first — a mistyped flag is rejected outright (unrecognized arguments: --no-metrcs), but a mistyped raw substring matches nothing and is silently ignored. Prefer the flags where one exists:

just stack dev --no-simulators           # skips aq-simulator and sensor-simulator
just stack dev --no-simulators frontend  # also skips the Vue frontend
just stack dev --no-agent --dry-run      # confirm the service list before starting

down and build deliberately ignore all exclusions and operate on the full set.

If exclusion stops working after editing the Justfile: the dev, start, and down recipes must keep their variadic *args parameter, which is what forwards flags through to compose-run.py.

Windows: kubectl fails to connect after just k8s start

After a cluster restart the kubeconfig may point to a stale port. Fix it:

# Find the actual port the k3d load balancer is using:
docker ps --filter name=k3d-crowdvision-serverlb
# Look for the port mapped to 6443 in the PORTS column, e.g. 0.0.0.0:32774->6443/tcp

# Update the kubeconfig to use the correct port:
kubectl config set-cluster k3d-crowdvision --server=https://127.0.0.1:<PORT>

just k8s secrets fails: “namespaces not found”

Secrets are scoped to the crowdvision namespace — it must exist first. Create it manually:

kubectl apply -f k8s/namespace.yml
just k8s secrets

Or use just k8s setup which handles the ordering automatically.

k3d image pull fails (ImagePullBackOff)

If pods are stuck in ImagePullBackOff, Kubernetes is trying to pull from GHCR instead of using the locally loaded image.

# Load images from your local Docker daemon into k3d:
just k8s build
just k8s load

Also check that the deployment manifest sets imagePullPolicy: IfNotPresent, not Always — Always forces a remote pull even when the image exists locally.