TSYSDevStack-SupportStack-LocalWorkstation/demo/docs/troubleshooting/README.md

# TSYS Developer Support Stack - Troubleshooting Guide

## Common Issues and Solutions

### Services Not Starting

#### Issue: Docker daemon not running
**Symptoms**: `Cannot connect to the Docker daemon`
**Solution**:
```bash
sudo systemctl start docker
sudo systemctl enable docker
```

#### Issue: Port conflicts
**Symptoms**: `Port already in use` errors
**Solution**:
```bash
# Check what's using the port
netstat -tulpn | grep :4000

# Kill conflicting process
sudo fuser -k 4000/tcp
```

#### Issue: Environment variables not set
**Symptoms**: `Variable not found` errors
**Solution**:
```bash
# Check demo.env exists and is populated
cat demo.env

# Re-run user detection
./scripts/demo-stack.sh deploy
```

### Health Check Failures

#### Issue: Services stuck in "starting" state
**Symptoms**: Health checks timeout
**Solution**:
```bash
# Check service logs
docker compose logs [service-name]

# Restart specific service
docker compose restart [service-name]

# Check resource usage
docker stats
```

#### Issue: Network connectivity problems
**Symptoms**: Services can't reach each other
**Solution**:
```bash
# Check network exists
docker network ls | grep tsysdevstack

# Recreate network
docker network create tsysdevstack_supportstack-demo

# Restart stack
docker compose down && docker compose up -d
```

### Permission Issues

#### Issue: File ownership problems
**Symptoms**: `Permission denied` errors
**Solution**:
```bash
# Check current user
id

# Verify UID/GID detection
cat demo.env | grep -E "(UID|GID)"

# Fix volume permissions
sudo chown -R $(id -u):$(id -g) /var/lib/docker/volumes/tsysdevstack_*
```

#### Issue: Docker group access
**Symptoms**: `Got permission denied` errors
**Solution**:
```bash
# Add user to docker group
sudo usermod -aG docker $USER

# Log out and back in, or run:
newgrp docker
```

### Service-Specific Issues

#### Pi-hole DNS Issues
**Symptoms**: DNS resolution failures
**Solution**:
```bash
# Check Pi-hole status
docker exec tsysdevstack-supportstack-demo-pihole pihole status

# Test DNS resolution
nslookup google.com localhost

# Restart DNS service
docker exec tsysdevstack-supportstack-demo-pihole pihole restartdns
```

#### Grafana Data Source Connection
**Symptoms**: InfluxDB data source not working
**Solution**:
```bash
# Test InfluxDB connectivity
curl http://localhost:4008/ping

# Check Grafana logs
docker compose logs grafana

# Verify data source configuration
# Navigate to: http://localhost:4009/datasources
```

#### Dockhand Container Access
**Symptoms**: Can't manage containers
**Solution**:
```bash
# Check Dockhand logs
docker compose logs dockhand

# Verify Docker socket access
docker exec tsysdevstack-supportstack-demo-dockhand docker version

# Restart Dockhand
docker compose restart dockhand
```

### Performance Issues

#### Issue: High memory usage
**Symptoms**: System becomes slow
**Solution**:
```bash
# Check resource usage
docker stats

# Set memory limits in docker-compose.yml
# Add to each service:
deploy:
  resources:
    limits:
      memory: 512M

# Restart with new limits
docker compose up -d
```

#### Issue: Slow startup times
**Symptoms**: Services take >60 seconds to start
**Solution**:
```bash
# Check system resources
free -h
df -h

# Pull images in advance
docker compose pull

# Check for conflicting services
docker ps -a
```

## Diagnostic Commands

### System Information
```bash
# System info
uname -a
free -h
df -h

# Docker info
docker version
docker compose version
docker system df
```

### Service Status
```bash
# All services status
docker compose ps

# Service logs
docker compose logs

# Resource usage
docker stats

# Network info
docker network ls
docker network inspect tsysdevstack_supportstack-demo
```

### Health Checks
```bash
# Test all endpoints
for port in 4000 4005 4006 4007 4008 4009 4010 4011 4012 4013 4014 4015 4017 4018; do
    curl -f -s --max-time 5 "http://localhost:$port" && echo "Port $port: OK" || echo "Port $port: FAIL"
done
```

## Getting Additional Help

### Check Logs First
```bash
# All service logs
docker compose logs

# Specific service logs
docker compose logs [service-name]

# Follow logs in real-time
docker compose logs -f [service-name]
```

### Validation Scripts
```bash
# Run comprehensive validation
./scripts/validate-all.sh

# Run test suite
./scripts/demo-test.sh full

# Run specific test categories
./scripts/demo-test.sh security
./scripts/demo-test.sh permissions
./scripts/demo-test.sh network
```

### Reset and Restart
```bash
# Complete reset (removes all data)
docker compose down -v
docker system prune -f

# Fresh deployment
./scripts/demo-stack.sh deploy
```

## Known Limitations

### Demo Mode Restrictions
- No data persistence between restarts
- Hardcoded demo credentials
- No external network access
- No security hardening

### Resource Requirements
- Minimum 8GB RAM recommended
- Minimum 10GB disk space
- Docker daemon must be running
- User must be in docker group

### Port Requirements
All ports 4000-4018 must be available:
- 4000: Homepage
- 4005: Docker Socket Proxy
- 4006: Pi-hole
- 4007: Portainer
- 4008: InfluxDB
- 4009: Grafana
- 4010: Draw.io
- 4011: Kroki
- 4012: Atomic Tracker
- 4013: ArchiveBox
- 4014: Tube Archivist
- 4015: Wakapi
- 4017: MailHog
- 4018: Atuin

## Contact and Support

If issues persist after trying these solutions:

1. Document the exact error message
2. Include system information (OS, Docker version)
3. List steps to reproduce the issue
4. Include relevant log output
5. Specify demo vs production context

Remember: This is a demo configuration designed for development and testing purposes only.