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>
This commit is contained in:
285
demo/docs/api-docs/README.md
Normal file
285
demo/docs/api-docs/README.md
Normal file
@@ -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
|
||||
55
demo/docs/service-guides/README.md
Normal file
55
demo/docs/service-guides/README.md
Normal file
@@ -0,0 +1,55 @@
|
||||
# TSYS Developer Support Stack - Service Guides
|
||||
|
||||
This directory contains detailed guides for each service in the stack.
|
||||
|
||||
## Available Guides
|
||||
|
||||
- [Homepage Dashboard](homepage.md)
|
||||
- [Infrastructure Services](infrastructure.md)
|
||||
- [Monitoring & Observability](monitoring.md)
|
||||
- [Documentation & Diagramming](documentation.md)
|
||||
- [Developer Tools](developer-tools.md)
|
||||
|
||||
## Quick Access
|
||||
|
||||
All services are accessible through the Homepage dashboard at http://localhost:4000
|
||||
|
||||
## Service Categories
|
||||
|
||||
### 🏗️ Infrastructure Services
|
||||
- **Pi-hole** (Port 4006): DNS management with ad blocking
|
||||
- **Portainer** (Port 4007): Web-based container management
|
||||
- **Docker Socket Proxy** (Port 4005): Secure Docker socket access
|
||||
|
||||
### 📊 Monitoring & Observability
|
||||
- **InfluxDB** (Port 4008): Time series database for metrics
|
||||
- **Grafana** (Port 4009): Analytics and visualization platform
|
||||
|
||||
### 📚 Documentation & Diagramming
|
||||
- **Draw.io** (Port 4010): Web-based diagramming application
|
||||
- **Kroki** (Port 4011): Diagrams as a service
|
||||
|
||||
### 🛠️ Developer Tools
|
||||
- **Homepage** (Port 4000): Central dashboard for service discovery
|
||||
- **Atomic Tracker** (Port 4012): Habit tracking and personal dashboard
|
||||
- **ArchiveBox** (Port 4013): Web archiving solution
|
||||
- **Tube Archivist** (Port 4014): YouTube video archiving
|
||||
- **Wakapi** (Port 4015): Open-source WakaTime alternative
|
||||
- **MailHog** (Port 4017): Web and API based SMTP testing
|
||||
- **Atuin** (Port 4018): Magical shell history synchronization
|
||||
|
||||
## Demo Credentials
|
||||
|
||||
⚠️ **FOR DEMONSTRATION PURPOSES ONLY**
|
||||
|
||||
- **Username**: `admin`
|
||||
- **Password**: `demo_password`
|
||||
|
||||
These credentials work for Grafana and Portainer. Other services may have different authentication requirements.
|
||||
|
||||
## Getting Help
|
||||
|
||||
1. Check the individual service guides below
|
||||
2. Review the [troubleshooting guide](../troubleshooting/README.md)
|
||||
3. Check service logs: `docker compose logs [service-name]`
|
||||
4. Verify service status: `docker compose ps`
|
||||
291
demo/docs/troubleshooting/README.md
Normal file
291
demo/docs/troubleshooting/README.md
Normal file
@@ -0,0 +1,291 @@
|
||||
# TSYS Developer Support Stack - Troubleshooting Guide
|
||||
|
||||
## Common Issues and Solutions
|
||||
|
||||
### Services Not Starting
|
||||
|
||||
#### Issue: Docker daemon not running
|
||||
**Symptoms**: `Cannot connect to the Docker daemon`
|
||||
**Solution**:
|
||||
```bash
|
||||
sudo systemctl start docker
|
||||
sudo systemctl enable docker
|
||||
```
|
||||
|
||||
#### Issue: Port conflicts
|
||||
**Symptoms**: `Port already in use` errors
|
||||
**Solution**:
|
||||
```bash
|
||||
# Check what's using the port
|
||||
netstat -tulpn | grep :4000
|
||||
|
||||
# Kill conflicting process
|
||||
sudo fuser -k 4000/tcp
|
||||
```
|
||||
|
||||
#### Issue: Environment variables not set
|
||||
**Symptoms**: `Variable not found` errors
|
||||
**Solution**:
|
||||
```bash
|
||||
# Check demo.env exists and is populated
|
||||
cat demo.env
|
||||
|
||||
# Re-run user detection
|
||||
./scripts/demo-stack.sh deploy
|
||||
```
|
||||
|
||||
### Health Check Failures
|
||||
|
||||
#### Issue: Services stuck in "starting" state
|
||||
**Symptoms**: Health checks timeout
|
||||
**Solution**:
|
||||
```bash
|
||||
# Check service logs
|
||||
docker compose logs [service-name]
|
||||
|
||||
# Restart specific service
|
||||
docker compose restart [service-name]
|
||||
|
||||
# Check resource usage
|
||||
docker stats
|
||||
```
|
||||
|
||||
#### Issue: Network connectivity problems
|
||||
**Symptoms**: Services can't reach each other
|
||||
**Solution**:
|
||||
```bash
|
||||
# Check network exists
|
||||
docker network ls | grep tsysdevstack
|
||||
|
||||
# Recreate network
|
||||
docker network create tsysdevstack_supportstack-demo
|
||||
|
||||
# Restart stack
|
||||
docker compose down && docker compose up -d
|
||||
```
|
||||
|
||||
### Permission Issues
|
||||
|
||||
#### Issue: File ownership problems
|
||||
**Symptoms**: `Permission denied` errors
|
||||
**Solution**:
|
||||
```bash
|
||||
# Check current user
|
||||
id
|
||||
|
||||
# Verify UID/GID detection
|
||||
cat demo.env | grep -E "(UID|GID)"
|
||||
|
||||
# Fix volume permissions
|
||||
sudo chown -R $(id -u):$(id -g) /var/lib/docker/volumes/tsysdevstack_*
|
||||
```
|
||||
|
||||
#### Issue: Docker group access
|
||||
**Symptoms**: `Got permission denied` errors
|
||||
**Solution**:
|
||||
```bash
|
||||
# Add user to docker group
|
||||
sudo usermod -aG docker $USER
|
||||
|
||||
# Log out and back in, or run:
|
||||
newgrp docker
|
||||
```
|
||||
|
||||
### Service-Specific Issues
|
||||
|
||||
#### Pi-hole DNS Issues
|
||||
**Symptoms**: DNS resolution failures
|
||||
**Solution**:
|
||||
```bash
|
||||
# Check Pi-hole status
|
||||
docker exec tsysdevstack-supportstack-demo-pihole pihole status
|
||||
|
||||
# Test DNS resolution
|
||||
nslookup google.com localhost
|
||||
|
||||
# Restart DNS service
|
||||
docker exec tsysdevstack-supportstack-demo-pihole pihole restartdns
|
||||
```
|
||||
|
||||
#### Grafana Data Source Connection
|
||||
**Symptoms**: InfluxDB data source not working
|
||||
**Solution**:
|
||||
```bash
|
||||
# Test InfluxDB connectivity
|
||||
curl http://localhost:4008/ping
|
||||
|
||||
# Check Grafana logs
|
||||
docker compose logs grafana
|
||||
|
||||
# Verify data source configuration
|
||||
# Navigate to: http://localhost:4009/datasources
|
||||
```
|
||||
|
||||
#### Portainer Container Access
|
||||
**Symptoms**: Can't manage containers
|
||||
**Solution**:
|
||||
```bash
|
||||
# Check Docker socket proxy
|
||||
docker compose logs docker-socket-proxy
|
||||
|
||||
# Verify proxy permissions
|
||||
curl http://localhost:4005/version
|
||||
|
||||
# Restart Portainer
|
||||
docker compose restart portainer
|
||||
```
|
||||
|
||||
### Performance Issues
|
||||
|
||||
#### Issue: High memory usage
|
||||
**Symptoms**: System becomes slow
|
||||
**Solution**:
|
||||
```bash
|
||||
# Check resource usage
|
||||
docker stats
|
||||
|
||||
# Set memory limits in docker-compose.yml
|
||||
# Add to each service:
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
memory: 512M
|
||||
|
||||
# Restart with new limits
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
#### Issue: Slow startup times
|
||||
**Symptoms**: Services take >60 seconds to start
|
||||
**Solution**:
|
||||
```bash
|
||||
# Check system resources
|
||||
free -h
|
||||
df -h
|
||||
|
||||
# Pull images in advance
|
||||
docker compose pull
|
||||
|
||||
# Check for conflicting services
|
||||
docker ps -a
|
||||
```
|
||||
|
||||
## Diagnostic Commands
|
||||
|
||||
### System Information
|
||||
```bash
|
||||
# System info
|
||||
uname -a
|
||||
free -h
|
||||
df -h
|
||||
|
||||
# Docker info
|
||||
docker version
|
||||
docker compose version
|
||||
docker system df
|
||||
```
|
||||
|
||||
### Service Status
|
||||
```bash
|
||||
# All services status
|
||||
docker compose ps
|
||||
|
||||
# Service logs
|
||||
docker compose logs
|
||||
|
||||
# Resource usage
|
||||
docker stats
|
||||
|
||||
# Network info
|
||||
docker network ls
|
||||
docker network inspect tsysdevstack_supportstack-demo
|
||||
```
|
||||
|
||||
### Health Checks
|
||||
```bash
|
||||
# Test all endpoints
|
||||
for port in 4000 4005 4006 4007 4008 4009 4010 4011 4012 4013 4014 4015 4017 4018; do
|
||||
curl -f -s --max-time 5 "http://localhost:$port" && echo "Port $port: OK" || echo "Port $port: FAIL"
|
||||
done
|
||||
```
|
||||
|
||||
## Getting Additional Help
|
||||
|
||||
### Check Logs First
|
||||
```bash
|
||||
# All service logs
|
||||
docker compose logs
|
||||
|
||||
# Specific service logs
|
||||
docker compose logs [service-name]
|
||||
|
||||
# Follow logs in real-time
|
||||
docker compose logs -f [service-name]
|
||||
```
|
||||
|
||||
### Validation Scripts
|
||||
```bash
|
||||
# Run comprehensive validation
|
||||
./scripts/validate-all.sh
|
||||
|
||||
# Run test suite
|
||||
./scripts/demo-test.sh full
|
||||
|
||||
# Run specific test categories
|
||||
./scripts/demo-test.sh security
|
||||
./scripts/demo-test.sh permissions
|
||||
./scripts/demo-test.sh network
|
||||
```
|
||||
|
||||
### Reset and Restart
|
||||
```bash
|
||||
# Complete reset (removes all data)
|
||||
docker compose down -v
|
||||
docker system prune -f
|
||||
|
||||
# Fresh deployment
|
||||
./scripts/demo-stack.sh deploy
|
||||
```
|
||||
|
||||
## Known Limitations
|
||||
|
||||
### Demo Mode Restrictions
|
||||
- No data persistence between restarts
|
||||
- Hardcoded demo credentials
|
||||
- No external network access
|
||||
- No security hardening
|
||||
|
||||
### Resource Requirements
|
||||
- Minimum 8GB RAM recommended
|
||||
- Minimum 10GB disk space
|
||||
- Docker daemon must be running
|
||||
- User must be in docker group
|
||||
|
||||
### Port Requirements
|
||||
All ports 4000-4018 must be available:
|
||||
- 4000: Homepage
|
||||
- 4005: Docker Socket Proxy
|
||||
- 4006: Pi-hole
|
||||
- 4007: Portainer
|
||||
- 4008: InfluxDB
|
||||
- 4009: Grafana
|
||||
- 4010: Draw.io
|
||||
- 4011: Kroki
|
||||
- 4012: Atomic Tracker
|
||||
- 4013: ArchiveBox
|
||||
- 4014: Tube Archivist
|
||||
- 4015: Wakapi
|
||||
- 4017: MailHog
|
||||
- 4018: Atuin
|
||||
|
||||
## Contact and Support
|
||||
|
||||
If issues persist after trying these solutions:
|
||||
|
||||
1. Document the exact error message
|
||||
2. Include system information (OS, Docker version)
|
||||
3. List steps to reproduce the issue
|
||||
4. Include relevant log output
|
||||
5. Specify demo vs production context
|
||||
|
||||
Remember: This is a demo configuration designed for development and testing purposes only.
|
||||
Reference in New Issue
Block a user