foundation/.claude/skills/foundation/troubleshoot-docker.md

Troubleshoot Docker

Diagnostic steps and solutions for common Docker issues in the Foundation framework.

When to use this skill

• User reports "Docker not working"
• User mentions "containers won't start"
• User reports "connection refused" errors
• User asks "why isn't the app working?"
• User mentions "port already in use"
• User reports "permission denied" errors
• Application not accessible via browser
• Database connection failures

Diagnostic Steps

Step 1: Check Container Status

1. List All Containers

   docker compose ps
   

   Expected Output:

   NAME                    STATUS              PORTS
   foundation-app          Up X minutes        0.0.0.0:8000->80/tcp
   foundation-db           Up X minutes        0.0.0.0:3306->3306/tcp
   foundation-phpmyadmin   Up X minutes        0.0.0.0:8080->80/tcp
   

   All containers should show "Up" status.

Step 2: Check Container Logs

2. View Container Logs

   # All containers
   docker compose logs
   
   # Specific container
   docker compose logs app
   docker compose logs db
   docker compose logs phpmyadmin
   
   # Follow logs in real-time
   docker compose logs -f app
   

   Look for error messages, warnings, or stack traces.

Step 3: Check Port Availability

3. Check if Ports are Available

   # Check port 8000 (app)
   sudo lsof -i :8000
   
   # Check port 8080 (phpmyadmin)
   sudo lsof -i :8080
   
   # Check port 3306 (mysql)
   sudo lsof -i :3306
   

   If output shows other processes using these ports, you have a port conflict.

Step 4: Verify Docker Service

4. Check Docker Daemon Status

   docker --version
   docker compose version
   systemctl status docker  # Linux
   

   Ensure Docker daemon is running.

Step 5: Test Application Access

5. Test HTTP Endpoints

   # Test app
   curl http://localhost:8000
   
   # Test phpMyAdmin
   curl http://localhost:8080
   

   Should return HTML content, not connection errors.

Common Issues and Solutions

Issue 1: Containers Won't Start

Symptoms:

• docker compose ps shows containers with "Exit" status
• Containers restart repeatedly

Diagnostic:

docker compose logs app
docker compose logs db

Solutions:

A) Port Conflict

# Find process using port
sudo lsof -i :8000

# Kill process or change port in docker-compose.yml

B) Configuration Error

# Check docker-compose.yml syntax
docker compose config

# Rebuild containers
make down
docker compose up -d --build

C) Previous Container Data Issues

# Remove containers and volumes
docker compose down -v

# Restart fresh
make up

Issue 2: Application Returns 500 Error

Symptoms:

• Browser shows "Internal Server Error"
• HTTP 500 status code

Diagnostic:

docker compose logs -f app
docker compose exec app tail -f storage/logs/app.log

Solutions:

A) Check File Permissions

# Fix permissions in container
docker compose exec app chown -R www-data:www-data storage/
docker compose exec app chmod -R 775 storage/

B) Check PHP Errors

# View PHP error log
docker compose exec app tail -f /var/log/apache2/error.log

C) Missing Dependencies

# Reinstall dependencies
make install

Issue 3: Database Connection Failed

Symptoms:

• "Connection refused" to database
• "SQLSTATE[HY000] [2002]" errors
• Application can't connect to MySQL

Diagnostic:

# Check database container
docker compose ps db

# Check database logs
docker compose logs db

# Test connection from app container
docker compose exec app mysql -h db -u foundation_user -pfoundation_password foundation

Solutions:

A) Database Container Not Running

# Restart database
docker compose restart db

# Check startup logs
docker compose logs db

B) Wrong Credentials

# Verify environment variables
docker compose exec app env | grep DB_

# Should show:
# DB_HOST=db
# DB_PORT=3306
# DB_DATABASE=foundation
# DB_USERNAME=foundation_user
# DB_PASSWORD=foundation_password

C) Database Not Initialized

# Import schema
docker compose exec -T db mysql -u foundation_user -pfoundation_password foundation < database/schema.sql

Issue 4: Port Already in Use

Symptoms:

• Error: "port is already allocated"
• Error: "bind: address already in use"

Diagnostic:

sudo lsof -i :8000
sudo lsof -i :8080
sudo lsof -i :3306

Solutions:

A) Stop Conflicting Service

# If Apache/Nginx is running
sudo systemctl stop apache2
# or
sudo systemctl stop nginx

# If MySQL is running
sudo systemctl stop mysql

B) Change Docker Ports

Edit docker-compose.yml:

