Docker-Compose: Error al desplegar una pila: el servicio hace referencia a un volumen indefinido – Solución

A veces puede ocurrir que aparezca el siguiente mensaje de error al iniciar Docker Compose Stack, de forma nativa o a través de Portainer:

Failed to deploy a stack: service "docker" refers to undefined volume mnt/docker: invalid compose project

El error “Error al desplegar una pila: el servicio ‘docker’ hace referencia a un volumen no definido mnt/docker: proyecto de composición no válido” se produce si se define un volumen en un archivo Docker Compose que no se especifica correctamente o hace referencia a un directorio que no existe.

Descripción del error

El error suele producirse porque el archivo Docker Compose(docker-compose.yml) contiene una ruta de volumen o una etiqueta de volumen que es o bien:

• no está formateado correctamente,
• no existe o
• no estabaclaramente definida.

El mensaje de error indica que el volumen mnt/docker no está definido o referenciado correctamente. Esto significa que Docker Compose no puede resolver o crear la ruta especificada.

Posibles causas

1. Falta la barra diagonal inicial: La ruta al volumen no empieza por /. Esto hace que Docker interprete la ruta como una ruta relativa, lo cual es incorrecto.
2. El directorio no existe: La ruta de directorio especificada(/mnt/docker) no existe en el sistema anfitrión.
3. Error tipográfico o sintaxis incorrecta: Un error tipográfico en la ruta o en el archivo de composición provoca una definición incorrecta.
4. Falta la definición del volumen o está mal colocada: Si se utiliza un volumen con nombre, debe definirse en volúmenes: en el archivo de composición.

Pasos de la solución

1. comprueba y corrige la ruta del volumen

• La ruta del archivo Docker Compose debe ser absoluta y correcta.
• Asegúrate de que la ruta existe en el sistema anfitrión.

Ejemplo:

services:
  my_service:
    image: my_image:latest
    volumes:
      - /mnt/docker:/data

Asegúrate de que /mnt/docker existe. Si no es así, créalo con el comando

sudo mkdir -p /mnt/docker

2. comprueba si hay errores tipográficos en la ruta

Presta atención a posibles errores tipográficos en la especificación del volumen y corrígelos.

Incorrecto:

Sin “/” inicial

volumes:
  - mnt/docker:/data

Correcto:

Guiando “/”

volumes:
  - /mnt/docker:/data  

3. utilizar correctamente los volúmenes con nombre

Si quieres utilizar volúmenes con nombre, debes definirlos explícitamente en volúmenes: en el archivo Componer:

Ejemplo para volúmenes con nombre:

version: '3'

services:
  app:
    image: my_image:latest
    volumes:
      - mydata:/data

volumes:
  mydata:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: /mnt/docker

El volumen con nombre mydata se define aquí y se vincula a la ruta /mnt/docker. El campo dispositivo debe apuntar a un directorio existente.

4. asegúrate de que los directorios existen y tienen las autorizaciones correctas

Comprueba las autorizaciones y la existencia del directorio. Docker debe poder acceder a la ruta especificada y escribir en ella:

ls -ld /mnt/docker

Debe asegurarse de que la ruta existe y es legible/escribible. Si no es así, establece las autorizaciones en consecuencia:

sudo chmod 755 /mnt/docker
sudo chown $USER:$USER /mnt/docker

5. comprueba la versión de Docker Compose

Asegúrate de que el archivo Docker Compose utilizado coincide con la versión de Docker Compose instalada. Utiliza la versión 3 o superior para utilizar volúmenes con nombre y otras funciones avanzadas.

El error “service ‘docker’ refers to undefined volume mnt/docker” se produce cuando los volúmenes no están definidos correctamente o las rutas son incorrectas. El problema suele resolverse comprobando y corrigiendo cuidadosamente el archivo Docker Compose y la estructura de directorios, y asegurándote de que los volúmenes con nombre se definen correctamente.