Docker-Compose: Failed to deploy a stack: service refers to undefined volume – Lösung

Manchmal kann es passieren, dass beim Starten des Docker-Compose Stacks, nativ oder über Portainer folgende Fehlermeldung erscheint:

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

Der Fehler “Failed to deploy a stack: service ‘docker’ refers to undefined volume mnt/docker: invalid compose project” tritt auf, wenn in einer Docker Compose-Datei ein Volume definiert wird, das nicht korrekt angegeben ist oder auf ein Verzeichnis verweist, das nicht existiert.

Fehlerbeschreibung

Der Fehler tritt in der Regel auf, weil die Docker Compose-Datei (docker-compose.yml) einen Volume-Pfad oder eine Volume-Bezeichnung enthält, der entweder:

• nicht korrekt formatiert ist,
• nicht existiert oder
• nicht eindeutig definiert wurde.

Die Fehlermeldung weist darauf hin, dass das Volume mnt/docker nicht definiert oder korrekt referenziert ist. Dies bedeutet, dass Docker Compose den angegebenen Pfad nicht auflösen oder erstellen kann.

Mögliche Ursachen

1. Fehlender führender Schrägstrich: Der Pfad zum Volume beginnt nicht mit einem /. Dies führt dazu, dass Docker den Pfad als relativen Pfad interpretiert, was falsch ist.
2. Verzeichnis existiert nicht: Der angegebene Verzeichnispfad (/mnt/docker) existiert nicht auf dem Host-System.
3. Schreibfehler oder falsche Syntax: Ein Tippfehler im Pfad oder in der Compose-Datei führt zu einer fehlerhaften Definition.
4. Volume-Definition fehlt oder ist falsch platziert: Wenn ein benanntes Volume verwendet wird, muss es unter volumes: im Compose-File definiert werden.

Lösungsschritte

1. Überprüfe und Korrigiere den Volume-Pfad

• Der Pfad in der Docker Compose-Datei sollte absolut und korrekt sein.
• Stelle sicher, dass der Pfad auf dem Host-System existiert.

Beispiel:

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

Stelle sicher, dass /mnt/docker existiert. Wenn nicht, erstelle es mit dem Befehl:

sudo mkdir -p /mnt/docker

2. Überprüfe den Pfad auf Tippfehler

Achte auf mögliche Tippfehler in der Volume-Angabe und korrigiere diese.

Falsch:

Kein führender “/”

volumes:
  - mnt/docker:/data

Richtig:

Führender “/”

volumes:
  - /mnt/docker:/data  

3. Verwende benannte Volumes korrekt

Wenn du benannte Volumes verwenden möchtest, musst du diese explizit unter volumes: in der Compose-Datei definieren:

Beispiel für benannte Volumes:

version: '3'

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

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

Hier wird das benannte Volume mydata definiert und mit dem Pfad /mnt/docker verknüpft. Das device-Feld sollte auf ein existierendes Verzeichnis zeigen.

4. Stelle sicher, dass die Verzeichnisse vorhanden sind und die richtigen Berechtigungen haben

Überprüfe die Berechtigungen und die Existenz des Verzeichnisses. Docker muss in der Lage sein, auf den angegebenen Pfad zuzugreifen und darin zu schreiben:

ls -ld /mnt/docker

Sollte sicherstellen, dass der Pfad existiert und lesbar/schreibbar ist. Falls nicht, setze die Berechtigungen entsprechend:

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

5. Prüfe die Docker Compose-Version

Stelle sicher, dass die verwendete Docker Compose-Datei zur installierten Docker Compose-Version passt. Verwende Version 3 oder höher, um benannte Volumes und andere erweiterte Funktionen zu nutzen.

Der Fehler “service ‘docker’ refers to undefined volume mnt/docker” tritt auf, wenn Volumes nicht korrekt definiert oder die Pfade fehlerhaft sind. Durch eine sorgfältige Prüfung und Korrektur der Docker Compose-Datei und der Verzeichnisstruktur sowie die Sicherstellung, dass benannte Volumes korrekt definiert sind, lässt sich das Problem in der Regel beheben.