ZimaOS Docker-Compose-Importfehler: YAML-Korrekturen

Wenn ZimaOS eine Docker-Compose-Datei unter Install a Customized App → Import ablehnt, gehen Sie nicht davon aus, dass die ZimaOS-Installation beschädigt ist. Im Community-Fall vom September 2025 machte die Neuinstallation von ZimaOS und ein erneuter Versuch in einem Inkognito-Browser keinen Unterschied. Das eigentliche Problem war die gespeicherte Compose-YAML-Datei: Beim Kopieren in Notizen war die Formatierung beschädigt worden, und die exportierte Definition enthielt mehr Komplexität, als die Anwendung benötigte.

Der Nutzer reparierte die YAML-Datei, vereinfachte den Syncthing-Dienst und bestätigte, dass das Importproblem gelöst war. Der Thread hebt außerdem einen wichtigen Anwendungsfall von ZimaOS hervor: Optionen wie tmpfs möglicherweise kein eigenes Feld im visuellen Editor haben, sodass der Compose-Import für erweiterte Container-Einstellungen weiterhin erforderlich ist.

So sah der Importfehler aus

Der ursprüngliche Nutzer führte ZimaOS 1.4.3 auf einem Beelink Mini aus und stellte fest, dass sich eine zuvor exportierte benutzerdefinierte Anwendung nach einer sauberen Neuinstallation nicht mehr importieren ließ.

ZimaOS-Browserkonsole mit einem Fehler nach dem Übermitteln einer benutzerdefinierten Docker-Compose-App — Das erste Symptom trat auf, als der gespeicherte Docker-Compose-Text an den Importer für benutzerdefinierte Apps von ZimaOS übermittelt wurde.

Während der Fehlersuche am Importer für benutzerdefinierte ZimaOS-Apps aufgezeichnete Ausgaben der Browser-Entwicklerkonsole — Eine Neuinstallation des Betriebssystems und der Wechsel von Browsersitzungen beseitigten das zugrunde liegende Compose-Problem nicht.

YAML vor der Fehlersuche in ZimaOS validieren

YAML ist einrückungssensitiv. Eine einzige von einer Notiz-App verschobene Ebene kann gültiges Compose in eine völlig andere Struktur verwandeln.

Der ursprüngliche Autor bemerkte schließlich, dass sein gespeicherter Export schlecht formatiert war. Sein Workflow zum Erstellen von Notizen hatte die Struktur verändert, nachdem die Compose-Datei von der alten ZimaOS-Installation kopiert worden war.

Vor Änderungen am ZimaOS-Host:

fügen Sie die Compose-Datei in einen YAML-/Compose-Validator ein;
verwenden Sie Leerzeichen statt Tabulatoren;
überprüfen Sie die Einrückung jedes Listenelements und jeder untergeordneten Eigenschaft;
bestätigen Sie, dass jeder Bind-Mount ein containerseitiges Ziel hat;
entfernen Sie doppelte Schlüssel;
Vergleichen Sie das Ergebnis mit der aktuellen Docker-Compose-Spezifikation.

Ein vollständiger Bind-Mount benötigt sowohl Quelle als auch Ziel

Ein gültiger Bind-Mount im Langformat sieht so aus:

volumes:
  - type: bind
    source: /DATA/AppData/syncthing/data
    target: /var/syncthing

Docker Compose unterstützt derzeit auch optionale Bind-Einstellungen wie:

bind:
  create_host_path: true

Die wichtigste Voraussetzung ist, dass die YAML-Struktur gültig ist und Quelle und Ziel sind unter demselben Mount-Eintrag verschachtelt.

Docker-Compose-Services verweisen auf

Die lange Port-Syntax ist gültig, aber halten Sie es einfach

Der alte Export enthielt ausführliche Porteinträge wie:

Ports:
  - target: 8384
    published: "8384"
    protocol: tcp
    mode: ingress

Aktuelles Docker Compose definiert ausdrücklich Modus in der langen Port-Syntax, hauptsächlich für das Publishing-Verhalten in Swarm. Das bedeutet, dass der Schlüssel selbst nicht universell ungültig für Compose ist.

Der ZimaOS-Importer von 2025 und das beschädigte exportierte YAML verarbeiteten die gespeicherte Struktur jedoch nicht sauber. Für einen normalen ZimaOS-Service auf einem einzelnen Host lässt sich einfachere Syntax oft leichter validieren:

Ports:
  - "8384:8384"
  - "22000:22000/tcp"
  - "22000:22000/udp"
  - "21027:21027/udp"

Verwenden Sie die erweiterte Langform nur, wenn Sie deren Optionen tatsächlich benötigen.

Host-Netzwerk korrekt verwenden

Wenn die Anwendung das Docker-Host-Netzwerk benötigt, stellt Compose Folgendes bereit:

network_mode: host

Nicht kombinieren network_mode mit einem networks Liste für denselben Service; Docker Compose lehnt diese Kombination derzeit ab.

Dies unterscheidet sich von der Definition eines normalen, vom Benutzer erstellten Netzwerks mit dem Namen Host.

tmpfs ist eine gültige Docker-Compose-Funktion

Die Anwendung des Autors der Quelle benötigte:

tmpfs:
  - /run

Docker Compose unterstützt ausdrücklich tmpfs Mounts. Es kann auch Optionen akzeptieren:

