Los importfouten van ZimaOS Docker Compose voor aangepaste apps oplossen

Als ZimaOS een Docker Compose-bestand afwijst tijdens Een aangepaste app installeren → Importeren, ga er dan niet van uit dat de ZimaOS-installatie beschadigd is. In de communitycasus van september 2025 maakten het opnieuw installeren van ZimaOS en opnieuw proberen in een incognitobrowser geen verschil. Het werkelijke probleem was de opgeslagen Compose-YAML: de opmaak was beschadigd toen deze in notities werd gekopieerd, en de geëxporteerde definitie bevatte meer complexiteit dan de applicatie nodig had.

De gebruiker herstelde de YAML, vereenvoudigde de Syncthing-service en bevestigde dat het importprobleem was opgelost. De thread benadrukt ook een belangrijk gebruiksscenario van ZimaOS: opties zoals tmpfs heeft mogelijk geen apart veld in de visuele editor, waardoor Compose-import noodzakelijk blijft voor geavanceerde containerinstellingen.

Zo zag de importfout eruit

De oorspronkelijke gebruiker draaide ZimaOS 1.4.3 op een Beelink Mini en ontdekte dat een eerder geëxporteerde aangepaste applicatie na een schone herinstallatie niet langer kon worden geïmporteerd.

Valideer de YAML voordat je problemen met ZimaOS oplost

YAML is gevoelig voor inspringing. Eén niveau dat door een notitie-app wordt verschoven, kan geldige Compose omzetten in een compleet andere structuur.

De auteur van de bron merkte uiteindelijk dat de opgeslagen export slecht was opgemaakt. De workflow voor het maken van notities had de structuur gewijzigd nadat het Compose-bestand uit de oude ZimaOS-installatie was gekopieerd.

Voordat je de ZimaOS-host wijzigt:

1. plak het Compose-bestand in een YAML-/Compose-validator;
2. gebruik spaties, geen tabs;
3. controleer de inspringing van elk lijstitem en elke onderliggende eigenschap;
4. bevestig dat elke bind-mount een doel aan de containerzijde heeft;
5. verwijder dubbele sleutels;
6. vergelijk het resultaat met de huidige Docker Compose-specificatie.

Een complete bind-mount heeft zowel een bron als een doel nodig

Een geldige bind-mount in lange notatie ziet er als volgt uit:

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

De huidige Docker Compose ondersteunt ook optionele bind-instellingen, zoals:

bind:
  create_host_path: true

De belangrijkste vereiste is dat de YAML-structuur geldig is en dat bron en doel vallen onder dezelfde mountvermelding.

Docker Compose-services verwijzen naar

Lange poortnotatie is geldig, maar houd het eenvoudig

De oude export bevatte uitgebreide poortvermeldingen zoals:

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

De huidige Docker Compose definieert wel modus in de lange poortnotatie, voornamelijk voor publicatiegedrag in Swarm. Dat betekent dat de sleutel zelf niet in alle gevallen ongeldig is in Compose.

De ZimaOS-importer uit 2025 en de beschadigde geëxporteerde YAML verwerkten de opgeslagen structuur echter niet goed. Voor een normale ZimaOS-service op één host is eenvoudigere syntaxis vaak gemakkelijker te valideren:

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

Gebruik de geavanceerdere lange notatie alleen wanneer je de opties ervan daadwerkelijk nodig hebt.

Hostnetwerken correct gebruiken

Als de toepassing Docker-hostnetwerken nodig heeft, biedt Compose:

network_mode: host

Combineer niet network_mode met een netwerken lijst voor dezelfde service; de huidige Docker Compose weigert die combinatie.

Dit verschilt van het definiëren van een normaal door de gebruiker aangemaakt netwerk met de naam host.

tmpfs is een geldige Docker Compose-functie

De toepassing van de auteur van de bron vereiste:

tmpfs:
  - /run

De huidige Docker Compose ondersteunt expliciet tmpfs koppelingen. Het kan ook opties accepteren:

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

In de ZimaOS-versie uit de bron bood het visuele formulier voor aangepaste apps geen veld voor deze optie. Daarom moest de gebruiker Compose importeren in plaats van elke instelling handmatig in te voeren.

De huidige ZimaOS-versie ondersteunt nog steeds importeren via Docker Compose

De huidige ZimaOS-documentatie beschrijft deze workflow:

1. open het dashboard;
2. kies Een aangepaste app installeren;
3. klik op Importeren;
4. open het tabblad Docker Compose;
5. plak de YAML;
6. dien de gegenereerde instellingen in en controleer ze vóór de installatie.

Documentatie voor aangepaste apps van ZimaOS

Hoe de defecte en gecorrigeerde Compose eruitzagen

Een eenvoudigere Syncthing-structuur

Een eenvoudige indeling voor één host kan er conceptueel als volgt uitzien:

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

Gebruik de PUID/PGID, paden, netwerken en imagetag die geschikt zijn voor je eigen implementatie. In de brondiscussie gebruikte men tijdens het oplossen van problemen root-ID's, maar dat is geen reden om elke Syncthing-container als root uit te voeren.

Een geëxporteerd ZimaOS Compose-bestand is geen onaantastbaar back-upformaat

De auteur van de bron zei dat het problematische bestand was ontstaan door containers te exporteren voordat ZimaOS opnieuw werd geïnstalleerd. Dat is een nuttige back-up, maar geëxporteerde applicatiedefinities kunnen door ZimaOS gegenereerde metadata of syntaxis bevatten die uitgebreider is dan een handgeschreven Compose-stack.

Voordat je voor noodherstel op geëxporteerde bestanden vertrouwt:

• bewaar ze in een indeling als platte tekst of code;
• zet ze indien passend onder versiebeheer;
• valideer ze terwijl het oorspronkelijke systeem nog werkt;
• maak afzonderlijk een back-up van persistente AppData-mappen.

Checklist voor het importeren van Compose in ZimaOS

1. Valideer YAML vóór het importeren.
2. Vervang tabs door spaties.
3. Controleer de inspringing van lijsten onder ports, volumes, environment en networks.
4. Zorg ervoor dat elke bind-mount een bron en doel bevat.
5. Gebruik network_mode: host als hostnetwerken bedoeld is.
6. Combineer niet network_mode en service netwerken.
7. Behoud tmpfs in Compose als de visuele interface dit niet beschikbaar maakt.
8. Verwijder gegenereerde/geavanceerde opties die de applicatie niet nodig heeft.
9. Bewaar een afzonderlijke back-up van applicatiegegevens; alleen Compose bevat de gegevens niet.

Veelgestelde vragen over het importeren van Docker Compose in ZimaOS

Werd het oorspronkelijke probleem veroorzaakt door de browsercache?

Nee. De auteur reproduceerde het probleem na een schone herinstallatie van ZimaOS en in een incognitobrowser en bevestigde vervolgens dat opmaakproblemen in de opgeslagen Compose het werkelijke probleem waren.

Ondersteunt ZimaOS tmpfs in het visuele formulier voor aangepaste apps?

In de thread uit 2025 stond dat de GUI die optie niet beschikbaar maakte. Docker Compose ondersteunt zelf tmpfs, dus importeren is de aangewezen geavanceerde optie.

Zijn mode: ingress en protocol: tcp ongeldig in Docker Compose?

Niet universeel. De huidige Compose-versie ondersteunt de uitgebreide poortsyntaxis, inclusief modusDe praktische les uit de broncasus is om de volledige YAML te valideren en onnodige complexiteit te verwijderen wanneer de ZimaOS-importeur de geëxporteerde vorm niet betrouwbaar kan gebruiken.