Validador de Docker Compose
Pega un docker-compose.yml o compose.yaml para revisarlo al instante. El validador detecta errores de sintaxis YAML, claves desconocidas o mal escritas, tipos de valor incorrectos, enlaces rotos entre servicios, redes, volúmenes y secretos, puertos de host duplicados y opciones obsoletas, cada uno con el número de línea y una solución.
Última actualización:
Servicios encontrados
| Servicio | Imagen / build | Puertos | Depende de |
|---|
Cómo usar Validador de Docker Compose
- Pega tu archivo Compose en el editor, sube docker-compose.yml o carga uno de los ejemplos.
- Lee el resumen: indica si el archivo es válido y cuántos errores, avisos y consejos se encontraron.
- Haz clic en un problema para saltar a la línea correspondiente; los errores se marcan en rojo y los avisos en ámbar.
- Corrige los problemas en el editor; el archivo se vuelve a revisar automáticamente mientras escribes.
- Filtra o copia el informe para compartirlo en un pull request o ticket, y luego ejecuta
docker compose configen local para una comprobación final.
Errores comunes de Docker Compose y cómo corregirlos
La mayoría de los archivos Compose rotos fallan por unas pocas razones. La tabla recoge los mensajes que probablemente verás aquí, su causa y la solución habitual.
| Problema | Causa típica | Solución |
|---|---|---|
| Sangría incorrecta | Una clave tiene una sangría con un número de espacios distinto al de sus hermanas, o se usó una tabulación | Usa solo espacios y mantén todas las claves de un servicio en la misma columna |
| Clave desconocida | Una errata (enviroment, depend_on) o una clave puesta en el nivel equivocado | Usa la ortografía sugerida; las claves personalizadas deben empezar por x- |
| Volumen con nombre no declarado | data:/app/data hace referencia a un volumen con nombre que falta en volumes: de nivel superior | Añade volumes: {data: {}}, o escribe ./data:/app/data para un bind mount |
| Red no declarada | Un servicio se une a una red personalizada que no está definida | Añádela en networks: de nivel superior; solo default existe automáticamente |
| El servicio no tiene ni image ni build | El servicio solo define puertos o variables de entorno | Añade image: name:tag o build: ./folder |
| Puerto de host ya publicado | Dos servicios asignan el mismo puerto de host, por ejemplo ambos usan "80:…" | Da a cada uno un puerto de host distinto, o vincúlalos a IP diferentes |
| Dependencia circular | A depende de B y B (directa o indirectamente) depende de A | Elimina una de las direcciones; usa healthchecks y reintentos en lugar de esperas mutuas |
| Duración no válida | interval: 30 seconds o timeout: 5 | Escribe un número con unidad: 30s, 1m30s, 500ms |
| Se esperaba un booleano | privileged: yes es una cadena en YAML 1.2 | Usa true o false |
Claves de Compose obsoletas y heredadas
La Compose Specification sustituyó los formatos de archivo separados de las versiones 2 y 3. Algunas opciones antiguas siguen funcionando pero ya no se recomiendan:
version: obsoleta. Compose v2 la ignora y avisa de ello. Elimina la línea; las funciones más recientes siempre están disponibles.links: heredada. Todos los servicios de una red compartida ya pueden comunicarse con los demás por el nombre del servicio, por ejemplodb:5432. Usadepends_onpara el orden de arranque yaliasesde red para nombres de host adicionales.external_links: heredada. Conecta ambos proyectos a la misma red externa.external: {name: …}: obsoleta. Escribename: shared_netyexternal: trueen la red o el volumen.
Consejos para un archivo Compose sano
- Fija las etiquetas de las imágenes (
postgres:16-alpineen lugar depostgreso:latest) para que cada despliegue use la misma versión. - Añade un
healthchecka las bases de datos y cachés y usacondition: service_healthyendepends_on, para que los servicios dependientes arranquen solo cuando puedan conectarse. - Mantén los secretos fuera del archivo: haz referencia a
${DB_PASSWORD}desde un archivo.envsin seguimiento en git, o usa la secciónsecretsde nivel superior y variables*_FILE. - No publiques los puertos de base de datos salvo que los necesites desde el host; los contenedores de la misma red se comunican sin
ports. Si lo haces, vincúlalos a127.0.0.1. - Evita
container_namesalvo que otra herramienta necesite un nombre fijo; impide escalar y puede chocar entre proyectos. - Ejecuta
docker compose configdespués de editar para ver el archivo final con las variables y los archivos override combinados.
Preguntas frecuentes
¿Qué comprueba este validador de Docker Compose?
Analiza el archivo como YAML y luego compara cada clave y valor con la Compose Specification que usa Docker Compose v2: claves permitidas, tipos de valor, enumeraciones como las políticas de reinicio y las condiciones de depends_on, y formatos de duración. Después comprueba las relaciones entre las partes del archivo, por ejemplo que cada red, volumen con nombre, secreto y dependencia que usa un servicio esté realmente definido.
¿Sigue siendo necesaria la clave version en docker-compose.yml?
No. Docker Compose v2 sigue la Compose Specification, que considera obsoleta la clave version de nivel superior. Compose la ignora y muestra un aviso de que el atributo está obsoleto, así que puedes borrar la línea. El validador la marca como clave obsoleta.
¿Por qué dice que mi volumen con nombre no está declarado?
Una entrada de volumen como db_data:/var/lib/mysql usa un volumen con nombre porque el origen no tiene barra ni punto. Los volúmenes con nombre deben figurar en la sección volumes de nivel superior (basta una entrada vacía como db_data:). Si te referías a una carpeta de tu computadora, escríbela como ruta, por ejemplo ./db_data:/var/lib/mysql.
¿En qué se diferencia de docker compose config?
docker compose config es la comprobación de referencia porque ejecuta el motor real de Compose, resuelve las variables de entorno y combina los archivos override. Esta herramienta funciona sin tener Docker instalado, explica cada problema en lenguaje sencillo, añade consejos de buenas prácticas y nunca envía el archivo a ningún sitio. Usa ambas: esta mientras editas y docker compose config antes de desplegar.
¿El validador reemplaza las ${VARIABLES} por valores?
No. Las variables se dejan como están escritas porque sus valores vienen de tu shell o de tu archivo .env. El validador comprueba que cada interpolación esté bien formada, por ejemplo ${VAR}, ${VAR:-default} o ${VAR:?message}, y omite la comprobación de tipos en los valores que contienen una variable.
¿Por qué hay que poner comillas a los mapeos de puertos?
Los analizadores YAML 1.1 leen un valor sin comillas como 22:22 como un número en base 60. Docker Compose v2 usa YAML 1.2 y lo interpreta correctamente, pero otras herramientas de tu pipeline quizá no. Poner comillas a cada mapeo, por ejemplo "8080:80", evita el problema en todas partes.
¿Se sube mi archivo Compose?
No. El validador y el analizador YAML funcionan en tu navegador. El archivo nunca se envía a un servidor, así que es seguro revisar archivos que contienen nombres de host internos o credenciales.
¿Se prueban todas las herramientas de FreeToolCabin para comprobar su calidad y precisión?
Sí. Cada herramienta del sitio pasa pruebas automáticas en navegadores reales para comprobar que el resultado es correcto y que no hay errores. Si encuentras un fallo o tienes una sugerencia, escríbenos a [email protected] y lo revisaremos.