TSYSDevStack/SupportStack/demo/AGENTS.md

# TSYS Developer Support Stack - Agent Guidelines

## Project Intent
The TSYS Developer Support Stack is a comprehensive Docker Compose environment providing 16 developer tools and services for TSYS Group development workflow. This stack includes:

- **Developer Tools**: Homepage (dashboard), Atuin (shell history), Wakapi (time tracking), ArchiveBox (web archiving), Tube Archivist (YouTube archiving), MailHog (email testing)
- **Infrastructure**: PostgreSQL, Elasticsearch, Docker Socket Proxy, Pi-hole (DNS), Portainer (Docker management), Redis (cache)
- **Monitoring**: InfluxDB (time series), Grafana (visualization)
- **Documentation**: Draw.io (diagrams), Kroki (diagrams as code)

## 🚨 STRICT QA/TESTING/AUDITING/VALIDATION GUIDELINES

### 📋 MANDATORY TESTING PROTOCOL

**ALL CHANGES MUST PASS THE FOLLOWING BEFORE CONSIDERATION COMPLETE:**

1. **PRIMARY VALIDATION**: `./test-stack.sh` is the **ONLY** entrypoint for all testing/qa/audit/validation
   - **100% Test Coverage Required**: All end-user facing services must be tested
   - **Zero Failure Tolerance**: Any test failure = change rejected
   - **Comprehensive Validation**: Security, functionality, performance, accessibility

2. **PRE-COMMIT VALIDATION**: Before any commit:
   ```bash
   # MUST run full test suite
   ./test-stack.sh
   
   # MUST verify all services healthy
   docker compose --env-file demo.env ps
   
   # MUST validate configuration
   ./test-stack.sh config
   ```

3. **SERVICE CATEGORIES**:
   - **End-User Services**: Homepage, Atuin, Wakapi, ArchiveBox, Tube Archivist, MailHog, Pi-hole, Portainer, InfluxDB, Grafana, Draw.io, Kroki
   - **Infrastructure Services**: PostgreSQL, Elasticsearch, Redis, Docker Socket Proxy
   - **Homepage Display Rule**: ONLY end-user services should appear in Homepage dashboard

### 🔒 SECURITY VALIDATION REQUIREMENTS

1. **Docker Socket Security**:
   - ✅ No direct Docker socket exposure
   - ✅ All access through proxy only
   - ✅ Proxy properly restricts dangerous operations

2. **Resource Limits**:
   - ✅ All services have memory limits
   - ✅ All services have CPU limits
   - ✅ Resource usage monitored

3. **Network Security**:
   - ✅ Services isolated in dedicated network
   - ✅ Only necessary ports exposed
   - ✅ No privileged containers

### 🧪 TEST SUITE REQUIREMENTS (test-stack.sh)

**MUST INCLUDE THE FOLLOWING TEST CATEGORIES:**

1. **Configuration Validation**:
   - Docker Compose syntax validation
   - Environment variable validation
   - YAML file linting
   - Shell script linting

2. **Service Health Validation**:
   - All end-user services accessible via HTTP
   - All health check endpoints responding
   - Proper service status reporting
   - Service discovery functionality

3. **Security Validation**:
   - Docker socket proxy security testing
   - Port accessibility validation
   - Container privilege verification
   - Network isolation testing

4. **Functionality Validation**:
   - Homepage service discovery accuracy
   - Service grouping correctness
   - End-user interface accessibility
   - Integration testing between services

5. **Performance Validation**:
   - Resource usage monitoring
   - Startup time validation
   - Memory leak detection
   - CPU usage validation

### 📊 SUCCESS CRITERIA (100% REQUIRED)

**ALL OF THE FOLLOWING MUST PASS:**

1. **Container Status**:
   - ✅ All 16 containers running
   - ✅ All end-user services healthy
   - ✅ No restart loops
   - ✅ Proper startup ordering

2. **Service Accessibility**:
   - ✅ All end-user services accessible via designated ports
   - ✅ HTTP status 200 for all web interfaces
   - ✅ Health check endpoints responding
   - ✅ No port conflicts

3. **Homepage Dashboard**:
   - ✅ Discovers exactly 12 end-user services (not 16)
   - ✅ Services grouped correctly in 4 categories
   - ✅ No infrastructure services displayed
   - ✅ Service status accurately reported

4. **Security Compliance**:
   - ✅ Docker socket proxy secure
   - ✅ No direct socket access
   - ✅ Resource limits enforced
   - ✅ Network isolation maintained

5. **Test Suite Coverage**:
   - ✅ 100% end-user service coverage
   - ✅ All failure scenarios tested
   - ✅ Performance benchmarks met
   - ✅ Security validations complete

## Demo Environment Specifics
- **Network**: 192.168.3.0/24
- **Host IP**: 192.168.3.6
- **Port Range**: 4000-4011 for services, 2375 for Docker socket proxy
- **Docker Network**: tsysdevstack_supportstack
- **All passwords**: demo_password (for demo environment only)

## 🔄 WORKFLOW INTEGRATION

### Before Making Changes:
1. Run `./test-stack.sh` to establish baseline
2. Make changes
3. Run `./test-stack.sh` again
4. Fix any failures
5. Repeat until 100% pass

### Before Committing:
1. `./test-stack.sh` must pass completely
2. All services must be healthy
3. Manual verification of key functionality
4. Documentation updated if needed

### Before Declaring "Done":
1. Full test suite execution
2. Manual service verification
3. Performance validation
4. Security audit completion
5. Documentation review

## Critical Configuration Files
- `docker-compose.yml`: Main service definitions with resource limits
- `homepage/config/settings.yaml`: Homepage configuration
- `homepage/config/docker.yaml`: Service discovery configuration (CRITICAL for service filtering)
- `test-stack.sh`: **PRIMARY VALIDATION TOOL** - comprehensive test suite
- `AGENTS.md`: This file - QA guidelines and workflow requirements

## 🚨 CURRENT KNOWN ISSUES (MUST BE FIXED)

1. **Homepage Service Discovery**:
   - ❌ Redis/Elasticsearch/PostgreSQL appearing (should be hidden)
   - ❌ Pi-hole not working
   - ❌ Atuin not working
   - ❌ Tube Archivist not working
   - ❌ Portainer showing "unknown" status

2. **Service Health Issues**:
   - ❌ Multiple services restarting
   - ❌ Health check timing issues
   - ❌ Resource contention problems

## Success Criteria (100% REQUIRED)
- ✅ All 16 containers running and healthy
- ✅ Homepage discovering exactly 12 end-user services in 4 groups
- ✅ All end-user ports accessible and responding with HTTP 200
- ✅ Test suite passing completely (100% coverage)
- ✅ No security vulnerabilities (Docker socket only via proxy)
- ✅ Zero infrastructure services displayed in Homepage
- ✅ All end-user services fully functional