feat(demo): add complete TSYS developer support stack demo implementation

Add full demo environment with 13 services across 4 categories: - Infrastructure: Homepage, Docker Socket Proxy, Pi-hole, Portainer - Monitoring: InfluxDB, Grafana - Documentation: Draw.io, Kroki - Developer Tools: Atomic Tracker, ArchiveBox, Tube Archivist, Wakapi, MailHog, Atuin Includes: - Docker Compose templates with dynamic environment configuration - Deployment orchestration scripts with user ID detection - Comprehensive test suite (unit, integration, e2e) - Pre-deployment validation with yamllint, shellcheck - Full documentation (PRD, AGENTS, README) - Service configurations for all components All services configured for demo purposes with: - Dynamic UID/GID mapping - Docker socket proxy security - Health checks and monitoring - Service discovery via Homepage labels Ports allocated 4000-4099 range with sequential assignment. 💘 Generated with Crush Assisted-by: GLM-4.7 via Crush <crush@charm.land>
2026-01-24 10:46:29 -05:00
parent c2d8b502cc
commit 937ec852eb
19 changed files with 4393 additions and 0 deletions
--- a/demo/docs/api-docs/README.md
+++ b/demo/docs/api-docs/README.md
@@ -0,0 +1,285 @@
+# TSYS Developer Support Stack - API Documentation
+
+## Service APIs Overview
+
+This document provides API endpoint information for all services in the stack.
+
+## Infrastructure Services APIs
+
+### Docker Socket Proxy
+- **Base URL**: `http://localhost:4005`
+- **API Version**: Docker Engine API
+- **Authentication**: None (restricted by proxy)
+- **Endpoints**:
+  - `GET /version` - Docker version information
+  - `GET /info` - System information
+  - `GET /containers/json` - List containers
+  - `GET /images/json` - List images
+
+### Pi-hole
+- **Base URL**: `http://localhost:4006/admin`
+- **API Version**: v1
+- **Authentication**: Basic auth (demo_password)
+- **Endpoints**:
+  - `GET /admin/api.php` - Statistics and status
+  - `GET /admin/api.php?list` - Blocked domains list
+  - `GET /admin/api.php?summaryRaw` - Raw statistics
+
+### Portainer
+- **Base URL**: `http://localhost:4007`
+- **API Version**: v2
+- **Authentication**: Bearer token
+- **Endpoints**:
+  - `POST /api/auth` - Authentication
+  - `GET /api/endpoints` - List endpoints
+  - `GET /api/containers` - List containers
+  - `GET /api/images` - List images
+
+## Monitoring & Observability APIs
+
+### InfluxDB
+- **Base URL**: `http://localhost:4008`
+- **API Version**: v2
+- **Authentication**: Token-based
+- **Endpoints**:
+  - `GET /ping` - Health check
+  - `POST /api/v2/write` - Write data
+  - `GET /api/v2/query` - Query data
+  - `GET /api/health` - Health status
+
+### Grafana
+- **Base URL**: `http://localhost:4009`
+- **API Version**: v1
+- **Authentication**: API key or Basic auth
+- **Endpoints**:
+  - `GET /api/health` - Health check
+  - `GET /api/dashboards` - List dashboards
+  - `GET /api/datasources` - List data sources
+  - `POST /api/login` - Authentication
+
+## Documentation & Diagramming APIs
+
+### Draw.io
+- **Base URL**: `http://localhost:4010`
+- **API Version**: None (web interface)
+- **Authentication**: None
+- **Endpoints**:
+  - `GET /` - Main interface
+  - `POST /export` - Export diagram
+  - `GET /images` - Image library
+
+### Kroki
+- **Base URL**: `http://localhost:4011`
+- **API Version**: v1
+- **Authentication**: None
+- **Endpoints**:
+  - `GET /health` - Health check
+  - `POST /plantuml/svg` - PlantUML to SVG
+  - `POST /mermaid/svg` - Mermaid to SVG
+  - `POST /graphviz/svg` - GraphViz to SVG
+
+## Developer Tools APIs
+
+### Homepage
+- **Base URL**: `http://localhost:4000`
+- **API Version**: None (web interface)
+- **Authentication**: None
+- **Endpoints**:
+  - `GET /` - Main dashboard
+  - `GET /widgets` - Widget data
+  - `GET /bookmarks` - Bookmark data
+
+### Atomic Tracker
+- **Base URL**: `http://localhost:4012`
+- **API Version**: v1
+- **Authentication**: Required
+- **Endpoints**:
+  - `GET /api/habits` - List habits
+  - `POST /api/habits` - Create habit
+  - `PUT /api/habits/:id` - Update habit
+  - `DELETE /api/habits/:id` - Delete habit
+
+### ArchiveBox
+- **Base URL**: `http://localhost:4013`
+- **API Version**: v1
+- **Authentication**: Required
+- **Endpoints**:
+  - `GET /api/v1/core/health` - Health check
+  - `POST /api/v1/core/add` - Add URL
+  - `GET /api/v1/snapshots` - List snapshots
+  - `GET /api/v1/snapshots/:id` - Get snapshot
+
+### Tube Archivist
+- **Base URL**: `http://localhost:4014`
+- **API Version**: v1
+- **Authentication**: Required
+- **Endpoints**:
+  - `GET /api/health` - Health check
+  - `POST /api/subscribe` - Subscribe to channel
+  - `GET /api/video/:id` - Get video info
+  - `GET /api/search` - Search videos
+
+### Wakapi
+- **Base URL**: `http://localhost:4015`
+- **API Version**: v1
+- **Authentication**: API key
+- **Endpoints**:
+  - `GET /api/health` - Heartbeat
+  - `GET /api/summary` - Time summary
+  - `GET /api/durations` - Heartbeats
+  - `POST /api/heartbeats` - Add heartbeat
+
+### MailHog
+- **Base URL**: `http://localhost:4017`
+- **API Version**: v1
+- **Authentication**: None
+- **Endpoints**:
+  - `GET /api/v1/messages` - List messages
+  - `GET /api/v1/messages/:id` - Get message
+  - `DELETE /api/v1/messages` - Delete all
+  - `POST /api/v1/messages` - Create message
+
+### Atuin
+- **Base URL**: `http://localhost:4018`
+- **API Version**: v1
+- **Authentication**: Required
+- **Endpoints**:
+  - `GET /api/health` - Health check
+  - `POST /api/sync` - Sync history
+  - `GET /api/history` - Get history
+  - `POST /api/history` - Add history
+
+## API Usage Examples
+
+### Docker Socket Proxy Example
+```bash
+# Get Docker version
+curl http://localhost:4005/version
+
+# List containers
+curl http://localhost:4005/containers/json
+```
+
+### InfluxDB Example
+```bash
+# Write data
+curl -X POST http://localhost:4008/api/v2/write \
+  -H "Authorization: Token demo_token_replace_in_production" \
+  -H "Content-Type: text/plain" \
+  --data-binary "measurement,field=value"
+
+# Query data
+curl -G http://localhost:4008/api/v2/query \
+  -H "Authorization: Token demo_token_replace_in_production" \
+  --data-urlencode "query=from(bucket:\"demo_metrics\") |> range(start: -1h)"
+```
+
+### Grafana Example
+```bash
+# Get dashboards
+curl -u admin:demo_password http://localhost:4009/api/dashboards
+
+# Create API key
+curl -X POST -u admin:demo_password \
+  http://localhost:4009/api/auth/keys \
+  -H "Content-Type: application/json" \
+  -d '{"name":"demo","role":"Admin"}'
+```
+
+### Kroki Example
+```bash
+# Convert PlantUML to SVG
+curl -X POST http://localhost:4011/plantuml/svg \
+  -H "Content-Type: text/plain" \
+  -d "@startuml
+  Alice -> Bob: Hello
+  @enduml"
+```
+
+## Authentication
+
+### Demo Credentials
+- **Username**: `admin`
+- **Password**: `demo_password`
+- **API Keys**: Use demo tokens provided in configuration
+
+### Token-based Authentication
+```bash
+# InfluxDB token
+export INFLUX_TOKEN="demo_token_replace_in_production"
+
+# Grafana API key
+export GRAFANA_API_KEY="demo_api_key"
+
+# Wakapi API key
+export WAKAPI_API_KEY="demo_wakapi_key"
+```
+
+## Rate Limiting
+
+Most services have no rate limiting in demo mode. In production:
+- Configure appropriate rate limits
+- Implement authentication
+- Set up monitoring
+- Use reverse proxy for additional security
+
+## Error Handling
+
+### Common HTTP Status Codes
+- `200` - Success
+- `401` - Authentication required
+- `403` - Forbidden
+- `404` - Not found
+- `500` - Internal server error
+
+### Error Response Format
+```json
+{
+  "error": "Error message",
+  "code": "ERROR_CODE",
+  "details": "Additional details"
+}
+```
+
+## Health Checks
+
+All services provide health check endpoints:
+- `GET /health` - Standard health check
+- `GET /ping` - Simple ping response
+- `GET /api/health` - API-specific health
+
+## Development Notes
+
+### Testing APIs
+```bash
+# Test all health endpoints
+for port in 4005 4006 4007 4008 4009 4010 4011 4012 4013 4014 4015 4017 4018; do
+    echo "Testing port $port..."
+    curl -f -s "http://localhost:$port/health" || \
+    curl -f -s "http://localhost:$port/ping" || \
+    curl -f -s "http://localhost:$port/api/health" || \
+    echo "Health check failed for port $port"
+done
+```
+
+### Monitoring API Usage
+- Use Grafana dashboards to monitor API calls
+- Check service logs for API errors
+- Monitor resource usage with Docker stats
+- Set up alerts for API failures
+
+## Security Considerations
+
+### Demo Mode
+- All APIs are accessible without authentication
+- No rate limiting implemented
+- No HTTPS encryption
+- Default demo credentials
+
+### Production Migration
+- Implement proper authentication
+- Add rate limiting
+- Use HTTPS/TLS
+- Set up API gateway
+- Implement audit logging
+- Configure CORS policies