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

# 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

# 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

# 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