TSYSDevStack/SupportStack/demo/README.md

🚀 TSYS Developer Support Stack - Demo

A comprehensive, demo-ready developer support services stack that enhances productivity and quality of life for the TSYS engineering team.

---

📖 Table of Contents

• 🚀 Quick Start
• 📋 Services Overview
• 🔧 Technical Configuration
• 🔐 Demo Credentials
• 📊 Service Dependencies
• 🧪 Testing
• 🔍 Troubleshooting
• 📁 Data Management
• 🔄 Updates & Maintenance
• 📚 Documentation
• 🚨 Security Notes
• 📞 Support

---

🚀 Quick Start

# 🎯 Demo deployment with dynamic user detection
./demo-stack.sh deploy

# 🔧 Comprehensive testing and validation
./demo-test.sh full

🎉 Access all services via the Homepage dashboard at http://localhost:${HOMEPAGE_PORT}

⚠️ Demo Configuration Only - This stack is designed for demonstration purposes with no data persistence.

---

🔧 Dynamic Deployment Architecture

📋 Environment Variables

All configuration is managed through demo.env and dynamic detection:

Variable	Description	Default
COMPOSE_PROJECT_NAME	Consistent naming prefix	tsysdevstack-supportstack-demo
UID	Current user ID	Auto-detected
GID	Current group ID	Auto-detected
DOCKER_GID	Docker group ID	Auto-detected
COMPOSE_NETWORK_NAME	Docker network name	tsysdevstack-supportstack-demo-network

🎯 Deployment Scripts