tmpfs:
  - /run
  - /data:mode=755,uid=1000,gid=1000

In der verwendeten ZimaOS-Version bot das Formular für visuelle benutzerdefinierte Apps kein Feld für diese Option, weshalb der Benutzer statt der manuellen Eingabe jeder Einstellung den Compose-Import benötigte.

Aktuelles ZimaOS unterstützt weiterhin den Import von Docker Compose

Die aktuelle ZimaOS-Dokumentation beschreibt diesen Ablauf:

das Dashboard öffnen;
Eine benutzerdefinierte App installieren auswählen;
auf Importieren klicken;
den Tab „Docker Compose“ öffnen;
das YAML einfügen;
die generierten Einstellungen vor der Installation übermitteln und überprüfen.

Dokumentation zu benutzerdefinierten Apps in ZimaOS

So sah die fehlerhafte und die korrigierte Compose-Datei aus

ZimaOS-Import einer benutzerdefinierten App mit fehlerhafter Docker-Compose-Formatierung aus dem gespeicherten Export — Der Autor der Quelle stellte fest, dass der gespeicherte Compose-Text seine vorgesehene YAML-Struktur verloren hatte.

Nach einem teilweise reparierten Syncthing-Docker-Compose-Import angezeigter ZimaOS-Fehler — Erfolgreiches Parsen ist nur die erste Phase; die resultierende Service-Definition muss auch für Docker und ZimaOS gültig sein.

Compose Toolbox validiert und vereinfacht eine ZimaOS-Docker-Compose-Definition — Die Community empfahl, die Compose-Datei vor dem erneuten Import zu validieren und zu vereinfachen.

Bereinigte Syncthing-Docker-Compose-Definition nach dem Entfernen unnötiger Konfiguration — Eine kleinere, standardbasierte Compose-Definition erleichterte das Nachvollziehen und Wiederherstellen der Konfiguration.

Eine einfachere Syncthing-Struktur

Eine übersichtliche Struktur für einen einzelnen Host kann konzeptionell so aussehen:

services:
  syncthing:
    image: syncthing/syncthing:2.0
    container_name: syncthing
    restart: unless-stopped
    network_mode: host
    environment:
      - PUID=1000
      - PGID=1000
    volumes:
      - /DATA/AppData/syncthing/data:/var/syncthing
      - /media/SLOT4/Syncthing:/media/data/syncthing
    tmpfs:
      - /run

Verwende PUID/PGID, Pfade, Netzwerkeinstellungen und den Image-Tag, die für deine eigene Bereitstellung geeignet sind. Im Quellthread verwendete man bei der Fehlersuche Root-IDs, aber das ist kein Grund, jeden Syncthing-Container als Root auszuführen.

Eine exportierte ZimaOS-Compose-Datei ist kein unveränderliches Backup-Format

Der Autor der Quelle sagte, dass die problematische Datei durch den Export von Containern vor der Neuinstallation von ZimaOS entstanden war. Das ist ein nützliches Backup, aber exportierte Anwendungsdefinitionen können von ZimaOS generierte Metadaten oder eine Syntax enthalten, die ausführlicher ist als ein von Hand geschriebener Compose-Stack.

Bevor du dich bei der Notfallwiederherstellung auf exportierte Dateien verlässt:

speichere sie in einem Klartext- oder codegeeigneten Format;
lege sie gegebenenfalls in einer Versionsverwaltung ab;
Validiere sie, solange das ursprüngliche System noch funktioniert;
Sichere persistente AppData-Ordner separat.

Checkliste für den Compose-Import in ZimaOS

Validiere die YAML-Datei vor dem Import.
Ersetze Tabulatoren durch Leerzeichen.
Überprüfe die Einrückung unter ports, volumes, environment und networks.
Stelle sicher, dass jeder Bind-Mount eine Quelle und ein Ziel enthält.
Verwende network_mode: host wenn Host-Netzwerk verwendet werden soll.
Nicht kombinieren network_mode und service networks.
Beibehalten tmpfs in Compose, wenn die visuelle Benutzeroberfläche die Option nicht anbietet.
Entferne generierte/erweiterte Optionen, die die Anwendung nicht benötigt.
Erstelle ein separates Backup der Anwendungsdaten; Compose allein enthält nicht die Daten.

FAQ zum Docker-Compose-Import in ZimaOS

Wurde das ursprüngliche Problem durch den Browser-Cache verursacht?

Nein. Der Autor reproduzierte das Problem nach einer sauberen Neuinstallation von ZimaOS und in einem Inkognito-Browser und bestätigte anschließend, dass Formatierungsprobleme in der gespeicherten Compose-Datei die eigentliche Ursache waren.

Unterstützt ZimaOS tmpfs im visuellen Formular für benutzerdefinierte Apps?

Im Thread von 2025 hieß es, dass die grafische Oberfläche diese Option nicht anbot. Docker Compose selbst unterstützt tmpfs, daher ist der Import der geeignete Pfad für erweiterte Optionen.

Sind mode: ingress und protocol: tcp in Docker Compose ungültig?

Nicht uneingeschränkt. Aktuelles Compose unterstützt die lange Port-Syntax, einschließlich ModusDie praktische Lehre aus dem Ausgangsfall ist, die gesamte YAML-Datei zu validieren und unnötige Komplexität zu entfernen, wenn der ZimaOS-Importer die exportierte Form nicht zuverlässig verarbeiten kann.