Docker Compose Doctor

docker-compose-doctor

Diagnostica problemas comunes en archivos compose.yml / docker-compose.yml antes de hacer docker compose up — para que el stack levante a la primera y los servicios queden saludables.

No reemplaza a docker compose config (que valida sintaxis del schema). Cubre la capa de convenciones operacionales que el schema oficial no captura: healthchecks faltantes, dependencias sin esperar a service_healthy, etc.

---

Cuándo invocar este skill

Triggers explícitos:

• "revisa el compose"
• "valida docker-compose"
• "qué tiene mal este compose"
• "docker compose lint"
• "auditar compose.yml"
• "chequea el stack"
• "por qué no levanta este compose"
• "doctor del compose"

Triggers proactivos:

• Después de editar cualquier compose*.y*ml o docker-compose*.y*ml en la sesión.
• Antes de un docker compose up cuando el usuario menciona problemas de orden de arranque, servicios "unhealthy", o puertos en conflicto.

---

Cómo se invoca

Sin argumentos: busca compose.yml, compose.yaml, docker-compose.yml y docker-compose.yaml en Path.cwd() recursivamente hasta 3 niveles.

python ~/.claude/skills/docker-compose-doctor/docker_compose_doctor.py

Modos:

# Archivo específico
python .../docker_compose_doctor.py path/to/compose.yml

# Solo errores (omite warnings)
python .../docker_compose_doctor.py --errors-only

# Output JSON (para integraciones)
python .../docker_compose_doctor.py --json

# Verbose — muestra cada check ejecutado
python .../docker_compose_doctor.py -v

Exit codes:

• 0 — sin hallazgos o solo warnings.
• 1 — al menos un error (bloquea CI / pre-push).
• 2 — error de invocación (archivo no existe, YAML malformado).

---

Qué chequea exactamente

| # | Check | Severidad | Razón | |---|---|:-:|---| | 1 | Puertos host duplicados entre servicios ("8080:80" en dos servicios). | error | El segundo servicio falla al bindear → stack no levanta. | | 2 | Servicios sin healthcheck. | warning | Sin healthcheck, depends_on: condition: service_healthy no funciona y el orquestador no detecta servicios atascados. | | 3 | depends_on simple cuando el target tiene healthcheck. Detecta depends_on: [db] cuando db define un healthcheck — debería usar la forma extendida con condition: service_healthy. | warning | Race condition clásica: la app arranca antes de que la DB acepte conexiones. | | 4 | Imágenes con :latest o sin tag (ej. image: postgres). | warning | Builds no reproducibles. Pinnear a versión major.minor al menos. | | 5 | Volúmenes nombrados declarados pero no referenciados en ningún servicio. | warning | Dead config. Suelen quedar tras refactors. | | 6 | env_file apuntando a archivo inexistente (relativo al compose.yml). | error | Falla en up. Frecuente cuando .env.example se renombra. |

---

Qué NO hace / limitaciones

• No valida el schema de Compose. Para eso usa docker compose config -q — este skill asume que la sintaxis ya es válida.
• No ejecuta el stack. Es análisis estático del YAML; no detecta problemas que solo aparecen runtime (ej. health check que devuelve 200 pero la app está rota internamente).
• No resuelve ${VAR} con valores de entorno. Si tu image: ${MY_IMAGE} no tiene tag literal en el YAML, no se reporta como latest — porque no se sabe.
• No valida redes custom. Salir del scope MVP — puede llegar en una versión futura.
• Sigue extends: y include: solo a un nivel (en compose v2.20+). Composes muy anidados pueden tener falsos negativos.

---

Dependencias

| Dependencia | Cómo instalar | Requerida o opcional | |---|---|---| | python>=3.11 | viene con el SO | requerida | | pyyaml | pip install pyyaml | requerida |

Sin binarios externos. No invoca docker ni docker compose.

---

Ejemplos de salida

Caso con hallazgos

docker-compose-doctor — repo: /ruta/a/mi-proyecto
  archivo: compose.yml (5 servicios)

[errors]
  ✗ Puerto host 8080 duplicado entre servicios 'api' y 'admin'
    api:    "8080:8000"  (línea 14)
    admin:  "8080:80"    (línea 41)
  ✗ env_file inexistente en servicio 'worker': ./envs/worker.env (línea 67)

[warnings]
  ⚠ Servicio 'api' sin healthcheck — depends_on no podrá esperar a service_healthy
  ⚠ Servicio 'worker' depende de 'db' (que tiene healthcheck) con depends_on simple
    Sugerencia:
        depends_on:
          db:
            condition: service_healthy
  ⚠ Imagen 'redis' sin tag (línea 52) — pinnea a 'redis:7.2-alpine' o similar
  ⚠ Volumen 'old_cache' declarado pero no referenciado por ningún servicio

Resumen: 2 errores, 4 warnings.

Exit 1 (errores presentes).

Caso limpio

docker-compose-doctor — repo: /ruta/a/mi-proyecto
  archivo: compose.yml (5 servicios)

✓ Puertos: sin conflictos
✓ Healthchecks: 5/5 servicios cubiertos
✓ depends_on: todas las dependencias usan condition apropiada
✓ Imágenes: todas pinneadas
✓ Volúmenes: sin huérfanos
✓ env_file: todos los archivos existen

Resumen: 0 errores, 0 warnings. OK para `docker compose up`.

Exit 0.

---

Integración con flujo de trabajo

Combinable con [[yaml-control]] (valida sintaxis YAML del compose) y [[pre-push-guard]] (orquesta ambos + tests antes de pushear).

# Antes de un cambio importante al stack
python ~/.claude/skills/yaml-control/yaml_control.py
python ~/.claude/skills/docker-compose-doctor/docker_compose_doctor.py
docker compose up -d

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: vladimiracunadev-create
• Source: vladimiracunadev-create/claude-skills-toolkit
• License: MIT
• Homepage: https://github.com/vladimiracunadev-create/claude-skills-toolkit#-catálogo

Install and usage instructions live in the source repository linked above.