Local Development

Iterate on your solution locally with hot reload, mocked platform services, and fast feedback before deploying to the cluster.

Local Development

This page covers three local-dev modes — choose based on what you’re iterating on. The Quickstart uses Kind; this page also covers the docker-compose loop (faster) and port-forward to a shared dev cluster (slowest, but real platform).

Pick a mode

Mode	Use when	Setup time	Iteration time
docker-compose	Iterating on your service code only; platform services can be mocked or stubbed	~2 min	<5s (hot reload)
Kind	You need a real Kubernetes context (probes, configmaps, ingress)	~5 min	~30s per redeploy
Port-forward to shared dev cluster	You need real platform services (real identity/authorization services, real Connections)	<1 min	~30s per redeploy

Most loops are docker-compose. Move to Kind for the integration-test pass. Use the shared dev cluster only when you need cross-service coordination.

Mode 1: docker-compose with hot reload

This is the daily-driver loop. Your service runs on the host with uvicorn --reload; supporting services (Postgres for your DB, MinIO for shared storage, a local identity provider) run in containers.

1. Write the compose file

   docker-compose.yaml

   services:
     postgres:
       image: postgres:17-alpine
       environment:
         POSTGRES_USER: dev
         POSTGRES_PASSWORD: dev
         POSTGRES_DB: hello_solution
       ports: ["5432:5432"]
       healthcheck:
         test: ["CMD-SHELL", "pg_isready -U dev"]
         interval: 2s
         retries: 20
   
     minio:
       image: minio/minio:latest
       command: server /data --console-address ":9001"
       environment:
         MINIO_ROOT_USER: minioadmin
         MINIO_ROOT_PASSWORD: minioadmin
       ports: ["9000:9000", "9001:9001"]
       healthcheck:
         test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/ready"]
         interval: 2s
         retries: 20
   
     # Local identity provider for JWT validation. Uses the platform's standard
     # dev image so JWKS endpoints behave realistically.
     keycloak:
       image: quay.io/keycloak/keycloak:26.0
       command: ["start-dev"]
       environment:
         KEYCLOAK_ADMIN: admin
         KEYCLOAK_ADMIN_PASSWORD: admin
       ports: ["8080:8080"]
   
2. Write a .env.example

   .env.example

   # Database (matches docker-compose service)
   DATABASE_URL=postgresql+asyncpg://dev:dev@localhost:5432/hello_solution
   
   # Object storage (MinIO with path-style addressing)
   OBSTORE_ENDPOINT=http://localhost:9000
   OBSTORE_ACCESS_KEY=minioadmin
   OBSTORE_SECRET_KEY=minioadmin
   OBSTORE_BUCKET=hello-solution
   OBSTORE_PATH_STYLE=true
   
   # Auth (point at the local identity provider realm you create with the bootstrap below)
   KEYCLOAK_ISSUER_URL=http://localhost:8080/realms/dev
   KEYCLOAK_AUDIENCE=hello-solution-api
   
   # LLM gateway (set to a real LiteLLM gateway URL in dev/stg/prod;
   # for local-only loops you can stub the LLM client)
   LLM_GATEWAY_URL=http://localhost:4000
   LLM_GATEWAY_API_KEY=local-dev-key
   LLM_DEFAULT_MODEL=gpt-4o-mini
   

   Copy to .env (which should be in .gitignore) before running.

