TSYSDevStack-SupportStack-LocalWorkstation/demo/docs/troubleshooting

TSYS Developer Support Stack - Troubleshooting Guide

Note: All commands in this guide assume your working directory is the demo/ folder of the repository. Run cd demo first if needed.

Common Issues and Solutions

Services Not Starting

Issue: Docker daemon not running

Symptoms: Cannot connect to the Docker daemon Solution:

sudo systemctl start docker
sudo systemctl enable docker

Issue: Port conflicts

Symptoms: Port already in use errors Solution:

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

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

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

# Check network exists
docker network ls | grep kneldevstack

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

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

Permission Issues

Issue: File ownership problems

Symptoms: Permission denied errors Solution:

# 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/kneldevstack-supportstack-demo_*

Issue: Docker group access

Symptoms: Got permission denied errors Solution:

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

# Check Pi-hole status
docker exec kneldevstack-supportstack-demo-pihole pihole status

# Test DNS resolution
nslookup google.com localhost

# Restart DNS service
docker exec kneldevstack-supportstack-demo-pihole pihole restartdns

Grafana Data Source Connection

Symptoms: InfluxDB data source not working Solution:

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

# Check Dockhand logs
docker compose logs dockhand

# Verify Docker socket access (check socket is mounted)
docker inspect kneldevstack-supportstack-demo-dockhand --format '{{.Mounts}}' | grep docker.sock

# Restart Dockhand
docker compose restart dockhand

Performance Issues

Issue: High memory usage

Symptoms: System becomes slow Solution:

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

# 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

# System info
uname -a
free -h
df -h

# Docker info
docker version
docker compose version
docker system df

Service Status

# All services status
docker compose ps

# Service logs
docker compose logs

# Resource usage
docker stats

# Network info
docker network ls
docker network inspect kneldevstack-supportstack-demo

Health Checks

# Test all endpoints
for port in 4000 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

# 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

# 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

# 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

The following host ports must be available (not a continuous range):

• 4000: Homepage
• 4006: Pi-hole
• 4007: Dockhand
• 4008: InfluxDB
• 4009: Grafana
• 4010: Draw.io
• 4011: Kroki
• 4012: Atomic Tracker
• 4013: ArchiveBox
• 4014: Tube Archivist
• 4015: Wakapi
• 4017: MailHog
• 4018: Atuin

Note: Docker Socket Proxy (4005), Redis, and Elasticsearch are internal-only and do not require host ports.

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.