From 849265a1c65c657c4b39845f91c1b08cb9978a24 Mon Sep 17 00:00:00 2001 From: hsiegeln <37154749+hsiegeln@users.noreply.github.com> Date: Tue, 21 Apr 2026 19:41:30 +0200 Subject: [PATCH] docs(howto): brand-new local environment via docker-compose MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rewrite the "Infrastructure Setup" / "Run the Server" sections to reflect what docker-compose.yml actually provides (full stack — PostgreSQL + ClickHouse + server + UI — not just PostgreSQL). Adds: - Step-by-step walkthrough for a first-run clean environment. - Port map including the UI (8080), ClickHouse (8123/9000), PG (5432), server (8081). - Dev credentials baked into compose surfaced in one place. - Lifecycle commands (stop/start/rebuild-single-service/wipe). - Infra-only mode for backend-via-mvn / UI-via-vite iteration. Co-Authored-By: Claude Opus 4.7 (1M context) --- HOWTO.md | 93 ++++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 77 insertions(+), 16 deletions(-) diff --git a/HOWTO.md b/HOWTO.md index fce321b0..6a342e11 100644 --- a/HOWTO.md +++ b/HOWTO.md @@ -19,38 +19,99 @@ mvn clean compile # compile only mvn clean verify # compile + run all tests (needs Docker for integration tests) ``` -## Infrastructure Setup +## Start a brand-new local environment (Docker) -Start PostgreSQL: +The repo ships a `docker-compose.yml` with the full stack: PostgreSQL, ClickHouse, the Spring Boot server, and the nginx-served SPA. All dev defaults are baked into the compose file — no `.env` file or extra config needed for a first run. ```bash +# 1. Clean slate (safe if this is already a first run — noop when no volumes exist) +docker compose down -v + +# 2. Build + start everything. First run rebuilds both images (~2–4 min). +docker compose up -d --build + +# 3. Watch the server come up (health check goes green in ~60–90s after Flyway + ClickHouse init) +docker compose logs -f cameleer-server +# ready when you see "Started CameleerServerApplication in ...". +# Ctrl+C when ready — containers keep running. + +# 4. Smoke test +curl -s http://localhost:8081/api/v1/health # → {"status":"UP"} +``` + +Open the UI at **http://localhost:8080** (nginx) and log in with **admin / admin**. + +| Service | Host port | URL / notes | +|------------|-----------|-------------| +| Web UI (nginx) | 8080 | http://localhost:8080 — proxies `/api` to the server | +| Server API | 8081 | http://localhost:8081/api/v1/health, http://localhost:8081/api/v1/swagger-ui.html | +| PostgreSQL | 5432 | user `cameleer`, password `cameleer_dev`, db `cameleer` | +| ClickHouse | 8123 (HTTP), 9000 (native) | user `default`, no password, db `cameleer` | + +**Dev credentials baked into compose (do not use in production):** + +| Purpose | Value | +|---|---| +| UI login | `admin` / `admin` | +| Bootstrap token (agent registration) | `dev-bootstrap-token-for-local-agent-registration` | +| JWT secret | `dev-jwt-secret-32-bytes-min-0123456789abcdef0123456789abcdef` | +| `CAMELEER_SERVER_RUNTIME_ENABLED` | `false` (Docker-in-Docker app orchestration off for the local stack) | + +Override any of these by editing `docker-compose.yml` or passing `-e KEY=value` to `docker compose run`. + +### Common lifecycle commands + +```bash +# Stop everything but keep volumes (quick restart later) +docker compose stop + +# Start again after a stop +docker compose start + +# Apply changes to the server code / UI — rebuild just what changed +docker compose up -d --build cameleer-server +docker compose up -d --build cameleer-ui + +# Wipe the environment completely (drops PG + ClickHouse volumes — all data gone) +docker compose down -v + +# Fresh Flyway run by dropping just the PG volume (keeps ClickHouse data) +docker compose down +docker volume rm cameleer-server_cameleer-pgdata docker compose up -d ``` -This starts PostgreSQL 16. The database schema is applied automatically via Flyway migrations on server startup. ClickHouse tables are created by the schema initializer on startup. +### Infra-only mode (backend via `mvn` / UI via Vite) -| Service | Port | Purpose | -|------------|------|----------------------| -| PostgreSQL | 5432 | JDBC (Spring JDBC) | - -PostgreSQL credentials: `cameleer` / `cameleer_dev`, database `cameleer`. - -## Run the Server +If you want to iterate on backend/UI code without rebuilding the server image on every change, start just the databases and run the server + UI locally: ```bash +# 1. Only infra containers +docker compose up -d cameleer-postgres cameleer-clickhouse + +# 2. Build and run the server jar against those containers mvn clean package -DskipTests -SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/cameleer \ +SPRING_DATASOURCE_URL="jdbc:postgresql://localhost:5432/cameleer?currentSchema=tenant_default&ApplicationName=tenant_default" \ SPRING_DATASOURCE_USERNAME=cameleer \ SPRING_DATASOURCE_PASSWORD=cameleer_dev \ -CAMELEER_SERVER_SECURITY_BOOTSTRAPTOKEN=my-secret-token \ +SPRING_FLYWAY_USER=cameleer \ +SPRING_FLYWAY_PASSWORD=cameleer_dev \ +CAMELEER_SERVER_CLICKHOUSE_URL="jdbc:clickhouse://localhost:8123/cameleer" \ +CAMELEER_SERVER_CLICKHOUSE_USERNAME=default \ +CAMELEER_SERVER_CLICKHOUSE_PASSWORD= \ +CAMELEER_SERVER_SECURITY_BOOTSTRAPTOKEN=dev-bootstrap-token-for-local-agent-registration \ +CAMELEER_SERVER_SECURITY_JWTSECRET=dev-jwt-secret-32-bytes-min-0123456789abcdef0123456789abcdef \ +CAMELEER_SERVER_RUNTIME_ENABLED=false \ +CAMELEER_SERVER_TENANT_ID=default \ java -jar cameleer-server-app/target/cameleer-server-app-1.0-SNAPSHOT.jar + +# 3. In another terminal — Vite dev server on :5173 (proxies /api → :8081) +cd ui && npm install && npm run dev ``` -> **Note:** The Docker image no longer includes default database credentials. When running via `docker run`, pass `-e SPRING_DATASOURCE_URL=...` etc. The docker-compose setup provides these automatically. +Database schema is applied automatically: PostgreSQL via Flyway migrations on server startup, ClickHouse tables via `ClickHouseSchemaInitializer`. No manual DDL needed. -The server starts on **port 8081**. The `CAMELEER_SERVER_SECURITY_BOOTSTRAPTOKEN` environment variable is **required** — the server fails fast on startup if it is not set. - -For token rotation without downtime, set `CAMELEER_SERVER_SECURITY_BOOTSTRAPTOKENPREVIOUS` to the old token while rolling out the new one. The server accepts both during the overlap window. +`CAMELEER_SERVER_SECURITY_BOOTSTRAPTOKEN` is **required** for agent registration — the server fails fast on startup if it's not set. For token rotation without downtime, set `CAMELEER_SERVER_SECURITY_BOOTSTRAPTOKENPREVIOUS` to the old token while rolling out the new one — the server accepts both during the overlap window. ## API Endpoints