3. Boot supporting services and run your app with hot reload

   docker compose up -d
   docker compose ps  # confirm all healthy
   
   # Pre-create the MinIO bucket
   docker run --rm --network host minio/mc \
     sh -c "mc alias set local http://localhost:9000 minioadmin minioadmin && mc mb -p local/hello-solution"
   
   # Run your service with hot reload
   set -a; source .env; set +a
   uv run uvicorn api.main:app --host 0.0.0.0 --port 8000 --reload
   

   Editing packages/api/src/api/*.py reloads the server inside ~1 second. Hit http://localhost:8000/echo?msg=hi to confirm.

4. Tear down

   docker compose down -v   # -v also removes the named volumes
   

Mode 2: Kind cluster

Use Kind when you need real Kubernetes semantics (probes firing, ConfigMaps mounting, Ingress routing). The Quickstart walks through this end-to-end. Make iteration faster with this rebuild-and-load script:

kind-load.sh

#!/usr/bin/env bash
set -euo pipefail

CLUSTER="${1:-hello-solution}"
TAG="${2:-dev}"

docker build -t hello-solution-api:$TAG .
kind load docker-image hello-solution-api:$TAG --name $CLUSTER

# Trigger a rolling restart (image pull policy IfNotPresent + same tag won't redeploy)
kubectl -n em-hello-solution rollout restart deployment/hello-solution-api
kubectl -n em-hello-solution rollout status deployment/hello-solution-api

Run ./kind-load.sh after each code change. ~30 seconds per cycle.

Mode 3: Port-forward to shared dev cluster

Use this when you need real platform behavior — real identity provider realms, real authorization data, real Connections. Run your code locally and forward platform services from a shared dev cluster.

# Connect to your shared dev cluster (context provisioned out of band by your platform team)
kubectl config use-context <your-dev-cluster-context>

# Port-forward platform services to localhost
kubectl -n em-runtime port-forward svc/em-runtime-governance 8001:8001 &
kubectl -n em-runtime port-forward svc/em-runtime-assets    8002:8002 &
kubectl -n em-runtime port-forward svc/em-runtime-utils     8003:8003 &
kubectl -n em-runtime port-forward svc/keycloak             8080:8080 &

# Run your service against them
set -a; source .env.dev; set +a
uv run uvicorn api.main:app --reload

Useful pitfall to know about: when port-forward drops (any error in the cluster), curl from your service will fail until you restart the forward. Wrap forwards in a tiny supervisor script (while true; do kubectl port-forward ... ; done) for long-running loops.

Mocking platform services

Three things are commonly mocked in unit tests:

1. JWT verification — generate a signed test token with a fixture private key; load the matching public key as KEYCLOAK_JWKS_OVERRIDE (a path to a JSON file your auth code prefers over the JWKS endpoint when set).
2. Permission checks — patch the Governance SDK’s permission method to return True (or the value under test).
3. LiteLLM gateway — point LLM_GATEWAY_URL at a stub HTTP server that returns canned completions; or use litellm’s built-in mock provider (model="mock-openai/...").

See SDKs › Python for SDK extension points and Authenticate Users for the JWT fixture pattern.

Common pitfalls

Kind: services on the cluster cannot reach localhost

Containers in Kind cannot use localhost to reach your host machine. Use host.docker.internal (macOS/Windows) or the host’s LAN IP (Linux). Or — better — run dependencies inside Kind with another helm install.

MinIO: SignatureDoesNotMatch errors

MinIO requires path-style addressing. Set OBSTORE_PATH_STYLE=true (or the equivalent in your S3 client config). Virtual-hosted style works on real S3 but not on MinIO without DNS magic.

Hot reload not picking up changes

uvicorn --reload watches the working directory by default. If your source is in a non-default location (e.g., packages/api/src/api/), pass --reload-dir packages/api/src. For container-based reload, mount the source directory as a volume and run uvicorn inside the container.

Missing X-Project-ID returning 400 from platform APIs

Every call to Governance, Assets, or Utils requires X-Project-ID. In local dev, hardcode a fixture project ID (e.g., 00000000-0000-0000-0000-000000000001) until you wire user-driven project switching.

CI smoke test

The Quickstart runs end-to-end in CI weekly via .github/workflows/quickstart-smoke.yml. The workflow provisions a Kind cluster, builds the example image, installs the chart, port-forwards, and asserts both endpoints respond. If it fails, an issue is opened automatically with the label solution-dev-guide — that is your signal to update the guide.

This is the strongest possible self-sustainability signal: the quickstart cannot rot silently.

Next steps

Authenticate users

Wire JWT validation into your local app.

Manage secrets

Move secrets out of .env into the platform pipeline.

Use shared storage

Replace MinIO test code with the obstore client.

Troubleshooting

Stuck? Check known causes by error symptom.