From faaf8ab724d9bef1b981124023153c7f0e1ebeaa Mon Sep 17 00:00:00 2001 From: Eric Fitzgerald Date: Sat, 4 Jul 2026 15:34:56 -0400 Subject: [PATCH] docs: correct dev-environment topology in CLAUDE.md The dev environment was migrated to Docker Desktop Kubernetes (#520/#521), but CLAUDE.md still described a kind cluster with the database and Redis running as containers "external to the cluster." That stale description caused a misdiagnosis when the in-cluster PostgreSQL PVC came up empty: the real data was assumed lost when it was actually stranded in the old host Docker volume the new topology no longer mounts. Update both occurrences to reflect reality: - Default CLUSTER=docker-desktop (k3s also supported) - server, PostgreSQL, Redis, and NATS all run in-cluster in the tmi-platform namespace (Deployments + StatefulSets) - PostgreSQL data persists in a Kubernetes PVC (data-postgres-0), NOT a host Docker volume; re-provisioning the PVC starts from an empty DB - With DB=oracle the database is an external managed Oracle ADB - orchestration is via scripts/devenv.py; manifests under deployments/k8s/dev// Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_01Kk9GxWS9EpazjbwBKfMpUX --- CLAUDE.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index da690622..bf84fbed 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -110,7 +110,7 @@ JWT Middleware -> Auth Context -> Resource Middleware -> Endpoint Handlers - Build: `make build-server` (creates bin/tmiserver executable) - Lint: `make lint` (runs golangci-lint) - Generate API: `make generate-api` (uses oapi-codegen with config from oapi-codegen-config.yml) -- Development: `make dev-up` (starts the full dev environment: the server runs in a local kind cluster, with DB and Redis alongside; server reachable at localhost:8080). Tear down with `make dev-down`, check status with `make dev-status`. For Oracle: `make dev-up DB=oracle`. +- Development: `make dev-up` (starts the full dev environment in a local Docker Desktop Kubernetes cluster: the server, PostgreSQL, Redis, and NATS all run in-cluster in the `tmi-platform` namespace; server reachable at localhost:8080). Tear down with `make dev-down`, check status with `make dev-status`. For Oracle: `make dev-up DB=oracle`. For k3s instead of Docker Desktop: `make dev-up CLUSTER=k3s`. - Clean all: `make clean-everything` (comprehensive cleanup of processes, containers, and files) - Health check: Use `curl http://localhost:8080/` (root endpoint) to verify server is running or check running version. **There is no /health endpoint.** - Validate AsyncAPI: `make validate-asyncapi` @@ -498,8 +498,8 @@ When working with JSON files **larger than 100KB**, use streaming approaches wit ## Development Environment - Local dev config lives in `.env.dev` (env vars) and `config-development.yaml`; `config-example.yml` (generated by `cmd/genconfig`) is the annotated template -- `make dev-up` brings up a local **kind** cluster: the TMI server runs in-cluster (deployed into kind), while the PostgreSQL/Oracle database and Redis run as containers external to the cluster. `make dev-down` tears it down (keeping db data), `make dev-status` shows status, `make dev-reset`/`make dev-nuke` provide soft/hard known-state resets. Use `make dev-up DB=oracle` for the Oracle ADB topology. -- Development scripts and the kind tooling handle cluster/container lifecycle automatically +- `make dev-up` brings up a local Kubernetes cluster (default `CLUSTER=docker-desktop`; `CLUSTER=k3s` is also supported) and deploys the full stack **in-cluster** in the `tmi-platform` namespace: the TMI server and Redis run as Deployments, while PostgreSQL and NATS run as StatefulSets. **PostgreSQL data persists in a Kubernetes PVC (`data-postgres-0`), not in a host Docker volume** — rebuilding/re-provisioning the cluster's PVC starts from an empty database. With `DB=oracle` the database is instead an external managed Oracle ADB (cloud), not in-cluster. `make dev-down` tears the deployment down (keeping db data), `make dev-status` shows status, `make dev-reset`/`make dev-nuke` provide soft/hard known-state resets. Orchestration is driven by `scripts/devenv.py`; the manifests live under `deployments/k8s/dev//`. +- The devenv tooling (`scripts/devenv.py`) handles cluster context and deployment lifecycle automatically - Server is reachable at port 8080 by default with configurable TLS support - Logs: In development and test, logs are written to `logs/tmi.log` in the project directory - **Local dev database credentials**: Postgres connection info is in `config-development.yaml` under `database.postgres.{host,port,user,password,database}` (also mirrored as `POSTGRES_*` in `.env.dev`)