TSYSDevStack-SupportStack-LocalWorkstation/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	kneldevstack-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	kneldevstack-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
Atomic Tracker	4012	Habit tracking and personal dashboard	Open
Wakapi	4015	Open-source WakaTime alternative for time tracking	Open
MailHog	4017	Web and API based SMTP testing tool	Open
Atuin	4018	Magical shell history synchronization	Open

📚 Archival & Content Management

Service	Port	Description	🌐 Access
ArchiveBox	4013	Web archiving solution	Open
Tube Archivist	4014	YouTube video archiving	Open

🏗️ Infrastructure Services

Service	Port	Description	🌐 Access
Pi-hole	4006	DNS-based ad blocking and monitoring	Open
Dockhand	4007	Modern Docker management UI	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
Dockhand (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
Dockhand	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 (Dockhand)	Docker socket (direct mount)	🔗 Required
Visualization Platform (Grafana)	Time Series Database (InfluxDB)	🔗 Required
Video Archiving (Tube Archivist)	Redis (ta-redis) + Elasticsearch (ta-elasticsearch)	🔗 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 kneldevstack-supportstack-demo

# 🔄 Recreate network
docker network create --subnet 192.168.3.0/24 --gateway 192.168.3.1 kneldevstack-supportstack-demo-network

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	Dockhand	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 kneldevstack

# 🗑️ 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