lc-docker-check

name	lc:docker-check
description	Verify docker-compose.yml, Dockerfile, and .env are properly synchronized.
argument-hint	[analyze | fix | fix --dry-run]
user-invocable	true
allowed-tools	Read Grep Bash Edit Write Glob

Docker Configuration Check

Verify that docker-compose.yml, Dockerfile, .env, and composer.json are properly synchronized. Detects mismatched service names, port conflicts, missing extensions, and configuration drift.

Subcommands

Subcommand	Description
(no argument)	Analyze Docker configuration and report issues. Read-only.
fix	Fix detected mismatches by syncing .env with docker-compose values. Asks for confirmation before each change.
fix --dry-run	Show what .env changes would be made without modifying anything.

Process

Step 1: Read Configuration Files

Use Read to load:

1. docker-compose.yml (or docker-compose.yaml, compose.yml, compose.yaml)
2. Dockerfile (and any variant like docker/*/Dockerfile, docker/Dockerfile)
3. .env
4. .env.example
5. composer.json (for PHP version and extension requirements)

If any file is missing, note it and continue with available files.

Step 2: Check Service-to-Env Synchronization

Database Configuration

1. Find the database service in docker-compose (mysql, mariadb, postgres).
2. Extract:
   • Service name (used as hostname): e.g., mysql, db, database
   • Port mapping: e.g., 3306:3306
   • Environment variables: MYSQL_DATABASE, MYSQL_USER, MYSQL_PASSWORD, MYSQL_ROOT_PASSWORD
3. Compare with .env:
   • DB_HOST should match the service name (e.g., mysql, not 127.0.0.1)
   • DB_PORT should match the internal port (usually 3306)
   • DB_DATABASE should match MYSQL_DATABASE
   • DB_USERNAME should match MYSQL_USER
   • DB_PASSWORD should match MYSQL_PASSWORD

Common issue: DB_HOST=127.0.0.1 when it should be the Docker service name (e.g., mysql).

Redis Configuration

1. Find the Redis service in docker-compose.
2. Compare with .env:
   • REDIS_HOST should match the service name (e.g., redis)
   • REDIS_PORT should match the internal port (usually 6379)

Mail Configuration

1. Find mail services (mailhog, mailpit, mailtrap).
2. Compare with .env:
   • MAIL_HOST should match the service name
   • MAIL_PORT should match the internal port

Queue/Cache

1. Check CACHE_DRIVER and QUEUE_CONNECTION in .env.
2. If set to redis, verify Redis service exists in docker-compose.
3. If set to database, no extra service needed.

Step 3: Check Port Conflicts

1. Extract all port mappings from docker-compose: host_port:container_port.
2. Check for duplicate host ports (would cause bind errors).
3. Check for common conflicts:
   • 3306 (MySQL) -- conflicts with local MySQL
   • 5432 (PostgreSQL) -- conflicts with local PostgreSQL
   • 6379 (Redis) -- conflicts with local Redis
   • 80/443 (HTTP/S) -- conflicts with local web server
   • 8080 (common dev port) -- conflicts with other dev servers

Step 4: Check Volume Paths

1. Extract volume mounts from docker-compose.
2. For bind mounts (host path : container path):
   • Check that the host path exists or is a relative path from the project root.
   • Check that the container path makes sense for the service type.
3. For named volumes, ensure they are defined in the volumes: section.

Step 5: Check PHP Version Consistency

1. Extract PHP version from Dockerfile (FROM php:X.Y-fpm, FROM php:X.Y-cli, etc.).
2. Check composer.json for the require.php constraint (e.g., "^8.2").
3. Compare: the Dockerfile PHP version should satisfy the Composer constraint.
4. If there is a mismatch, flag it.

Step 6: Check Required PHP Extensions

1. Parse composer.json for require entries starting with ext-:
   • "ext-gd": "*" -> requires gd extension
   • "ext-redis": "*" -> requires redis extension
   • "ext-intl": "*" -> requires intl extension
2. Parse the Dockerfile for installed extensions:
   • docker-php-ext-install gd intl pdo_mysql
   • pecl install redis
   • RUN apt-get install (for underlying libraries)
3. Flag extensions required by Composer but not installed in Dockerfile.

Step 7: Check .env.example Completeness

1. Compare all keys in .env with keys in .env.example.
2. Flag keys present in .env but missing from .env.example (may cause setup issues for new developers).
3. Flag keys in .env.example but missing from .env (may indicate unused configuration).

Step 8: Report

DOCKER CONFIGURATION CHECK
============================

ISSUES FOUND
--------------

1. DB_HOST mismatch
   .env: DB_HOST=127.0.0.1
   docker-compose: Database service name is 'mysql'
   Fix: Change DB_HOST to 'mysql' in .env
   Severity: Critical (app cannot connect to DB in Docker)

2. Port conflict
   Service 'mysql' maps to host port 3306
   Service 'testing-db' also maps to host port 3306
   Fix: Change one service to a different host port (e.g., 3307:3306)
   Severity: Critical (docker-compose will fail to start)

3. Missing PHP extension
   composer.json requires: ext-redis
   Dockerfile: redis extension not found
   Fix: Add 'pecl install redis && docker-php-ext-enable redis' to Dockerfile
   Severity: High (application will fail at runtime)

4. PHP version mismatch
   Dockerfile: PHP {detected_version}
   composer.json: "php": "{composer_constraint}"
   Status: Compatible/Incompatible

5. Missing .env.example keys
   Keys in .env but not in .env.example:
   - GOOGLE_OAUTH_CLIENT_ID
   - GOOGLE_OAUTH_CLIENT_SECRET
   - MICROSOFT_OAUTH_CLIENT_ID
   Severity: Low (documentation issue)

ALL CHECKS
-----------
[PASS] Database service exists and is properly configured
[FAIL] DB_HOST does not match service name
[PASS] Redis service exists and matches REDIS_HOST
[PASS] No port conflicts detected
[PASS] Volume paths are valid
[PASS] PHP version is compatible
[FAIL] Missing ext-redis in Dockerfile
[WARN] 3 .env keys missing from .env.example

SUMMARY
========
Checks performed: 8
Passed: 5
Failed: 2
Warnings: 1

Fix Mode

In fix mode, apply corrections with confirmation:

1. Sync .env values: Update DB_HOST, REDIS_HOST, MAIL_HOST to match docker-compose service names.
2. Sync credentials: Update DB_DATABASE, DB_USERNAME, DB_PASSWORD to match docker-compose environment variables.
3. Update .env.example: Add missing keys with placeholder values.

Not auto-fixed (manual intervention needed):

• Dockerfile changes (adding extensions, changing PHP version)
• Port conflict resolution (requires understanding of the developer's environment)
• Volume path fixes

Notes

• This skill reads configuration files only. It does not start, stop, or modify Docker containers.
• Docker Compose file format (version 2 vs 3) affects syntax. Handle both formats.
• Some projects use multiple Dockerfiles (e.g., docker/{version}/Dockerfile for different PHP versions). Check all.
• .env files may have platform-specific line endings. Handle both \n and \r\n.
• When fixing .env, preserve the existing file format and ordering.