docs: add HOWTO.md with build, setup, and testing instructions

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

HOWTO.md

@@ -0,0 +1,121 @@
+# HOWTO — Cameleer3 Server
+
+## Prerequisites
+
+- Java 17+
+- Maven 3.9+
+- Docker & Docker Compose
+- Access to the Gitea Maven registry (for `cameleer3-common` dependency)
+
+## Build
+
+```bash
+mvn clean compile          # compile only
+mvn clean verify           # compile + run all tests (needs Docker for integration tests)
+```
+
+## Infrastructure Setup
+
+Start ClickHouse:
+
+```bash
+docker compose up -d
+```
+
+This starts ClickHouse 25.3 and automatically runs the schema init script (`clickhouse/init/01-schema.sql`).
+
+| Service    | Port | Purpose          |
+|------------|------|------------------|
+| ClickHouse | 8123 | HTTP API (JDBC)  |
+| ClickHouse | 9000 | Native protocol  |
+
+ClickHouse credentials: `cameleer` / `cameleer_dev`, database `cameleer3`.
+
+## Run the Server
+
+```bash
+mvn clean package -DskipTests
+java -jar cameleer3-server-app/target/cameleer3-server-app-1.0-SNAPSHOT.jar
+```
+
+The server starts on **port 8081**.
+
+## API Endpoints
+
+### Ingestion (POST, returns 202 Accepted)
+
+```bash
+# Post route execution data
+curl -s -X POST http://localhost:8081/api/v1/data/executions \
+  -H "Content-Type: application/json" \
+  -H "X-Protocol-Version: 1" \
+  -d '{"agentId":"agent-1","routeId":"route-1","executionId":"exec-1","status":"COMPLETED","startTime":"2026-03-11T00:00:00Z","endTime":"2026-03-11T00:00:01Z","processorExecutions":[]}'
+
+# Post route diagram
+curl -s -X POST http://localhost:8081/api/v1/data/diagrams \
+  -H "Content-Type: application/json" \
+  -H "X-Protocol-Version: 1" \
+  -d '{"agentId":"agent-1","routeId":"route-1","version":1,"nodes":[],"edges":[]}'
+
+# Post agent metrics
+curl -s -X POST http://localhost:8081/api/v1/data/metrics \
+  -H "Content-Type: application/json" \
+  -H "X-Protocol-Version: 1" \
+  -d '[{"agentId":"agent-1","metricName":"cpu","value":42.0,"timestamp":"2026-03-11T00:00:00Z","tags":{}}]'
+```
+
+**Note:** The `X-Protocol-Version: 1` header is required on all `/api/v1/data/**` endpoints. Missing or wrong version returns 400.
+
+### Health & Docs
+
+```bash
+# Health check
+curl -s http://localhost:8081/api/v1/health
+
+# OpenAPI JSON
+curl -s http://localhost:8081/api/v1/api-docs
+
+# Swagger UI
+open http://localhost:8081/api/v1/swagger-ui.html
+```
+
+### Backpressure
+
+When the write buffer is full (default capacity: 50,000), ingestion endpoints return **503 Service Unavailable**. Already-buffered data is not lost.
+
+## Configuration
+
+Key settings in `cameleer3-server-app/src/main/resources/application.yml`:
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `server.port` | 8081 | Server port |
+| `ingestion.buffer-capacity` | 50000 | Max items in write buffer |
+| `ingestion.batch-size` | 5000 | Items per ClickHouse batch insert |
+| `ingestion.flush-interval-ms` | 1000 | Buffer flush interval (ms) |
+| `ingestion.data-ttl-days` | 30 | ClickHouse TTL for auto-deletion |
+
+## Running Tests
+
+Integration tests use Testcontainers (starts ClickHouse automatically — requires Docker):
+
+```bash
+# All tests
+mvn verify
+
+# Unit tests only (no Docker needed)
+mvn test -pl cameleer3-server-core
+
+# Specific integration test
+mvn test -pl cameleer3-server-app -Dtest=ExecutionControllerIT
+```
+
+## Verify ClickHouse Data
+
+After posting data and waiting for the flush interval (1s default):
+
+```bash
+docker exec -it cameleer3-server-clickhouse-1 clickhouse-client \
+  --user cameleer --password cameleer_dev -d cameleer3 \
+  -q "SELECT count() FROM route_executions"
+```