TSYSDevStack-SupportStack-LocalWorkstation/demo/AGENTS.md

# TSYS Developer Support Stack - Development Guidelines

## 🎯 Development Principles

### Demo-First Architecture
- **Demo-Only Configuration**: All services configured for demonstration purposes only
- **No Persistent Data**: Zero data persistence between demo sessions
- **Dynamic User Handling**: Automatic UID/GID detection and application
- **Security-First**: Docker socket proxy for all container operations
- **Minimal Bind Mounts**: Prefer Docker volumes over host bind mounts. Use host bind mounts only for minimal bootstrap purposes of configuration data that needs to be persistent.
- **Consistent Naming**: `tsysdevstack-supportstack-demo-` prefix everywhere including in the docker-compose file for the service names.
- **One-Command Deployment**: Single script deployment with full validation

### Dynamic Environment Strategy
- **User Detection**: Automatic current user and group ID detection
- **Docker Group Handling**: Dynamic docker group ID resolution
- **Variable-Driven Configuration**: All settings via environment variables
- **Template-Based Compose**: Generate docker-compose.yml from templates
- **Environment Isolation**: Separate demo.env for all configuration

### FOSS Only Policy
- Exclusively use free/libre/open source software
- Verify license compatibility
- Prefer official Docker images
- Document any proprietary dependencies

### Inner Loop Focus
- Support daily development workflows
- Avoid project-specific dependencies
- Prioritize developer productivity
- Maintain workstation-local deployment

### Code Organization Policy
- **Mandatory Code Subdirectory**: ALL created files, configurations, scripts, and code MUST be placed in the `code/` subdirectory
- **No Root-Level Code**: Absolutely NO code files shall be created at the project root level
- **Structured Organization**: All implementation artifacts belong under `code/` with proper subdirectory organization

### System Interference Policy
- **NEVER interfere with existing processes**: Do not kill, stop, or modify any running processes without explicit permission
- **Check before acting**: Always verify what processes/screen sessions are running before taking any action
- **Use unique identifiers**: Create uniquely named sessions/processes to avoid conflicts
- **Ask first**: Always request permission before touching any existing work on the system
- **Respect concurrent work**: Other users/processes may be running - do not assume exclusive access

---

## 🛡️ Quality Assurance Standards

### Mandatory Tool Validation
- **yamllint**: ALL YAML files MUST pass yamllint validation before commit
- **shellcheck**: ALL shell scripts MUST pass shellcheck validation before commit
- **hadolint**: ALL Dockerfiles MUST pass hadolint validation before commit
- **Pre-commit Hooks**: Automated validation on every commit attempt

### Zero-Tolerance Policy
- **No YAML syntax errors**: Prevents Docker Compose failures
- **No shell script errors**: Prevents deployment script failures  
- **No Docker image issues**: Prevents container startup failures
- **No port conflicts**: Prevents service accessibility issues
- **No permission problems**: Prevents file ownership issues

### Proactive Validation Checklist
Before ANY file is created or modified:
1. ✅ YAML syntax validated with yamllint
2. ✅ Shell script validated with shellcheck
3. ✅ Environment variables verified
4. ✅ Port availability confirmed
5. ✅ Docker image existence verified
6. ✅ Service dependencies validated
7. ✅ Health check endpoints confirmed
8. ✅ Resource requirements assessed

---

## 🏗️ Architecture Guidelines

### Service Categories
- **Infrastructure Services**: Core platform services
- **Monitoring & Observability**: Metrics and visualization
- **Documentation & Diagramming**: Knowledge management
- **Developer Tools**: Productivity enhancers

### Design Patterns
- **Service Discovery**: Automatic via Homepage dashboard
- **Health Checks**: Comprehensive for all services
- **Network Isolation**: Docker network per stack
- **Resource Limits**: Memory and CPU constraints

---

## 🔧 Technical Standards

### Docker Configuration Standards

#### Demo Service Template
```yaml
# Standard service template (docker-compose.yml.template)
services:
  service-name:
    image: official/image:tag
    user: "${UID}:${GID}"
    container_name: "${COMPOSE_PROJECT_NAME}-service-name"
    restart: unless-stopped
    networks:
      - ${COMPOSE_NETWORK_NAME}
    volumes:
      - "${COMPOSE_PROJECT_NAME}_service_data:/path"
    environment:
      - PUID=${UID}
      - PGID=${GID}
    labels:
      homepage.group: "Group Name"
      homepage.name: "Display Name"
      homepage.icon: "icon-name"
      homepage.href: "http://localhost:${SERVICE_PORT}"
      homepage.description: "Brief description"
```