Script	Purpose	Usage
demo-stack.sh	Dynamic deployment with user detection	`./demo-stack.sh [deploy
demo-test.sh	Comprehensive QA and validation	`./demo-test.sh [full
demo.env	All environment variables	Source of configuration

---

📋 Services Overview

🛠️ Developer Tools

Service	Port	Description	🌐 Access
Homepage	4000	Central dashboard for service discovery	Open
Atuin	4001	Shell history synchronization	Open
Wakapi	4002	Time tracking for developers	Open
ArchiveBox	4003	Web archiving solution	Open
Tube Archivist	4004	YouTube video archiving	Open
MailHog	4005	Email testing for development	Open

🏗️ Infrastructure Services

Service	Port	Description	🌐 Access
Pi-hole	4006	DNS-based ad blocking and monitoring	Open
Docker Socket Proxy	4013	Infrastructure	Secure Docker socket API proxy
Portainer	4007	Web-based container management	Open

📊 Monitoring & Observability

Service	Port	Description	🌐 Access
InfluxDB	4008	Time series database for metrics	Open
Grafana	4009	Analytics and visualization platform	Open

📚 Documentation & Diagramming

Service	Port	Description	🌐 Access
Draw.io	4010	Web-based diagramming application	Open
Kroki	4011	Diagrams as a service	Open

---

🔧 Technical Configuration

🐳 Docker Integration

# Demo 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 Configuration

Setting	Variable	Description
Service Naming	${COMPOSE_PROJECT_NAME}-{service}	Dynamic container naming
Network	${COMPOSE_NETWORK_NAME}	Dedicated Docker network
User Mapping	${UID}:${GID}	Dynamic user detection
Docker Group	${DOCKER_GID}	Docker socket access
Volume Naming	${COMPOSE_PROJECT_NAME}_{service}_data	Consistent volumes
Restart Policy	unless-stopped	Automatic recovery

🔍 Health Check Endpoints

Service	Health Check Path	Status
Pi-hole (DNS Management)	HTTP GET /	✅ Active
Portainer (Container Management)	HTTP GET /	✅ Active
InfluxDB (Time Series Database)	HTTP GET /ping	✅ Active
Grafana (Visualization Platform)	HTTP GET /api/health	✅ Active
Draw.io (Diagramming Server)	HTTP GET /	✅ Active
Kroki (Diagrams as a Service)	HTTP GET /health	✅ Active

🏷️ Service Discovery Labels

All services include Homepage labels for auto-discovery:

labels:
  homepage.group: "Service category"
  homepage.name: "Display name"
  homepage.icon: "Appropriate icon"
  homepage.href: "Full URL"
  homepage.description: "Brief service description"

---

🔐 Demo Credentials

⚠️ Demo Configuration Only - Reset all credentials before production use

Service	Username	Password	🔗 Access
Grafana	admin	demo_password	Login
Portainer	admin	demo_password	Login

---

📊 Service Dependencies

graph TD
    A[Homepage Dashboard] --> B[All Services]
    C[Container Management] --> D[Container Socket Proxy]
    E[Visualization Platform] --> F[Time Series Database]
    G[All Other Services] --> H[No Dependencies]
    
    style A fill:#e1f5fe
    style C fill:#f3e5f5
    style E fill:#e8f5e8
    style G fill:#fff3e0

Service	Dependencies	Status
Container Management (Portainer)	Container Socket Proxy	🔗 Required
Visualization Platform (Grafana)	Time Series Database (InfluxDB)	🔗 Required
All Other Services	None	✅ Standalone

---

🧪 Testing & Validation

🤖 Automated Demo Testing

# 🎯 Full deployment and validation
./demo-stack.sh deploy && ./demo-test.sh full

# 🔍 Security compliance validation
./demo-test.sh security

# 👤 File ownership validation
./demo-test.sh permissions

# 🌐 Network isolation validation
./demo-test.sh network

✅ Manual Validation Commands

# 📊 Check service status with dynamic naming
docker compose ps

# 📋 View service logs
docker compose logs {service-name}

# 🌐 Test individual endpoints with variables
curl -f http://localhost:${HOMEPAGE_PORT}/
curl -f http://localhost:${INFLUXDB_PORT}/ping
curl -f http://localhost:${GRAFANA_PORT}/api/health

# 🔍 Validate user permissions
ls -la /var/lib/docker/volumes/${COMPOSE_PROJECT_NAME}_*/

---

🔍 Troubleshooting

🚨 Common Issues

Services not starting

# 🔧 Check Docker daemon
docker info

# 🌐 Check network
docker network ls | grep tsysdevstack_supportstack

# 🔄 Recreate network
docker network create tsysdevstack_supportstack

Port conflicts

# 🔍 Check port usage
netstat -tulpn | grep :400

# 🗑️ Kill conflicting processes
sudo fuser -k {port}/tcp

Health check failures

# 🔍 Check individual service health
docker compose exec {service} curl -f http://localhost:{internal-port}/health

# 🔄 Restart specific service
docker compose restart {service}

🛠️ Service-Specific Issues

Issue	Service	Solution
DNS issues	Pi-hole	Ensure Docker DNS settings allow custom DNS servers Check that port 53 is available on the host
Database connection	Grafana-InfluxDB	Verify both services are on the same network Check database connectivity: curl http://localhost:4008/ping
Container access	Portainer	Ensure container socket is properly mounted Check Container Socket Proxy service if used

---

📁 Data Management

🎭 Demo Mode Configuration

💡 No persistent data storage - All data resets on container restart

Feature	Configuration
Data Persistence	❌ Disabled (demo mode)
Storage Type	Docker volumes (temporary)
Data Reset	✅ Automatic on restart
Credentials	🔒 Hardcoded demo only

🗂️ Volume Management

# 📋 List volumes
docker volume ls | grep tsysdevstack

# 🗑️ Clean up all data
docker compose down -v

---

🔄 Updates & Maintenance

📦 Image Updates

# 🔄 Pull latest images
docker compose pull

# 🚀 Recreate with new images
docker compose up -d --force-recreate

⚙️ Configuration Changes

1. Edit docker-compose.yml
2. Apply changes: docker compose up -d
3. Verify with docker compose ps
4. Test functionality

---

📚 Documentation

Document	Purpose	Link
📋 Product Requirements	Business requirements and specifications	PRD.md
🤖 Development Guidelines	Development principles and standards	AGENTS.md
🌐 Service Documentation	Individual service guides	Service web interfaces

---

🚨 Security Notes

⚠️ Demo Configuration Only - Production Use Prohibited

🔒 Demo Security Model

• 🔓 Demo Credentials: Hardcoded for demonstration only
• 🚫 No Hardening: No encryption or security features
• 🌐 Network Isolation: Do not expose to external networks
• 🔄 Ephemeral Data: All data resets on container restart
• 📡 Docker Socket Proxy: Mandatory for all container operations

🛡️ Security Requirements

• Dynamic User Detection: Prevents root file ownership issues
• Docker Group Access: Required for socket proxy functionality
• Volume-First Storage: Docker volumes preferred over bind mounts
• Read-Only Host Access: Minimal host filesystem interaction
• Network Segregation: Services isolated in demo network

⚠️ Production Migration Warning

• Reset all credentials before production deployment
• Implement persistent data storage
• Add encryption and security hardening
• Configure proper backup and recovery
• Set up monitoring and alerting

---

📞 Support

🆘 Getting Help

1. 📖 Check troubleshooting section above
2. 📋 Review service logs: docker compose logs
3. 📚 Consult individual service documentation
4. 🔍 Check health status: docker compose ps

🐛 Issue Reporting

When reporting issues, please include:

• 📝 Full error messages
• 💻 System information
• 🔄 Reproduction steps
• ⚙️ Configuration snippets
• 🎭 Demo vs production context

---

🎉 Happy Developing!

Last updated: 2025-11-13