TSYSDevStack/SupportStack/demo/README.md

# 🚀 TSYS Developer Support Stack - Demo

<div align="center">

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Docker](https://img.shields.io/badge/Docker-Ready-blue.svg)](https://www.docker.com/)
[![FOSS](https://img.shields.io/badge/FOSS-Only-green.svg)](https://www.fsf.org/)
[![Demo](https://img.shields.io/badge/Mode-Demo-orange.svg)](#)

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

</div>

---

## 📖 Table of Contents

- [🚀 Quick Start](#-quick-start)
- [📋 Services Overview](#-services-overview)
- [🔧 Technical Configuration](#-technical-configuration)
- [🔐 Demo Credentials](#-demo-credentials)
- [📊 Service Dependencies](#-service-dependencies)
- [🧪 Testing](#-testing)
- [🔍 Troubleshooting](#-troubleshooting)
- [📁 Data Management](#-data-management)
- [🔄 Updates & Maintenance](#-updates--maintenance)
- [📚 Documentation](#-documentation)
- [🚨 Security Notes](#-security-notes)
- [📞 Support](#-support)

---

## 🚀 Quick Start

<div align="center">

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

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

</div>

🎉 **Access all services via the Homepage dashboard at** **[http://localhost:${HOMEPAGE_PORT}](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|stop|restart]` |
| **demo-test.sh** | Comprehensive QA and validation | `./demo-test.sh [full|security|permissions]` |
| **demo.env** | All environment variables | Source of configuration |

---

## 📋 Services Overview

### 🛠️ Developer Tools
| Service | Port | Description | 🌐 Access |
|---------|------|-------------|-----------|
| **Homepage** | 4000 | Central dashboard for service discovery | [Open](http://localhost:4000) |
| **Atuin** | 4001 | Shell history synchronization | [Open](http://localhost:4001) |
| **Wakapi** | 4002 | Time tracking for developers | [Open](http://localhost:4002) |
| **ArchiveBox** | 4003 | Web archiving solution | [Open](http://localhost:4003) |
| **Tube Archivist** | 4004 | YouTube video archiving | [Open](http://localhost:4004) |
| **MailHog** | 4005 | Email testing for development | [Open](http://localhost:4005) |

### 🏗️ Infrastructure Services
| Service | Port | Description | 🌐 Access |
|---------|------|-------------|-----------|
| **Pi-hole** | 4006 | DNS-based ad blocking and monitoring | [Open](http://localhost:4006) |
| **Docker Socket Proxy** | 4013 | Infrastructure | Secure Docker socket API proxy | [Internal](#) |
| **Portainer** | 4007 | Web-based container management | [Open](http://localhost:4007) |

### 📊 Monitoring & Observability
| Service | Port | Description | 🌐 Access |
|---------|------|-------------|-----------|
| **InfluxDB** | 4008 | Time series database for metrics | [Open](http://localhost:4008) |
| **Grafana** | 4009 | Analytics and visualization platform | [Open](http://localhost:4009) |

### 📚 Documentation & Diagramming
| Service | Port | Description | 🌐 Access |
|---------|------|-------------|-----------|
| **Draw.io** | 4010 | Web-based diagramming application | [Open](http://localhost:4010) |
| **Kroki** | 4011 | Diagrams as a service | [Open](http://localhost:4011) |

---

## 🔧 Technical Configuration

### 🐳 Docker Integration

<div align="center">

```yaml
# 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"
```

</div>

### ⚙️ 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:

```yaml
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](http://localhost:4009) |
| **Portainer** | `admin` | `demo_password` | [Login](http://localhost:4007) |

---

## 📊 Service Dependencies

```mermaid
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

<div align="center">

```bash
# 🎯 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
```

</div>

### ✅ Manual Validation Commands

```bash
# 📊 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
```bash
# 🔧 Check Docker daemon
docker info

# 🌐 Check network
docker network ls | grep tsysdevstack_supportstack

# 🔄 Recreate network
docker network create tsysdevstack_supportstack
```

#### Port conflicts
```bash
# 🔍 Check port usage
netstat -tulpn | grep :400

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

#### Health check failures
```bash
# 🔍 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<br>Check that port 53 is available on the host |
| **Database connection** | Grafana-InfluxDB | Verify both services are on the same network<br>Check database connectivity: `curl http://localhost:4008/ping` |
| **Container access** | Portainer | Ensure container socket is properly mounted<br>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

```bash
# 📋 List volumes
docker volume ls | grep tsysdevstack

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

---

## 🔄 Updates & Maintenance

### 📦 Image Updates

<div align="center">

```bash
# 🔄 Pull latest images
docker compose pull

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

</div>

### ⚙️ 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](PRD.md) |
| **🤖 Development Guidelines** | Development principles and standards | [AGENTS.md](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

---

<div align="center">

**🎉 Happy Developing!**

*Last updated: 2025-11-13*

</div>