#### Dynamic Variable Requirements
- **UID/GID**: Current user and group detection
- **DOCKER_GID**: Docker group ID for socket access
- **COMPOSE_PROJECT_NAME**: `tsysdevstack-supportstack-demo`
- **COMPOSE_NETWORK_NAME**: `tsysdevstack-supportstack-demo-network`
- **Service Ports**: All configurable via environment variables

### Port Assignment Strategy
- Range: 4000-4099
- Groups: Sequential allocation
- Document in README.md port table
- Avoid conflicts with host services

### Network Configuration
- Network name: `tsysdevstack_supportstack-demo`
- IP binding: `192.168.3.6:{port}` where applicable
- Inter-service communication via container names
- Only necessary ports exposed to host

---

## 📋 Quality Assurance

### Testing Requirements
- Automated health check validation
- Port accessibility verification
- Service discovery functionality
- Resource usage monitoring
- User workflow validation

### Code Quality Standards
- Clear, commented configurations
- Consistent naming conventions
- Comprehensive documentation
- Atomic commits with conventional messages

### Security Guidelines

#### Demo Security Model
- **Demo-Hardened Configurations**: All settings optimized for demonstration
- **No External Network Access**: Isolated except for image pulls
- **Production Separation**: Clear distinction from production deployments
- **Security Documentation**: All assumptions clearly documented

#### Docker Socket Security
- **Mandatory Proxy**: All container operations through docker-socket-proxy
- **Restricted API Access**: Minimal permissions per service requirements
- **No Direct Socket Access**: Prevent direct Docker socket mounting
- **Group-Based Access**: Dynamic docker group ID assignment

#### File System Security
- **Dynamic User Mapping**: Automatic UID/GID detection prevents ownership issues
- **Volume-First Storage**: Prefer Docker volumes over bind mounts
- **Read-Only Bind Mounts**: Minimal host filesystem access
- **Permission Validation**: Automated file ownership verification

---

## 🔄 Development Workflow

### Demo-First Service Addition
1. **Research**: Verify FOSS status and official Docker image availability
2. **Plan**: Determine port assignment and service group
3. **Template Configuration**: Add to docker-compose.yml.template with variables
4. **Environment Setup**: Add service variables to demo.env
5. **Security Integration**: Configure docker-socket-proxy permissions
6. **Dynamic Testing**: Validate with demo-stack.sh and demo-test.sh
7. **Documentation Update**: Update README.md, PRD.md, and AGENTS.md
8. **Atomic Commit**: Conventional commit with detailed description

### Process Management Guidelines
- **Screen Sessions**: Use descriptive, unique names (e.g., `demo-deploy-YYYYMMDD-HHMMSS`)
- **Background Processes**: Always use logging to track progress
- **Process Discovery**: Use `ps aux | grep` and `screen -ls` to check existing work
- **Safe Termination**: Only terminate processes you explicitly started
- **Permission First**: Always ask before modifying/killing any existing process

### Template-Driven Development
- **Variable Configuration**: All settings via environment variables
- **Naming Convention**: Consistent `tsysdevstack-supportstack-demo-` prefix
- **User Handling**: Dynamic UID/GID detection in all services
- **Security Integration**: Docker socket proxy for container operations
- **Volume Strategy**: Docker volumes with dynamic naming

### Service Removal Process
1. **Deprecate**: Mark service for removal in documentation
2. **Test**: Verify stack functionality without service
3. **Remove**: Delete from docker-compose.yml
4. **Update**: Clean up documentation and port assignments
5. **Commit**: Document removal in commit message

### Configuration Changes
1. **Plan**: Document change rationale and impact
2. **Test**: Validate in development environment
3. **Update**: Apply changes to configuration files
4. **Verify**: Run full test suite
5. **Document**: Update relevant documentation
6. **Commit**: Atomic commit with detailed description

---

## 📊 Monitoring & Observability

### Health Check Standards
- All services must include health checks
- Health checks complete within 10 seconds
- HTTP endpoints preferred
- Fallback to container status checks

