Skip to content

Troubleshooting

This section provides comprehensive troubleshooting guides for common issues with the brennan.page homelab.

Quick Diagnosis

System Status Check

# Quick system health check
ssh -i ~/.omg-lol-keys/id_ed25519 -T -o BatchMode=yes root@159.203.44.169 "
  echo '=== System Status ==='
  docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'
  echo -e '\n=== Resource Usage ==='
  free -h | head -2
  df -h | head -2
  echo -e '\n=== Network Status ==='
  curl -I https://brennan.page
"

Service Health Check

# Check all critical services
services=("docker.brennan.page" "monitor.brennan.page" "files.brennan.page" "wiki.brennan.page")
for service in "${services[@]}"; do
  echo "Checking $service..."
  curl -s -o /dev/null -w "%{http_code} $service\n" "https://$service"
done

Common Issues

Service Not Starting

  • Symptoms: Service shows as "Exited" or "Restarting", HTTP 502/503 errors
  • Quick Fix: docker compose restart or docker compose down && docker compose up -d
  • Details: See Service Issues

Database Connection Issues

  • Symptoms: Service can't connect to database, connection timeouts
  • Quick Fix: docker restart postgresql
  • Details: See Database Issues

SSL/TLS Certificate Issues

  • Symptoms: HTTPS not working, certificate errors
  • Quick Fix: docker restart caddy
  • Details: See Network Issues

Performance Issues

  • Symptoms: Slow response times, high resource usage
  • Quick Fix: docker system prune -f
  • Details: See Performance Issues

Service-Specific Troubleshooting

Phase 1 Services

Phase 2 Services

Phase 3 Services

Phase 4 Services

Emergency Procedures

Complete System Outage

  1. Assess Impact: Check system status
  2. Restart Services: docker compose restart
  3. Check Connectivity: ping -c 4 8.8.8.8

Data Recovery

Getting Help

Before Opening Support Ticket

  • Checked system status
  • Reviewed service logs
  • Tested basic connectivity
  • Attempted basic restarts

Information to Include

  • System status output
  • Complete error messages
  • Recent changes
  • Steps already taken

References