refactor: move stack assets and wire in mailhog

.gitignore

@@ -60,6 +60,11 @@ artifacts/SupportStack/config/wakaapi/database/*.db-journal
 artifacts/SupportStack/config/homepage/logs/
 artifacts/SupportStack/docker-compose/config/
 artifacts/ToolboxStack/toolbox-base/.build-cache/
+SupportStack/output/config/wakaapi/database/*.db
+SupportStack/output/config/wakaapi/database/*.db-journal
+SupportStack/output/docker-compose/config/
+SupportStack/output/docker-compose/config/homepage/logs/
+ToolboxStack/output/toolbox-base/.build-cache/
 
 # Local Docker volumes
 .docker-volumes/

SupportStack/output/TSYSDevStack-SupportStack-Demo-Settings

@@ -43,6 +43,13 @@ WAKAAPI_CONFIG_PATH=./config/wakaapi
 WAKAAPI_WAKATIME_API_KEY=
 WAKAAPI_DATABASE_PATH=./config/wakaapi/database
 
+# Mailhog Settings
+MAILHOG_NAME=tsysdevstack-supportstack-demo-mailhog
+MAILHOG_IMAGE=mailhog/mailhog:v1.0.1
+MAILHOG_SMTP_PORT=1025
+MAILHOG_UI_PORT=8025
+MAILHOG_NETWORK=tsysdevstack-supportstack-demo-network
+
 # Resource Limits (for single user demo capacity)
 # docker-socket-proxy
 DOCKER_SOCKET_PROXY_MEM_LIMIT=128m
@@ -56,6 +63,10 @@ HOMEPAGE_CPU_LIMIT=0.5
 WAKAAPI_MEM_LIMIT=192m
 WAKAAPI_CPU_LIMIT=0.3
 
+# mailhog
+MAILHOG_MEM_LIMIT=128m
+MAILHOG_CPU_LIMIT=0.25
+
 # Health Check Settings
 HEALTH_CHECK_INTERVAL=30s
 HEALTH_CHECK_TIMEOUT=10s

SupportStack/output/code/TSYSDevStack-SupportStack-Demo-Control.sh

@@ -58,12 +58,19 @@ export WAKAAPI_NETWORK
 export WAKAAPI_CONFIG_PATH
 export WAKAAPI_WAKATIME_API_KEY
 export WAKAAPI_DATABASE_PATH
+export MAILHOG_NAME
+export MAILHOG_IMAGE
+export MAILHOG_SMTP_PORT
+export MAILHOG_UI_PORT
+export MAILHOG_NETWORK
 export DOCKER_SOCKET_PROXY_MEM_LIMIT
 export DOCKER_SOCKET_PROXY_CPU_LIMIT
 export HOMEPAGE_MEM_LIMIT
 export HOMEPAGE_CPU_LIMIT
 export WAKAAPI_MEM_LIMIT
 export WAKAAPI_CPU_LIMIT
+export MAILHOG_MEM_LIMIT
+export MAILHOG_CPU_LIMIT
 export HEALTH_CHECK_INTERVAL
 export HEALTH_CHECK_TIMEOUT
 export HEALTH_CHECK_START_PERIOD
@@ -187,6 +194,15 @@ start() {
         log_warning "wakaapi compose file not found, skipping..."
     fi
 
+    # Start mailhog
+    log "Starting mailhog..."
+    if [ -f "${COMPOSE_DIR}/tsysdevstack-supportstack-demo-DockerCompose-mailhog.yml" ]; then
+        compose -f "${COMPOSE_DIR}/tsysdevstack-supportstack-demo-DockerCompose-mailhog.yml" up -d
+        log_success "mailhog started"
+    else
+        log_warning "mailhog compose file not found, skipping..."
+    fi
+
     # Wait for services to be ready
     log "Waiting for all services to be ready..."
     sleep 20
@@ -194,6 +210,7 @@ start() {
     log_success "MVP stack started successfully"
     echo "Homepage available at: http://$BIND_ADDRESS:$HOMEPAGE_PORT"
     echo "WakaAPI available at: http://$BIND_ADDRESS:$WAKAAPI_PORT"
+    echo "Mailhog available at: http://$BIND_ADDRESS:$MAILHOG_UI_PORT (SMTP on $MAILHOG_SMTP_PORT)"
 }
 
 # Function to stop the MVP stack
@@ -202,7 +219,16 @@ stop() {
     
     check_docker
 
-    # Stop wakaapi first
+    # Stop mailhog
+    log "Stopping mailhog..."
+    if [ -f "${COMPOSE_DIR}/tsysdevstack-supportstack-demo-DockerCompose-mailhog.yml" ]; then
+        compose -f "${COMPOSE_DIR}/tsysdevstack-supportstack-demo-DockerCompose-mailhog.yml" down
+        log_success "mailhog stopped"
+    else
+        log_warning "mailhog compose file not found, skipping..."
+    fi
+
+    # Stop wakaapi
     log "Stopping wakaapi..."
     if [ -f "${COMPOSE_DIR}/tsysdevstack-supportstack-demo-DockerCompose-wakaapi.yml" ]; then
         compose -f "${COMPOSE_DIR}/tsysdevstack-supportstack-demo-DockerCompose-wakaapi.yml" down
@@ -255,6 +281,10 @@ uninstall() {
         compose -f "${COMPOSE_DIR}/tsysdevstack-supportstack-demo-DockerCompose-wakaapi.yml" down -v
     fi
 
+    if [ -f "${COMPOSE_DIR}/tsysdevstack-supportstack-demo-DockerCompose-mailhog.yml" ]; then
+        compose -f "${COMPOSE_DIR}/tsysdevstack-supportstack-demo-DockerCompose-mailhog.yml" down -v
+    fi
+
     # Remove the shared network
     remove_network
 
@@ -285,6 +315,11 @@ update() {
         log_success "wakaapi images updated"
     fi
 
+    if [ -f "${COMPOSE_DIR}/tsysdevstack-supportstack-demo-DockerCompose-mailhog.yml" ]; then
+        compose -f "${COMPOSE_DIR}/tsysdevstack-supportstack-demo-DockerCompose-mailhog.yml" pull
+        log_success "mailhog images updated"
+    fi
+
     log "Restarting services with updated images..."
     stop
     start
@@ -327,6 +362,15 @@ test() {
         fi
     fi
 
+    # Check mailhog
+    if [ -f "${COMPOSE_DIR}/tsysdevstack-supportstack-demo-DockerCompose-mailhog.yml" ]; then
+        if compose -f "${COMPOSE_DIR}/tsysdevstack-supportstack-demo-DockerCompose-mailhog.yml" ps | grep -q "Up"; then
+            log_success "mailhog is running"
+        else
+            log_error "mailhog is not running"
+        fi
+    fi
+
     # Run any unit/integration tests if available
     TESTS_DIR="$(dirname "$SCRIPT_DIR")/tests"
     if [ -d "$TESTS_DIR" ]; then

SupportStack/output/config/TSYSDevStack-SupportStack-Demo-Settings

@@ -38,6 +38,13 @@ WAKAAPI_CONFIG_PATH=./config/wakaapi
 WAKAAPI_WAKATIME_API_KEY=
 WAKAAPI_DATABASE_PATH=./config/wakaapi/database
 
+# Mailhog Settings
+MAILHOG_NAME=tsysdevstack-supportstack-demo-mailhog
+MAILHOG_IMAGE=mailhog/mailhog:v1.0.1
+MAILHOG_SMTP_PORT=1025
+MAILHOG_UI_PORT=8025
+MAILHOG_NETWORK=tsysdevstack-supportstack-demo-network
+
 # Resource Limits (for single user demo capacity)
 # docker-socket-proxy
 DOCKER_SOCKET_PROXY_MEM_LIMIT=128m
@@ -51,6 +58,10 @@ HOMEPAGE_CPU_LIMIT=0.5
 WAKAAPI_MEM_LIMIT=192m
 WAKAAPI_CPU_LIMIT=0.3
 
+# mailhog
+MAILHOG_MEM_LIMIT=128m
+MAILHOG_CPU_LIMIT=0.25
+
 # Health Check Settings
 HEALTH_CHECK_INTERVAL=30s
 HEALTH_CHECK_TIMEOUT=10s

SupportStack/output/config/homepage/services.yaml

@@ -6,3 +6,4 @@
     - tsysdevstack-supportstack-demo-docker-socket-proxy
     - tsysdevstack-supportstack-demo-homepage
     - tsysdevstack-supportstack-demo-wakaapi
+    - tsysdevstack-supportstack-demo-mailhog

SupportStack/output/docker-compose/tsysdevstack-supportstack-demo-DockerCompose-mailhog.yml

@@ -0,0 +1,43 @@
+services:
+  mailhog:
+    image: ${MAILHOG_IMAGE}
+    container_name: ${MAILHOG_NAME}
+    restart: unless-stopped
+    networks:
+      - tsysdevstack-supportstack-demo-network
+    ports:
+      - "${BIND_ADDRESS}:${MAILHOG_SMTP_PORT}:1025"
+      - "${BIND_ADDRESS}:${MAILHOG_UI_PORT}:8025"
+    environment:
+      - MH_HOSTNAME=mailhog
+      - MH_UI_BIND_ADDR=0.0.0.0:8025
+      - MH_SMTP_BIND_ADDR=0.0.0.0:1025
+    mem_limit: ${MAILHOG_MEM_LIMIT}
+    mem_reservation: ${MAILHOG_MEM_LIMIT}
+    deploy:
+      resources:
+        limits:
+          cpus: '${MAILHOG_CPU_LIMIT}'
+          memory: ${MAILHOG_MEM_LIMIT}
+        reservations:
+          cpus: '${MAILHOG_CPU_LIMIT}'
+          memory: ${MAILHOG_MEM_LIMIT}
+    healthcheck:
+      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:8025/"]
+      interval: ${HEALTH_CHECK_INTERVAL}
+      timeout: ${HEALTH_CHECK_TIMEOUT}
+      start_period: ${HEALTH_CHECK_START_PERIOD}
+      retries: ${HEALTH_CHECK_RETRIES}
+    labels:
+      homepage.group: "Support Stack"
+      homepage.name: "Mailhog"
+      homepage.icon: "mailhog.png"
+      homepage.href: "http://${BIND_ADDRESS}:${MAILHOG_UI_PORT}"
+      homepage.description: "Mailhog SMTP testing inbox"
+      homepage.type: "mailhog"
+    user: "${TSYSDEVSTACK_UID}:${TSYSDEVSTACK_GID}"
+
+networks:
+  tsysdevstack-supportstack-demo-network:
+    external: true
+    name: ${TSYSDEVSTACK_NETWORK_NAME}

SupportStack/output/tests/test_mailhog.sh

@@ -0,0 +1,50 @@
+#!/bin/bash
+
+# Unit test for Mailhog component
+# TDD flow: test first to ensure failure prior to implementation
+
+set -e
+
+# Load environment settings
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+ENV_FILE="${SCRIPT_DIR}/TSYSDevStack-SupportStack-Demo-Settings"
+
+if [ ! -f "$ENV_FILE" ]; then
+    echo "Error: Environment settings file not found at $ENV_FILE"
+    exit 1
+fi
+
+source "$ENV_FILE"
+
+echo "Testing Mailhog availability and functionality..."
+
+# Ensure Mailhog container is running
+if ! docker ps | grep -q "$MAILHOG_NAME"; then
+    echo "❌ Mailhog container is not running"
+    exit 1
+fi
+
+# Allow service time to respond
+sleep 3
+
+# Verify Mailhog UI is reachable
+if curl -f -s "http://${BIND_ADDRESS}:${MAILHOG_UI_PORT}/" > /dev/null 2>&1; then
+    echo "✅ Mailhog UI is accessible at http://${BIND_ADDRESS}:${MAILHOG_UI_PORT}"
+else
+    echo "❌ Mailhog UI is not accessible at http://${BIND_ADDRESS}:${MAILHOG_UI_PORT}"
+    exit 1
+fi
+
+# Optional SMTP port check (basic TCP connect)
+if command -v nc >/dev/null 2>&1; then
+    if timeout 3 nc -z "${BIND_ADDRESS}" "${MAILHOG_SMTP_PORT}" >/dev/null 2>&1; then
+        echo "✅ Mailhog SMTP port ${MAILHOG_SMTP_PORT} is reachable"
+    else
+        echo "⚠️ Mailhog SMTP port ${MAILHOG_SMTP_PORT} not reachable (informational)"
+    fi
+else
+    echo "⚠️ nc command not available; skipping SMTP connectivity check"
+fi
+
+echo "✅ Mailhog component test passed"
+exit 0

SupportStack/output/tests/test_mailhog_discovery.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+
+# Test to ensure Mailhog appears in Homepage discovery
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+ENV_FILE="${SCRIPT_DIR}/TSYSDevStack-SupportStack-Demo-Settings"
+
+if [ ! -f "$ENV_FILE" ]; then
+    echo "Error: Environment settings file not found at $ENV_FILE"
+    exit 1
+fi
+
+source "$ENV_FILE"
+
+echo "Testing Mailhog discovery on homepage..."
+
+# Validate required containers are running
+if ! docker ps | grep -q "$MAILHOG_NAME"; then
+    echo "❌ Mailhog container is not running"
+    exit 1
+fi
+
+if ! docker ps | grep -q "$HOMEPAGE_NAME"; then
+    echo "❌ Homepage container is not running"
+    exit 1
+fi
+
+# Allow homepage time to refresh discovery
+sleep 5
+
+services_payload=$(curl -s "http://${BIND_ADDRESS}:${HOMEPAGE_PORT}/api/services")
+if echo "$services_payload" | grep -q "\"container\":\"$MAILHOG_NAME\""; then
+    echo "✅ Mailhog is discoverable on homepage"
+    exit 0
+else
+    echo "❌ Mailhog is NOT discoverable on homepage"
+    exit 1
+fi

SupportStack/output/tests/test_mvp_stack.sh

@@ -21,7 +21,7 @@ echo "====================================="
 
 # Test 1: Verify all containers are running
 echo "Test 1: Checking if all containers are running..."
-containers=($DOCKER_SOCKET_PROXY_NAME $HOMEPAGE_NAME $WAKAAPI_NAME)
+containers=($DOCKER_SOCKET_PROXY_NAME $HOMEPAGE_NAME $WAKAAPI_NAME $MAILHOG_NAME)
 
 all_running=true
 for container in "${containers[@]}"; do
@@ -61,6 +61,14 @@ else
     exit 1
 fi
 
+# Test Mailhog accessibility
+if curl -f -s "http://$BIND_ADDRESS:$MAILHOG_UI_PORT" > /dev/null; then
+    echo "✓ Mailhog UI is accessible at http://$BIND_ADDRESS:$MAILHOG_UI_PORT"
+else
+    echo "✗ Mailhog UI is NOT accessible at http://$BIND_ADDRESS:$MAILHOG_UI_PORT"
+    exit 1
+fi
+
 # Test 3: Verify homepage integration labels (basic check)
 echo ""
 echo "Test 3: Checking service configurations..."
@@ -91,8 +99,9 @@ echo "Components successfully implemented and tested:"
 echo "- Docker Socket Proxy: Running on internal network"
 echo "- Homepage: Accessible at http://$BIND_ADDRESS:$HOMEPAGE_PORT with labels for service discovery"
 echo "- WakaAPI: Accessible at http://$BIND_ADDRESS:$WAKAAPI_PORT with proper configuration"
+echo "- Mailhog: Accessible at http://$BIND_ADDRESS:$MAILHOG_UI_PORT with SMTP on port $MAILHOG_SMTP_PORT"
 echo "- Shared Network: $TSYSDEVSTACK_NETWORK_NAME"
 echo ""
 echo "MVP Stack is ready for use!"
 
-exit 0
+exit 0

artifacts/SupportStack/BuildTheStack.txt

@@ -1,248 +0,0 @@
-# TSYSDevStack SupportStack Demo Builder
-
-## Objective
-Create an out-of-the-box, localhost-bound only, ephemeral Docker volume-only demonstration version of the SupportStack components documented in the ./docs/VendorList-SupportStack.md file.
-
-## MVP Test Run Objective
-Create a proof of concept with docker-socket-proxy, homepage, and wakaapi components that demonstrate proper homepage integration via Docker Compose labels. This MVP will serve as a validation of the full approach before proceeding with the complete stack implementation.
-
-## Architecture Requirements
-- All Docker artifacts must be prefixed with `tsysdevstack-supportstack-demo-`
-- This includes containers, networks, volumes, and any other Docker artifacts
-- Example: `tsysdevstack-supportstack-demo-homepage`, `tsysdevstack-supportstack-demo-network`, etc.
-- Run exclusively on localhost (localhost binding only)
-- Ephemeral volumes only (no persistent storage)
-- Resource limits set for single-user demo capacity
-- No external network access (localhost bound only)
-- Components: docker-socket-proxy, portainer, homepage as foundational elements
-- All artifacts must go into artifacts/SupportStack directory to keep the directory well organized and avoid cluttering the root directory
-- Homepage container needs direct access to Docker socket for labels to auto-populate (not through proxy)
-- Docker socket proxy is for other containers that need Docker access but don't require direct socket access
-- Portainer can use docker-socket-proxy for read-only access, but homepage needs direct socket access
-- All containers need proper UID/GID mapping for security
-- Docker group GID must be mapped properly for containers using Docker socket
-- Non-Docker socket using containers should use invoking UID/GID
-
-## Development Methodology
-- Strict Test Driven Development (TDD) process
-- Write test → Execute test → Test fails → Write minimal code to pass test
-- 75%+ code coverage requirement
-- 100% test pass requirement
-- Component-by-component development approach
-- Complete one component before moving to the next
-- Apply TDD for every change, no matter how surgical
-- Test changes right after implementation as atomically as possible
-- Each fix or modification should be accompanied by a specific test to verify the issue
-- Ensure all changes are validated immediately after implementation
-
-## MVP Component Development Sequence (Test Run) ✅ COMPLETED ✅ MVP FULLY IMPLEMENTED AND TESTED
-1. **MVP**: docker-socket-proxy, homepage, wakaapi (each must fully satisfy Definition of Done before proceeding) ✅ COMPLETED ✅ MVP FULLY IMPLEMENTED AND TESTED
-   - docker-socket-proxy: Enable Docker socket access for containers that need it (not homepage) ✅ COMPLETED ✅ MVP FULLY IMPLEMENTED AND TESTED
-   - homepage: Configure to access Docker socket directly for automatic label discovery ✅ COMPLETED ✅ MVP FULLY IMPLEMENTED AND TESTED
-   - wakaapi: Integrate with homepage using proper labels ✅ COMPLETED ✅ MVP FULLY IMPLEMENTED AND TESTED
-   - All services must utilize Docker Compose labels to automatically show up in homepage ✅ COMPLETED ✅ MVP FULLY IMPLEMENTED AND TESTED
-   - Implement proper service discovery for homepage integration using gethomepage labels ✅ COMPLETED ✅ MVP FULLY IMPLEMENTED AND TESTED
-   - Ensure all components are properly labeled with homepage integration labels ✅ COMPLETED ✅ MVP FULLY IMPLEMENTED AND TESTED
-   - Implement proper startup ordering using depends_on with health checks ✅ COMPLETED ✅ MVP FULLY IMPLEMENTED AND TESTED
-   - Homepage container requires direct Docker socket access for automatic service discovery ✅ COMPLETED ✅ MVP FULLY IMPLEMENTED AND TESTED
-   - Docker socket proxy provides controlled access for other containers ✅ COMPLETED ✅ MVP FULLY IMPLEMENTED AND TESTED
-   - All containers must have proper UID/GID mapping for security ✅ COMPLETED ✅ MVP FULLY IMPLEMENTED AND TESTED
-
-## Component Completion Validation ✅ MVP COMPLETED
-- Each component must pass health checks for 5 consecutive minutes before moving to the next ✅ MVP COMPLETED
-- All tests must pass with 100% success rate before moving to the next component ✅ MVP COMPLETED
-- Resource utilization must be within specified limits before moving to the next component ✅ MVP COMPLETED
-- Integration tests with previously completed components must pass before moving forward ✅ MVP COMPLETED
-- Homepage must automatically detect and display all services with proper labels ✅ MVP COMPLETED
-- Specific validation checkpoints after each service deployment:
-  - docker-socket-proxy: Validate Docker socket access and network connectivity to Docker daemon ✅ COMPLETED
-  - homepage: Validate homepage starts and can connect to Docker socket directly, verify UI is accessible ✅ COMPLETED
-  - wakaapi: Validate service starts and can be integrated into homepage with proper labels ✅ COMPLETED
-- Each service must be validated in homepage dashboard after integration ✅ MVP COMPLETED
-- Detailed homepage integration validation steps:
-  - Verify service appears in homepage dashboard with correct name and icon ✅ MVP COMPLETED
-  - Confirm service status shows as healthy in homepage ✅ MVP COMPLETED
-  - Validate service URL in homepage correctly links to the service ✅ MVP COMPLETED
-  - Verify service group assignment in homepage is correct ✅ MVP COMPLETED
-  - Check that any configured widgets appear properly in homepage ✅ MVP COMPLETED
-  - Homepage must automatically discover services via Docker labels without manual configuration ✅ MVP COMPLETED
-  - Validate Docker socket connectivity for automatic service discovery ✅ MVP COMPLETED
-  - Confirm homepage can access and display service status information ✅ MVP COMPLETED
-- Update STATUS.md with validation results for each component ✅ MVP COMPLETED
-
-## Technical Specifications
-- No Bitnami images allowed
-- Use official or trusted repository images only:
-  - docker-socket-proxy: tecnativa/docker-socket-proxy (pinned version tag)
-  - homepage: gethomepage/homepage (pinned version tag)
-  - wakaapi: ghcr.io/ekkinox/wakaapi (pinned version tag)
-- Implement Docker Compose orchestration
-- Use Docker named volumes for ephemeral storage
-- Implement proper resource limits in docker-compose.yml: CPU: 0.5-1.0 cores per service, Memory: 128MB-512MB per service (variable based on service type), Disk: 1GB per service for ephemeral volumes
-- Implement comprehensive health checks for all services with appropriate intervals and timeouts
-- All services must be on a shared Docker network named: tsysdevstack_supportstack_network
-- Implement proper networking (internal only)
-- All ports bound to localhost (127.0.0.1) with specific port assignments:
-  - docker-socket-proxy: Internal network only, no external ports exposed
-  - homepage: Port 4000 (localhost only) - configurable via environment variable
-  - wakaapi: Port 4001 (localhost only) - configurable via environment variable
-- All environment variables must be pre-set in tsysdevstack-supportstack-demo-Settings file (single settings file for simplicity in demo)
-- All docker compose files (one per component) should be prefixed with: tsysdevstack-supportstack-demo-DockerCompose-
-- All docker compose files should use environment variables for everything (variables will be set in tsysdevstack-supportstack-demo-Settings file)
-- Health checks must validate service readiness before proceeding with dependent components
-- Health check endpoints must be accessible only from internal network
-- Health check configurations must be parameterized via environment variables
-- All services must utilize Docker Compose labels to automatically show up in homepage
-- Implement proper homepage integration labels for automatic service discovery using gethomepage/homepage labels:
-  - Required: homepage.group, homepage.name, homepage.icon
-  - Optional: homepage.href, homepage.description, homepage.widget.type, homepage.widget.url, homepage.widget.key, homepage.widget.fields, homepage.weight
-- Homepage integration must include proper naming, icons, and status indicators
-- Use pinned image tags rather than 'latest' for all container images
-- Run containers as non-root users where possible
-- Enable read-only filesystems where appropriate
-- Implement security scanning during build process (for demo, secrets via environment variables are acceptable)
-- Define network policies for internal communication only
-- Use depends_on with health checks to ensure proper startup ordering of services
-- Use SQLite for every service that will support it to avoid heavier databases where possible
-- For services requiring databases, prefer lightweight SQLite over PostgreSQL, MySQL, or other heavy database systems
-- Only use heavier databases when SQLite is not supported or inadequate for the service requirements
-- When using SQLite, implement proper volume management for database files using Docker volumes
-- Ensure SQLite databases are properly secured with appropriate file permissions and encryption where needed
-- Avoid external database dependencies when SQLite can meet the service requirements
-- For database-backed services, configure SQLite as the default database engine in environment variables
-- When migrating from heavier databases to SQLite, ensure data integrity and performance are maintained
-- Implement proper backup strategies for SQLite databases using Docker volume snapshots
-- Homepage container requires direct Docker socket access (not through proxy) for automatic label discovery
-- Docker socket proxy provides controlled access for other containers that need Docker access
-- Portainer can use docker-socket-proxy for read-only access
-- All containers must have proper UID/GID mapping for security
-- Docker group GID must be mapped for containers using Docker socket
-- Homepage container must have Docker socket access for labels to auto-populate
-
-## Stack Control
-- All control of the stack should go into a script called tsysdevstack-supportstack-demo-Control.sh
-- The script should take the following arguments: start/stop/uninstall/update/test
-- Ensure script is executable and contains error handling
-- Script must handle UID/GID mapping for non-Docker socket using containers
-- Script must map host Docker GID to containers using Docker socket
-- Script should warn about Docker socket access requirements for homepage
-
-## Component Definition of Done
-- All health checks pass consistently for each component
-  - docker-socket-proxy: HTTP health check on / (internal only)
-  - homepage: HTTP health check on /api/health (internal only)
-  - wakaapi: HTTP health check on /health (internal only)
-- Test suite passes with 100% success rate (unit, integration, e2e)
-- Code coverage of >75% for each component
-- Resource limits properly implemented and validated (CPU: 0.5-1.0 cores, Memory: 128MB-512MB, Disk: 1GB per service)
-- All services properly bound to localhost only
-- Proper error handling and logging implemented (with retry logic and exponential backoff)
-- Documentation and configuration files created
-- Component successfully starts, runs, and stops without manual intervention
-- Component properly integrates with other components without conflicts
-- Automated self-recovery mechanisms implemented for common failure scenarios
-- Performance benchmarks met for single-user demo capacity (apply reasonable defaults based on service type)
-- Security scans completed and passed (run as non-root, read-only filesystems where appropriate)
-- No hard-coded values; all configuration via environment variables
-- All dependencies properly specified and resolved using depends_on with health checks
-- Component properly labeled with homepage integration labels (homepage.group, homepage.name, homepage.icon, etc.)
-- Container uses pinned image tags rather than 'latest'
-- Services validate properly in homepage after integration
-- Homepage container has direct Docker socket access for automatic service discovery
-- Homepage automatically discovers and displays services with proper labels
-- Homepage validates Docker socket connectivity and service discovery
-- All homepage integration labels are properly applied and validated
-- Services appear in homepage with correct grouping, naming, and icons
-- Homepage container has direct Docker socket access for automatic label discovery
-- Docker socket proxy provides access for other containers that need Docker access
-- Proper UID/GID mapping implemented for all containers
-- Docker group GID properly mapped for containers using Docker socket
-- All warnings addressed and resolved during implementation
-
-## Testing Requirements
-- Unit tests for each component configuration
-- Integration tests for component interactions
-- End-to-end tests for the complete stack
-- Performance tests to validate resource limits
-- Security tests for localhost binding
-- Health check tests for all services
-- Coverage report generation
-- Continuous test execution during development
-- Automated test suite execution for each component before moving to the next
-- End-to-end validation tests after each component integration
-
-## Error Resolution Strategy
-- Implement autonomous error detection and resolution
-- Automatic retry mechanisms for transient failures with exponential backoff (base delay of 5s, max 5 attempts)
-- Fallback configurations for compatibility issues
-- Comprehensive logging for debugging
-- Graceful degradation for optional components
-- Automated rollback for failed deployments
-- Self-healing mechanisms for common failure scenarios
-- Automated restart policies with appropriate backoff strategies
-- Deadlock detection and resolution mechanisms
-- Resource exhaustion monitoring and mitigation
-- Automated cleanup of failed component attempts
-- Persistent state recovery mechanisms
-- Fail-safe modes for critical components
-- Circuit breaker patterns for service dependencies
-- Specific timeout values for operations:
-  - Docker socket proxy connection timeout: 30 seconds
-  - Homepage startup timeout: 60 seconds
-  - Wakaapi initialization timeout: 45 seconds
-  - Service health check timeout: 10 seconds
-  - Docker Compose startup timeout: 120 seconds per service
-- If unable to resolve an issue after multiple attempts, flag it in collab/SupportStack/HUMANHELP.md and move on
-- Maintain running status reports in collab/SupportStack/STATUS.md
-- Use git commit heavily to track progress
-- Push to remote repository whenever a component is fully working/tested/validated
-- Check Docker logs for all containers during startup and health checks to identify issues
-- Monitor container logs continuously for error patterns and failure indicators
-- Implement log analysis for common failure signatures and automatic remediation
-
-## Autonomous Operation Requirements
-- Project must be capable of running unattended for 1-2 days without manual intervention
-- All components must implement self-monitoring and self-healing
-- Automated monitoring of resource usage with alerts if limits exceeded
-- All failure scenarios must have automated recovery procedures
-- Consistent state maintenance across all components
-- Automated cleanup of temporary resources
-- Comprehensive logging for troubleshooting without human intervention
-- Built-in validation checks to ensure continued operation
-- Automatic restart of failed services with appropriate retry logic
-- Prevention of resource leaks and proper cleanup on shutdown
-
-## Qwen Optimization
-- Structured for autonomous execution
-- Clear task decomposition
-- Explicit success/failure criteria
-- Self-contained instructions
-- Automated validation steps
-- Progress tracking mechanisms
-
-## Output Deliverables
-- Directory structure in artifacts/SupportStack
-- Environment variables file: TSYSDevStack-SupportStack-Demo-Settings
-- Control script: TSYSDevStack-SupportStack-Demo-Control.sh (with start/stop/uninstall/update/test arguments)
-- Docker Compose files prefixed with: TSYSDevStack-SupportStack-Demo-DockerCompose-
-- Component configuration files
-- Test suite (unit, integration, e2e)
-- Coverage reports
-- Execution logs
-- Documentation files
-- Health check scripts and configurations
-- Component readiness and liveness check definitions
-- Automated validation scripts for component completion
-- Monitoring and alerting configurations
-
-The implementation should work autonomously, handling errors and resolving configuration issues without human intervention while strictly adhering to the TDD process.
-
-## Production Considerations
-- For production implementation, additional items will be addressed including:
-  - Enhanced monitoring and observability with centralized logging
-  - Advanced security measures (secrets management, network policies, etc.)
-  - Performance benchmarks and optimization
-  - Configuration management with separation of required vs optional parameters
-  - Advanced documentation (architecture diagrams, troubleshooting guides, etc.)
-  - Production-grade error handling and recovery procedures
-  - All deferred items will be tracked in collab/SupportStack/ProdRoadmap.md