### Resource Limits
- Memory: < 512MB per service (where applicable)
- CPU: < 25% per service (idle)
- Startup time: < 60 seconds for full stack
- Disk usage: Temporary volumes only

### Logging Standards
- Structured logging where possible
- Log levels: INFO, WARN, ERROR
- Container logs accessible via `docker compose logs`
- No persistent log storage in demo mode

---

## 🧪 Testing Guidelines

### Demo Testing Framework
```bash
# ALWAYS check for existing work first
screen -ls
ps aux | grep demo-stack

# Dynamic deployment and testing (use unique session names)
screen -S demo-deploy-$(date +%Y%m%d-%H%M%S) -dm -L -Logfile deploy-$(date +%Y%m%d-%H%M%S).log ./demo-stack.sh deploy
./demo-test.sh full       # Comprehensive QA/validation
./demo-test.sh security    # Security compliance validation
./demo-test.sh permissions # File ownership validation
./demo-test.sh network     # Network isolation validation
```

### Automated Validation Suite
- **File Ownership**: Verify no root-owned files on host
- **User Mapping**: Validate UID/GID detection and application
- **Docker Group**: Confirm docker group access for socket proxy
- **Service Health**: All services passing health checks
- **Port Accessibility**: Verify all ports accessible from host
- **Network Isolation**: Confirm services isolated in demo network
- **Volume Permissions**: Validate Docker volume permissions
- **Security Compliance**: Docker socket proxy restrictions enforced

### Manual Testing Checklist
- [ ] All web interfaces accessible via browser
- [ ] Demo credentials work correctly
- [ ] Service discovery functional in Homepage
- [ ] Inter-service communication working through proxy
- [ ] Resource usage within defined limits
- [ ] No port conflicts on host system
- [ ] All health checks passing
- [ ] No root-owned files created on host
- [ ] Docker socket proxy functioning correctly
- [ ] Dynamic user detection working properly

### Performance Testing
- Startup time measurement
- Memory usage monitoring
- CPU usage validation
- Network connectivity testing
- Resource leak detection

---

## 📚 Documentation Standards

### README.md Requirements
- Quick start instructions
- Service overview table
- Technical configuration details
- Troubleshooting guide
- Security notes and warnings

### PRD.md Requirements
- Product vision and goals
- Functional requirements
- User experience requirements
- Acceptance criteria
- Success metrics

### AGENTS.md Requirements
- Development principles
- Technical standards
- Quality assurance guidelines
- Development workflow
- Testing procedures

---

## 🔒 Security Considerations

### Demo Security Model
- Hardcoded credentials clearly marked
- No encryption or security hardening
- Network isolation within Docker
- No external access except image pulls

### Security Checklist
- [ ] All services use demo credentials
- [ ] No persistent sensitive data
- [ ] Network properly isolated
- [ ] Only necessary ports exposed
- [ ] Security warnings documented
- [ ] Production deployment guidance included

---

## 🚀 Deployment Guidelines

### Local Development
```bash
# Check for existing work BEFORE starting
screen -ls
ps aux | grep demo-stack

# Start development stack with unique session name
screen -S demo-deploy-$(date +%Y%m%d-%H%M%S) -dm -L -Logfile deploy-$(date +%Y%m%d-%H%M%S).log ./demo-stack.sh deploy

# Monitor startup
docker compose logs -f

# Validate deployment
./test-stack.sh
```

### Demo Preparation
1. Clean all containers and volumes
2. Pull latest images
3. Verify all health checks
4. Test complete user workflows
5. Document any known issues

### Production Migration
- Replace demo credentials with secure ones
- Implement persistent data storage
- Add encryption and security hardening
- Configure backup and recovery
- Set up monitoring and alerting

---

## 📞 Development Support

### Getting Help
1. Check troubleshooting section in README.md
2. Review service logs: `docker compose logs {service}`
3. Consult individual service documentation
4. Check health status: `docker compose ps`
5. **CRITICAL**: Always check for existing processes before starting new ones: `screen -ls` and `ps aux | grep demo-stack`

### Issue Reporting
- Include full error messages
- Provide system information
- Document reproduction steps
- Include relevant configuration snippets
- Specify demo vs production context

---

*Last updated: 2025-11-13*