Docker-Stacks in Dockhand zu importieren, macht bestehende Compose-Projekte zentral verwaltbar. Du kannst die Compose-Datei und die zugehörige .env-Datei einbinden und den Stack anschließend auf einem lokalen oder entfernten Docker-Host verwalten. Entscheidend ist dabei, wo Dockhand die Dateien lesen kann und auf welchem Rechner relative Pfade wie ./config liegen müssen.

Dockhand speichert die Stack-Konfiguration zentral. Container, Volumes und Bind-Mount-Daten liegen weiterhin auf dem jeweiligen Docker-Host. Bei Remote-Hosts hängt der Umgang mit relativen Pfaden davon ab, ob du den Host über Hawser oder direkt per TCP angebunden hast.

Voraussetzungen für den Stack-Import

Bevor du einen Stack importierst, sollte Dockhand den Zielhost als Environment anzeigen und eine Verbindung zu dessen Docker Engine herstellen können. Für die Installation von Dockhand findest du eine Anleitung für Docker Run und Docker Compose. Wie du einen entfernten Host mit Hawser verbindest, zeigt der Artikel Hawser mit Dockhand installieren.

Für den Import brauchst du außerdem Zugriff auf die Stack-Dateien: die Compose-Datei, gegebenenfalls eine .env-Datei und weitere benötigte Konfigurationsdateien. Der Import-Dialog kann nur Ordner anbieten, die Dockhand selbst lesen darf. Liegen die Dateien außerhalb des Dockhand-Containers, musst du den betreffenden Ordner als Volume in den Container einbinden.

Compose- und .env-Dateien vorbereiten

Lege die Dateien möglichst gemeinsam in einem Verzeichnis ab. So kann Dockhand die passende .env-Datei leichter erkennen und relative Pfade bleiben nachvollziehbar:

/srv/compose/meine-app/
├── compose.yaml
├── .env
├── init/
└── config/

Die Compose-Datei beschreibt Dienste, Netzwerke und Volumes. Die .env-Datei enthält Werte, die Compose beim Einlesen der Datei einsetzen soll. Beispiel für eine einfache PostgreSQL-Konfiguration:

services:
  db:
    image: postgres:16
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./init:/docker-entrypoint-initdb.d:ro

volumes:
  postgres_data:

Die dazugehörige .env-Datei liegt im gleichen Verzeichnis:

POSTGRES_DB=app
POSTGRES_USER=appuser
POSTGRES_PASSWORD=HIER_EIN_EIGENES_PASSWORT_EINTRAGEN

Compose verwendet die Werte aus .env, um Platzhalter wie ${POSTGRES_DB} zu ersetzen. Ein Eintrag in .env wird jedoch nicht automatisch an jeden Container weitergegeben. Soll die Anwendung einen Wert als Umgebungsvariable erhalten, muss er in der Compose-Datei unter environment: stehen. Das zeigt das Beispiel mit den drei PostgreSQL-Variablen.

env_file: in einem Dienst ist eine separate Compose-Einstellung: Damit werden Variablen aus der angegebenen Datei an den Container übergeben. Sie ist nicht dasselbe wie die .env-Datei, die Compose zur Variablen-Ersetzung verwendet. Die Docker-Dokumentation zur Variablen-Ersetzung erklärt die Unterschiede und die unterstützte Syntax.

Prüfe außerdem, ob deine Compose-Datei weitere Dateien einbindet, etwa Zertifikate, Konfigurationen oder Skripte. Bei relativen Einbindungen müssen diese Dateien ebenfalls im Stack-Verzeichnis oder an einem passenden relativen Pfad vorhanden sein.

Docker-Stacks in Dockhand importieren

  1. Wähle in Dockhand das Environment aus, auf dem der Stack laufen soll.
  2. Öffne die Seite Stacks und klicke auf Import.
  3. Navigiere im Dialog zu dem Ordner mit deiner Compose-Datei.
  4. Wähle die Compose-Datei direkt aus oder klicke auf Scan this folder, um den Ordner nach weiteren Stacks zu durchsuchen.
  5. Prüfe die angezeigten Stack-Namen und wähle die gewünschten Einträge aus.
  6. Klicke auf Import.

Dockhand erkennt beim Durchsuchen eines Ordners zugehörige .env-Dateien automatisch. Verwendet dein Projekt einen anderen Dateinamen, etwa .env.production, prüfe nach dem Import die Environment-Einstellungen des Stacks und gib dort die passende Datei an.

Dockhand verwendet den Namen aus dem obersten name:-Eintrag in der Compose-Datei, falls vorhanden. Ohne diesen Eintrag dient der Verzeichnisname als Stack-Name. Bei einem bereits laufenden Stack ist der Name wichtig: Dockhand erkennt ihn anhand des Compose-Projektnamens der Container. Eine erkannte laufende Anwendung wird in den Scan-Ergebnissen angezeigt.

