Docker-Local Troubleshooting Skill

Overview

This skill helps diagnose and fix common docker-local issues including:

• Container failures and crashes
• Port conflicts
• Permission errors
• Network connectivity problems
• Database connection issues
• DNS and SSL problems

Activation

Use this skill when:

• User reports Docker errors
• Services won't start
• Projects aren't accessible
• Database connections fail
• SSL/certificate issues
• General "it's not working" complaints

MANDATORY: Prerequisite Check

Before ANY docker-local command, verify installation:

which docker-local > /dev/null 2>&1

If docker-local is NOT found:

1. Stop and ask the user if they want to install it
2. If yes, install via:

   composer global require mwguerra/docker-local

3. Add to PATH:

   export PATH="$HOME/.composer/vendor/bin:$PATH"

4. Initialize:

   docker-local init

5. Verify:

   which docker-local && docker-local --version

Diagnostic Process

1. Quick Fix (Recommended First Step)

Use the

fix

command for automatic diagnosis and resolution:

# Run all checks and auto-fix what's possible
docker-local fix

# Target specific areas
docker-local fix --dns         # Only check/fix DNS issues
docker-local fix --docker      # Only check/fix Docker daemon
docker-local fix --services    # Only check/fix container services
docker-local fix --hosts       # Only check/fix /etc/hosts

# Additional options
docker-local fix --verbose     # Show detailed diagnostic info
docker-local fix --dry-run     # Show what would be fixed without making changes

The fix command automatically detects and resolves:

• Docker daemon not running
• Stopped containers
• Missing systemd-resolved configuration for *.test DNS
• Missing dnsmasq configuration
• /etc/hosts not configured

2. Gather Additional Information

# Check docker-local status
docker-local status

# View recent logs
docker-local logs --tail=50

# Check Docker system
docker info
docker system df

3. Common Issue Patterns

Docker Not Running

Error: Docker is not running

Diagnosis:

docker info 2>&1
systemctl status docker  # Linux

Fix:

# Linux
sudo systemctl start docker

# macOS
open -a Docker

# Windows (WSL2)
# Start Docker Desktop from Windows Start Menu

Port Already in Use

Error: Port 3306 already in use

Diagnosis:

# Find what's using the port
lsof -i :3306
netstat -tulpn | grep 3306

# Common ports to check:
# 80, 443 - Traefik/HTTP
# 3306 - MySQL
# 5432 - PostgreSQL
# 6379 - Redis
# 9000, 9001 - MinIO
# 1025, 8025 - Mailpit

Fix:

# Kill the process using the port
kill $(lsof -t -i:3306)

# Or change port in config
# Edit ~/.config/docker-local/config.json

Container Won't Start

Container php: Exited (1)

Diagnosis:

# Check logs for the failing container
docker-local logs php

# Check exit code
docker inspect --format='{{.State.ExitCode}}' php

# Exit codes:
# 0 - Normal stop
# 1 - Application error
# 137 - Out of memory (OOM killed)
# 139 - Segmentation fault

Fix based on exit code:

# Exit 1 - Check application logs
docker-local logs php --tail=100

# Exit 137 - Increase Docker memory
# Docker Desktop > Settings > Resources > Memory

# Restart the container
docker-local restart

Permission Denied

Error: Permission denied

Diagnosis:

# Check user permissions
id
groups

# Check project permissions
ls -la ~/projects/

# Check Docker socket
ls -la /var/run/docker.sock

Fix:

# Linux: Add user to docker group
sudo usermod -aG docker $USER
newgrp docker

# Fix project permissions
sudo chown -R $USER:$USER ~/projects

# Fix socket permissions (temporary)
sudo chmod 666 /var/run/docker.sock

Cannot Connect to Database

SQLSTATE[HY000] [2002] Connection refused

Diagnosis:

# Check if database container is running
docker-local status

# Check database logs
docker-local logs mysql
docker-local logs postgres

# Test connection from inside container
docker exec php php -r "new PDO('mysql:host=mysql;dbname=laravel', 'laravel', 'secret');"

Fix:

# Ensure services are running
docker-local up

# Wait for database to be ready (health check)
docker-local status

# Check .env has correct host (mysql, not localhost)
# DB_HOST=mysql

DNS Not Resolving (*.test domains)

Could not resolve host: myapp.test

Diagnosis:

# Check if DNS is configured
ping myapp.test

# Check /etc/hosts
cat /etc/hosts | grep test

# Check dnsmasq (if used)
systemctl status dnsmasq  # Linux

Fix:

# Option 1: Setup DNS (recommended)
sudo docker-local setup:dns

# Option 2: Add to /etc/hosts
sudo docker-local setup:hosts

# Option 3: Manual hosts entry
echo "127.0.0.1 myapp.test" | sudo tee -a /etc/hosts

SSL Certificate Issues

SSL certificate problem: unable to get local issuer certificate

Diagnosis:

# Check SSL certificate status
docker-local ssl:status

# Check certificates exist
ls -la ~/.config/docker-local/certs/

# Check certificate validity
openssl x509 -in ~/.config/docker-local/certs/localhost.pem -noout -dates

# Test HTTPS
curl -vk https://localhost 2>&1 | head -20

Fix:

# Regenerate SSL certificates with mkcert
docker-local ssl:regenerate

# Or regenerate during init
docker-local init --certs

# Trust the certificate (browser)
# Import ~/.config/docker-local/certs/localhost.pem

# For mkcert users
mkcert -install

Projects Not Visible

No projects found in ~/projects

Diagnosis:

# Check projects directory
ls -la ~/projects/

# Check config
docker-local config | grep projects_path

# Verify project structure
ls -la ~/projects/myapp/artisan

Fix:

# Ensure projects are in correct location
mv /path/to/myapp ~/projects/

# Or update config
# Edit ~/.config/docker-local/config.json
# Change projects_path

4. Full Reset Procedure

If all else fails, perform a complete reset:

# Stop everything
docker-local down

# Remove all Docker resources
docker system prune -af
docker volume prune -f
docker network prune -f

# Remove docker-local config (backup first)
mv ~/.config/docker-local ~/.config/docker-local.backup

# Reinitialize
docker-local init

# Restart
docker-local up

# Restore projects (they're safe in ~/projects)
docker-local list

5. Useful Debugging Commands

# Shell into PHP container
docker-local shell

# Real-time Docker events
docker events

# Container resource usage
docker stats --no-stream

# Network inspection
docker network inspect laravel-dev

# Volume inspection
docker volume ls
docker volume inspect mysql_data

# Compose configuration check
docker compose -f ~/.config/docker-local/docker-compose.yml config

Report Format

After troubleshooting, provide:

1. Root Cause: What caused the issue
2. Solution: Commands that fix it
3. Prevention: How to avoid in future
4. Verification: How to confirm it's fixed

Issue: MySQL container not starting

Root Cause: Port 3306 already in use by local MySQL installation

Solution:
  sudo systemctl stop mysql  # Stop local MySQL
  docker-local up            # Start docker-local

Prevention:
  - Use docker-local consistently
  - Or change MySQL port in ~/.config/docker-local/config.json

Verification:
  docker-local status        # Should show mysql: Running
  docker-local db:mysql      # Should open MySQL CLI

$ARGUMENTS