From 9b1643c1ee3831d2e9e0d462fc4ce6cef33be331 Mon Sep 17 00:00:00 2001
From: hsiegeln <37154749+hsiegeln@users.noreply.github.com>
Date: Sat, 4 Apr 2026 21:06:05 +0200
Subject: [PATCH] docs: update HOWTO with observability dashboard, routing, and
 agent status

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 HOWTO.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/HOWTO.md b/HOWTO.md
index 8bf7a80..7398635 100644
--- a/HOWTO.md
+++ b/HOWTO.md
@@ -62,6 +62,7 @@ Edit `.env` and set at minimum:
 # Change in production
 POSTGRES_PASSWORD=<strong-password>
 CAMELEER_AUTH_TOKEN=<random-string-for-agent-bootstrap>
+CAMELEER_TENANT_SLUG=<your-tenant-slug>   # e.g., "acme" — tags all observability data
 
 # Logto M2M credentials (get from Logto admin console after first boot)
 LOGTO_M2M_CLIENT_ID=
@@ -185,6 +186,46 @@ curl -X POST "http://localhost:8080/api/apps/$APP_ID/stop" \
   -H "Authorization: Bearer $TOKEN"
 ```
 
+### Enable Inbound HTTP Routing
+
+If your Camel app exposes a REST endpoint, you can make it reachable from outside the stack:
+
+```bash
+# Set the port your app listens on (e.g., 8080 for Spring Boot)
+curl -X PATCH "http://localhost:8080/api/environments/$ENV_ID/apps/$APP_ID/routing" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"exposedPort": 8080}'
+```
+
+Your app is now reachable at `http://{app-slug}.{env-slug}.{tenant-slug}.{domain}` (e.g., `http://order-service.default.my-company.localhost`). Traefik routes traffic automatically.
+
+To disable routing, set `exposedPort` to `null`.
+
+### View the Observability Dashboard
+
+The cameleer3-server React SPA dashboard is available at:
+
+```
+http://localhost/dashboard
+```
+
+This shows execution traces, route topology graphs, metrics, and logs for all deployed apps. Authentication is required (Logto OIDC token via forward-auth).
+
+### Check Agent & Observability Status
+
+```bash
+# Is the agent registered with cameleer3-server?
+curl "http://localhost:8080/api/apps/$APP_ID/agent-status" \
+  -H "Authorization: Bearer $TOKEN"
+# Returns: registered, state (ACTIVE/STALE/DEAD/UNKNOWN), routeIds
+
+# Is the app producing observability data?
+curl "http://localhost:8080/api/apps/$APP_ID/observability-status" \
+  -H "Authorization: Bearer $TOKEN"
+# Returns: hasTraces, lastTraceAt, traceCount24h
+```
+
 ## API Reference
 
 ### Tenants
@@ -216,6 +257,7 @@ curl -X POST "http://localhost:8080/api/apps/$APP_ID/stop" \
 | GET | `/api/environments/{eid}/apps` | List apps |
 | GET | `/api/environments/{eid}/apps/{aid}` | Get app |
 | PUT | `/api/environments/{eid}/apps/{aid}/jar` | Re-upload JAR |
+| PATCH | `/api/environments/{eid}/apps/{aid}/routing` | Set/clear exposed port |
 | DELETE | `/api/environments/{eid}/apps/{aid}` | Delete app |
 
 ### Deployments
@@ -234,6 +276,17 @@ curl -X POST "http://localhost:8080/api/apps/$APP_ID/stop" \
 
 Query params: `since`, `until` (ISO timestamps), `limit` (default 500), `stream` (stdout/stderr/both)
 
+### Observability
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/apps/{aid}/agent-status` | Agent registration status |
+| GET | `/api/apps/{aid}/observability-status` | Trace/metrics data health |
+
+### Dashboard
+| Path | Description |
+|------|-------------|
+| `/dashboard` | cameleer3-server observability dashboard (forward-auth protected) |
+
 ### Health
 | Method | Path | Description |
 |--------|------|-------------|