services:
  app:
    ports:
      - "8001:80"  # Change 8000 to 8001

Then restart:

make down
make up

Issue 5: Permission Denied Errors

Symptoms:

• Can't write to files
• Can't create directories
• Permission denied in logs

Diagnostic:

# Check file ownership
docker compose exec app ls -la /var/www/html/storage

# Check user in container
docker compose exec app whoami

Solutions:

A) Fix Ownership (Linux/macOS)

export USER_ID=$(id -u) && export GROUP_ID=$(id -g)
make down
make up

B) Fix Permissions in Container

docker compose exec app chown -R www-data:www-data /var/www/html
docker compose exec app chmod -R 775 /var/www/html/storage

Issue 6: Changes Not Reflected

Symptoms:

• Code changes don't appear in browser
• Old version still running

Diagnostic:

# Check if volumes are mounted
docker compose exec app ls -la /var/www/html

Solutions:

A) Clear Caches

# Clear application cache
docker compose exec app rm -rf storage/cache/*

# Clear browser cache
# Use Ctrl+Shift+R or Cmd+Shift+R

B) Restart Container

docker compose restart app

C) Rebuild Container

make down
docker compose up -d --build

Issue 7: Slow Performance

Symptoms:

• Application very slow to respond
• High CPU/memory usage
• Timeouts

Diagnostic:

# Check container resource usage
docker stats

# Check logs for errors
docker compose logs app

Solutions:

A) Increase Docker Resources

In Docker Desktop: Settings → Resources → Increase CPU/Memory

B) Clear Logs

docker compose exec app rm -f storage/logs/*
docker compose exec app truncate -s 0 /var/log/apache2/error.log

C) Optimize Autoloader

make dump-autoload

Issue 8: Cannot Access Container Shell

Symptoms:

• make shell or docker compose exec app bash fails

Diagnostic:

docker compose ps app

Solutions:

A) Container Not Running

make up

B) Use Different Shell

docker compose exec app sh

Complete Reset Procedure

If all else fails, completely reset the environment:

# 1. Stop and remove everything
docker compose down -v

# 2. Remove dangling images
docker system prune -f

# 3. Rebuild from scratch
export USER_ID=$(id -u) && export GROUP_ID=$(id -g)
docker compose up -d --build

# 4. Reinstall dependencies
make install

# 5. Import database schema
docker compose exec -T db mysql -u foundation_user -pfoundation_password foundation < database/schema.sql

# 6. Verify
docker compose ps
curl http://localhost:8000

Diagnostic Command Checklist

Run these commands to gather diagnostic information:

# 1. Container status
docker compose ps

# 2. Container logs
docker compose logs --tail=50

# 3. Docker version
docker --version
docker compose version

# 4. Port availability
sudo lsof -i :8000
sudo lsof -i :8080
sudo lsof -i :3306

# 5. Disk space
df -h

# 6. Docker disk usage
docker system df

# 7. Network connectivity
docker compose exec app ping -c 3 db

# 8. Environment variables
docker compose exec app env | grep DB_

# 9. File permissions
docker compose exec app ls -la /var/www/html/storage

# 10. Test database connection
docker compose exec app mysql -h db -u foundation_user -pfoundation_password foundation -e "SELECT 1;"

Prevention Best Practices

1. Regular Cleanup

   docker system prune -f
   

2. Monitor Logs

   docker compose logs -f
   

3. Use Make Commands

   • Prefer make up over direct docker compose commands
   • Ensures consistent environment setup

4. Keep Docker Updated

   # Check for updates
   docker --version
   

5. Document Environment

   • Note any custom ports or configurations
   • Keep .env file up to date

Getting Help

If issues persist:

1. Collect Information:

   docker compose ps > debug-status.txt
   docker compose logs > debug-logs.txt
   docker compose config > debug-config.txt
   

2. Check Docker Documentation: https://docs.docker.com

3. Review Project Issues: Check if it's a known issue

4. System Requirements:

   • Docker Engine 20.10+
   • Docker Compose 2.0+
   • At least 4GB RAM allocated to Docker
   • 10GB free disk space

Quick Reference

# Status and logs
docker compose ps
docker compose logs -f app

# Restart
docker compose restart app
docker compose restart db

# Full reset
docker compose down -v
make up

# Access shell
make shell

# Check ports
sudo lsof -i :8000
sudo lsof -i :8080
sudo lsof -i :3306

# View resource usage
docker stats

# Clean up
docker system prune -f

# Rebuild
make down
docker compose up -d --build