docker-local-doctor
Run comprehensive health check on docker-local environment - diagnose configuration, services, and connectivity
When & Why to Use This Skill
The Docker-Local Doctor skill is a comprehensive diagnostic utility designed to automate health checks and troubleshooting for local Docker development environments. It performs deep analysis of system requirements, service health, network connectivity, and project configurations, offering actionable resolutions for common environment issues, SSL certificate expirations, and resource conflicts to ensure a seamless development workflow.
Use Cases
- Environment Troubleshooting: Rapidly identify and fix root causes when local services like MySQL, Redis, or Traefik fail to start or exhibit connectivity issues.
- New Machine Onboarding: Automatically verify that all prerequisites, including Docker, PHP, and Composer versions, are correctly installed and configured on a new developer workstation.
- Project Conflict Detection: Audit multiple local projects simultaneously to detect overlapping database names, Redis DB indices, or port conflicts that could lead to data corruption or service failure.
- Connectivity & SSL Verification: Validate local DNS resolution and SSL certificate validity to ensure that secure local development URLs and proxy configurations are functioning correctly.
| name | docker-local-doctor |
|---|---|
| description | Run comprehensive health check on docker-local environment - diagnose configuration, services, and connectivity |
Docker-Local Doctor Skill
Overview
This skill performs a comprehensive health check of the docker-local environment, diagnosing:
- System requirements
- Docker configuration
- Service health
- Network connectivity
- Project configurations
- Potential conflicts
Activation
Use this skill when:
- User reports issues with their environment
- Setting up a new machine
- After updates or changes
- Periodic health verification
- Before creating new projects
MANDATORY: Prerequisite Check
Before ANY docker-local command, verify installation:
which docker-local > /dev/null 2>&1
If docker-local is NOT found:
- Stop and ask the user if they want to install it
- If yes, install via:
composer global require mwguerra/docker-local - Add to PATH:
export PATH="$HOME/.composer/vendor/bin:$PATH" - Initialize:
docker-local init - Verify:
which docker-local && docker-local --version
Process
1. Run Docker-Local Doctor
# Full diagnostic
docker-local doctor
# This checks:
# - Docker version and daemon
# - Docker Compose version
# - PHP and Composer versions
# - Configuration files
# - Container health
# - Network connectivity
# - DNS resolution
# - SSL certificates
2. Check System Requirements
# Docker version (24.0+)
docker --version
# Docker Compose (2.20+)
docker compose version
# PHP (8.2+)
php --version
# Composer (2.6+)
composer --version
3. Verify Configuration
# Check config exists
ls -la ~/.config/docker-local/
# View configuration
docker-local config
# Verify projects directory
ls -la ~/projects/
4. Test Services
# Check all containers
docker-local status
# Test database connectivity
docker exec mysql mysqladmin ping -h localhost -u root -psecret 2>/dev/null && echo "MySQL: OK"
docker exec postgres pg_isready -U laravel 2>/dev/null && echo "PostgreSQL: OK"
docker exec redis redis-cli ping 2>/dev/null && echo "Redis: OK"
5. Check Network
# Verify Docker network
docker network ls | grep laravel-dev
# Test DNS resolution (if configured)
ping -c 1 mysql.localhost 2>/dev/null && echo "DNS: OK"
# Check Traefik
curl -sk https://traefik.localhost 2>/dev/null && echo "Traefik: OK"
6. Audit Project Configurations
# Check all projects for conflicts
docker-local env:check --all
# This checks:
# - Database names (unique per project)
# - Redis DB numbers (no overlap)
# - Cache prefixes (unique)
# - MinIO buckets (unique)
# - Reverb credentials (unique)
7. Check Certificates
# Verify SSL certificates exist
ls -la ~/.config/docker-local/certs/
# Check certificate validity
openssl x509 -in ~/.config/docker-local/certs/localhost.pem -noout -dates 2>/dev/null
Diagnostic Report Format
Docker-Local Health Check
=========================
System Requirements:
[OK] Docker 24.0.7 (required: 24.0+)
[OK] Docker Compose 2.24.5 (required: 2.20+)
[OK] PHP 8.3.0 (required: 8.2+)
[OK] Composer 2.7.1 (required: 2.6+)
Configuration:
[OK] Config directory exists
[OK] config.json valid
[OK] .env file present
[OK] Projects directory exists
Services:
[OK] Docker daemon running
[OK] php container healthy
[OK] mysql container healthy
[OK] postgres container healthy
[OK] redis container healthy
[OK] traefik container healthy
[OK] nginx container healthy
Network:
[OK] laravel-dev network exists
[OK] Traefik responding
[OK] SSL certificates valid
Projects:
[OK] blog - no conflicts
[OK] api - no conflicts
[WARN] shop - Redis DB overlap with 'blog'
Recommendations:
- Fix Redis DB conflict in ~/projects/shop/.env
Common Issues Detected
Version Mismatch
[FAIL] Docker 23.0.0 (required: 24.0+)
Fix: Update Docker to latest version
Missing Configuration
[FAIL] config.json not found
Fix: Run docker-local init
Service Not Running
[FAIL] mysql container not running
Fix: Run docker-local up
Project Conflicts
[WARN] Redis DB conflict between projects
Fix: Update .env with unique REDIS_*_DB values
Certificate Expired
[WARN] SSL certificate expired
Fix: Run docker-local init --certs
Resolution Commands
After diagnosis, provide specific fix commands:
# Reinitialize environment
docker-local init
# Restart services
docker-local restart
# Fix DNS
sudo docker-local setup:dns
# Regenerate certificates
docker-local init --certs
# Clean and restart
docker-local clean
docker-local up
$ARGUMENTS