7780e8e5f6
Some checks failed
CI / build (push) Failing after 4s
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
122 lines
3.4 KiB
Markdown
122 lines
3.4 KiB
Markdown
# 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"
|
|
```
|