Der Import ordnet die Compose-Datei Dockhand zu und macht den Stack verwaltbar. Die Dateien bleiben an ihrem bisherigen Speicherort. Vergleiche vor dem ersten erneuten Bereitstellen die importierte Compose-Datei mit der tatsächlich laufenden Konfiguration. Abweichungen können dazu führen, dass Dockhand Container neu erstellt.

Stack-Dateien in den Dockhand-Container einbinden

Wenn Dockhand selbst als Container läuft und deine Stacks beispielsweise unter /srv/compose liegen, muss dieser Ordner im Dockhand-Container verfügbar sein. Ein passender Volume-Eintrag sieht zum Beispiel so aus:

volumes:
  - /srv/compose:/srv/compose

Die linke Seite bezeichnet den Pfad auf dem Host, die rechte Seite den Pfad im Container. Gleiche Pfade auf beiden Seiten machen die Zuordnung einfacher. Achte darauf, den Compose-Ordner nicht nur lesbar, sondern auch beschreibbar einzubinden, wenn du Dateien später über Dockhand bearbeiten möchtest.

Wenn du beim Import keinen Stack-Ordner findest, prüfe zuerst, ob der Pfad in den Dockhand-Container eingebunden wurde. Ein Verzeichnis, das nur auf dem entfernten Docker-Host liegt, wird dadurch nicht automatisch im Dateibrowser von Dockhand sichtbar. Du kannst die Dateien in einen für Dockhand erreichbaren Ordner legen oder einen Stack aus einem Git-Repository bereitstellen.

Relative Pfade auf Remote-Hosts richtig behandeln

Ein Bind-Mount wie ./config:/app/config verweist auf einen Ordner relativ zum Stack-Verzeichnis. Docker muss diesen Ordner auf dem Rechner finden, auf dem der Docker-Daemon läuft. Genau hier unterscheiden sich lokale und entfernte Environments:

Verbindung Was mit relativen Pfaden geschieht
Lokaler Docker-Socket Dockhand und Docker verwenden denselben Host. Bei einem containerisierten Dockhand muss der Docker-Daemon den aufgelösten Pfad auf dem Host erreichen können.
Hawser Standard oder Edge Der Hawser-Agent überträgt die Stack-Dateien zum Remote-Host und legt sie dort ab. Relative Dateien wie ./config können dadurch mit dem Stack bereitgestellt werden.
Direkte TCP-Verbindung Dockhand und der Remote-Docker-Daemon teilen sich kein Dateisystem. Konfiguriere ein Remote stacks directory in den Environment-Einstellungen oder verwende bereits vorhandene absolute Host-Pfade beziehungsweise benannte Volumes.

Bei einer direkten TCP-Verbindung kannst du in aktuellen Dockhand-Versionen ein absolutes Remote stacks directory auf dem Zielhost eintragen, zum Beispiel /opt/dockhand/stacks. Dockhand stellt dann die Compose-Datei und relative Stack-Dateien auf dem Remote-Host bereit. Die Option betrifft relative Pfade innerhalb des Stack-Verzeichnisses. Absolute Bind-Pfade wie /mnt/media:/media müssen weiterhin auf dem Remote-Host vorhanden sein.

Ein Beispiel für einen relativen Mount:

volumes:
  - ./config:/app/config:ro

Bei einer Hawser-Verbindung muss der Ordner config im Stack-Verzeichnis liegen, damit der Agent ihn mit dem Stack übertragen kann. Bei direkter TCP-Verbindung benötigt Dockhand das konfigurierte Remote-Stacks-Verzeichnis, damit die relative Datei auf dem Zielhost bereitgestellt werden kann.

Ein absoluter Pfad funktioniert anders:

volumes:
  - /mnt/media:/media:ro

Hier muss /mnt/media direkt auf dem verwalteten Host existieren. Dockhand oder Hawser erstellt den externen Ordner nicht automatisch. Kontrolliere außerdem die Zugriffsrechte des Docker-Daemons auf die Dateien.

Benannte Volumes sind eine weitere Möglichkeit, wenn du keine Host-Dateien direkt einbinden musst:

volumes:
  - app_data:/var/lib/app

Docker verwaltet ein benanntes Volume auf dem Zielhost. Es hängt nicht davon ab, ob ein bestimmter relativer Ordner auf dem Host vorhanden ist.

Importierten Stack prüfen und bereitstellen

Öffne nach dem Import den Stack-Editor und kontrolliere Compose-Datei, Umgebungsvariablen, Mounts und Ziel-Environment. Prüfe besonders, ob ein bereits laufender Stack erkannt wurde und ob der Compose-Projektname passt.

