From 6288084daf055b3ef7dc878241627c11d16a08ca Mon Sep 17 00:00:00 2001 From: hsiegeln <37154749+hsiegeln@users.noreply.github.com> Date: Wed, 8 Apr 2026 22:09:18 +0200 Subject: [PATCH] docs: update documentation for Docker orchestration and env var rename Co-Authored-By: Claude Sonnet 4.6 --- CLAUDE.md | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index e0c975d5..e5153df8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -64,6 +64,16 @@ java -jar cameleer3-server-app/target/cameleer3-server-app-1.0-SNAPSHOT.jar - Docker build uses buildx registry cache + `--provenance=false` for Gitea compatibility - CI: branch slug sanitization extracted to `.gitea/sanitize-branch.sh`, sourced by docker and deploy-feature jobs +## UI Structure + +The UI has 4 main tabs: **Exchanges**, **Dashboard**, **Runtime**, **Deployments**. + +- **Exchanges** — route execution search and detail +- **Dashboard** — metrics and stats +- **Runtime** — live agent status, logs (previously separate Logs tab merged here) +- **Deployments** — deployment lifecycle. Config sub-tabs: **Variables | Monitoring | Traces & Taps | Route Recording | Resources** (previously a separate Config tab, now merged into Deployments) +- **Create app** — full page at `/apps/new` (not a modal) + ## UI Styling - Always use `@cameleer/design-system` CSS variables for colors (`var(--amber)`, `var(--error)`, `var(--success)`, etc.) — never hardcode hex values. This applies to CSS modules, inline styles, and SVG `fill`/`stroke` attributes. SVG presentation attributes resolve `var()` correctly. @@ -71,6 +81,47 @@ java -jar cameleer3-server-app/target/cameleer3-server-app-1.0-SNAPSHOT.jar - Sidebar generates `/exchanges/` paths directly (no legacy `/apps/` redirects). basePath is centralized in `ui/src/config.ts`; router.tsx imports it instead of re-reading `` tag. - Global user preferences (environment selection) use Zustand stores with localStorage persistence — never URL search params. URL params are for page-specific state only (e.g. `?text=` search query). Switching environment resets all filters and remounts pages. +## Docker Orchestration + +When deployed via the cameleer-saas platform, this server orchestrates customer app containers using Docker. Key components: + +- **ConfigMerger** — merges config at three levels: global → environment → app. Lower levels override higher. Used to produce the final env var set for a deployment. +- **TraefikLabelBuilder** — generates Traefik Docker labels for path-based or subdomain-based routing to each deployed container. Two routing strategies: path prefix (`/app/{slug}`) and subdomain (`{slug}.domain`). +- **DockerNetworkManager** — manages two Docker network tiers: + - `cameleer-traefik` — shared network that Traefik joins; all routable containers attach here + - `cameleer-env-{slug}` — per-environment isolated network; containers in the same environment can reach each other and the cameleer3-server +- **DockerEventMonitor** — listens to the Docker event stream to detect container exits, OOM kills, and health state changes. Updates deployment status in real time. +- **DeploymentProgress** — tracks deploy stages and broadcasts progress events via SSE for the UI progress indicator. + +### Deployment Status Model + +Deployments move through these statuses: + +| Status | Meaning | +|--------|---------| +| `PENDING` | Queued, not started | +| `RUNNING` | Container healthy and serving | +| `DEGRADED` | Container up but health check failing or some replicas down | +| `STOPPING` | Graceful shutdown in progress | +| `STOPPED` | Intentionally stopped | +| `FAILED` | Terminal failure | + +**Replica support**: deployments can specify a replica count. `DEGRADED` is used when at least one but not all replicas are healthy. + +**Deploy stages** (`DeployStage`): BUILD → PUSH → PULL → STOP_OLD → START → HEALTH_CHECK → DONE (or FAILED at any stage). + +**Blue/green strategy**: when re-deploying, the new container is started and health-checked before the old one is stopped, minimising downtime. + +### JAR Management + +- **Retention policy** per environment: configurable maximum number of JAR versions to keep. Older JARs are deleted automatically. +- **Nightly cleanup job** (Spring `@Scheduled`): purges JARs exceeding the retention limit and removes orphaned files not referenced by any app version. +- **Volume-based JAR mounting** for Docker-in-Docker setups: set `CAMELEER_JAR_DOCKER_VOLUME` to the Docker volume name that contains the JAR storage directory. When set, the orchestrator mounts this volume into the container instead of bind-mounting the host path (required when the SaaS container itself runs inside Docker and the host path is not accessible from sibling containers). + +### nginx / Reverse Proxy + +- `client_max_body_size 200m` is required in the nginx config to allow JAR uploads up to 200 MB. Without this, large JAR uploads return 413. + ## Disabled Skills - Do NOT use any `gsd:*` skills in this project. This includes all `/gsd:` prefixed commands.