Wenn alle Werte stimmen, kannst du den Stack über Dockhand bereitstellen oder aktualisieren. Beobachte anschließend den Status der Dienste und die Logs. Bei einem Stack mit Datenbank oder wichtigen Dateien solltest du vor Änderungen ein Backup der Anwendungsdaten erstellen. Ein Import ersetzt keine Datensicherung.

Eine kurze Kontrolle hilft bei der Fehlersuche:

  • Stack wird nicht gefunden: Prüfe, ob die Compose-Datei im gewählten Ordner liegt und der Ordner in Dockhand eingebunden ist.
  • Werte fehlen im Container: Prüfe, ob die Variablen unter environment: oder über env_file: an den Dienst übergeben werden.
  • Ein Bind-Mount ist leer: Prüfe, ob der relative Ordner auf dem Docker-Host bereitgestellt wurde beziehungsweise ein absolutes Verzeichnis dort existiert.
  • Ein Stack wird doppelt angezeigt: Vergleiche den Compose-Projektnamen mit dem Namen der laufenden Container, bevor du den Stack erneut bereitstellst.

Wenn du dich auch mit Änderungen und Updates von Compose-Projekten beschäftigst, hilft dir die Anleitung Docker Compose aktualisieren.

.env-Dateien und Zugangsdaten schützen

Eine .env-Datei kann Passwörter und API-Schlüssel enthalten. Nimm sie nicht ungeschützt in ein öffentliches Git-Repository auf und beschränke den Zugriff auf den Ordner. Für Git kannst du eine Vorlage wie .env.example ohne echte Zugangsdaten veröffentlichen und die produktive .env-Datei ausschließen.

Dockhand kann Secrets für die Variablen-Ersetzung verwenden. Soll ein solcher Wert im Container verfügbar sein, muss auch er in der Compose-Datei ausdrücklich unter environment: referenziert werden. Prüfe nach dem Import, wo Zugangsdaten gespeichert sind und welche Personen Zugriff auf Dockhand und den Docker-Host haben.

Passende Hardware für Docker-Hosts und Backups

Für Dockhand selbst ist keine zusätzliche Hardware nötig, wenn du bereits einen geeigneten Docker-Host betreibst. Wer einen weiteren, kompakten Remote-Host für Tests oder kleinere Dienste sucht, kann Mini-PCs mit Intel N100, mindestens 16 GB RAM und SSD vergleichen. Für separate Sicherungskopien kommen externe SSDs infrage. Eine externe SSD ersetzt jedoch kein Backup an einem zweiten Standort.

Werbung / Affiliate-Links: Die mit einem Sternchen (*) gekennzeichneten Links sind Amazon-Partnerlinks. Wenn du darüber etwas kaufst, erhalte ich möglicherweise eine Provision. Für dich entstehen dadurch keine zusätzlichen Kosten. Als Amazon-Partner verdiene ich an qualifizierten Verkäufen.

Häufige Fragen zu Docker-Stacks in Dockhand

Wird ein importierter Stack sofort neu gestartet?

Der Import ordnet Dockhand die Compose-Datei zu. Prüfe den Status und die Konfiguration des Stacks, bevor du ihn erneut bereitstellst. Eine spätere Bereitstellung kann Container neu erstellen, wenn sich die Konfiguration geändert hat.

Kann Dockhand eine Compose-Datei direkt vom Remote-Host importieren?

Der Import-Dialog zeigt Verzeichnisse an, auf die Dockhand selbst zugreifen kann. Liegt die Datei nur auf dem Remote-Host, muss sie zunächst für Dockhand verfügbar werden, zum Beispiel über einen eingebundenen Ordner oder ein Git-Repository.

Warum bleibt ein relativer Bind-Mount auf dem Remote-Host leer?

Relative Pfade müssen im Stack-Verzeichnis auf dem Docker-Host verfügbar sein. Hawser überträgt die Stack-Dateien automatisch. Bei direkter TCP-Verbindung konfigurierst du dafür ein Remote stacks directory oder verwendest einen vorhandenen absoluten Pfad beziehungsweise ein benanntes Volume.

Ist die .env-Datei automatisch im Container verfügbar?

Nein. Compose verwendet die Datei standardmäßig für Variablen-Ersetzungen in der Compose-Konfiguration. Soll ein Wert im Container ankommen, muss er unter environment: oder über die Dienstoption env_file: übergeben werden.

Fazit

Mit dem Import verknüpfst du bestehende Compose-Projekte mit Dockhand und kannst sie anschließend zentral verwalten. Lege Compose-, .env– und Konfigurationsdateien übersichtlich ab, prüfe die Variablen nach dem Import und behalte die Pfade des Zielhosts im Blick. Für relative Pfade auf Remote-Hosts ist Hawser meist der einfachste Weg; bei direkter TCP-Verbindung brauchst du ein Remote-Stacks-Verzeichnis oder bereits vorhandene Host-Pfade.