Risolvi gli errori di importazione di Docker Compose in ZimaOS per le app personalizzate

Se ZimaOS rifiuta un file Docker Compose durante Install a Customized App → Import, non presumere che l'installazione di ZimaOS sia danneggiata. Nel caso della community di settembre 2025, reinstallare ZimaOS e riprovare in una finestra del browser in incognito non ha prodotto alcuna differenza. Il problema reale era il file YAML Compose salvato: la formattazione era stata danneggiata durante la copia negli appunti e la definizione esportata conteneva più complessità di quanta l'applicazione necessitasse.

L'utente ha corretto il file YAML, semplificato il servizio Syncthing e confermato che il problema di importazione era stato risolto. La discussione evidenzia anche un importante caso d'uso di ZimaOS: opzioni come tmpfs potrebbe non avere un campo dedicato nell'editor visuale, quindi l'importazione Compose rimane necessaria per le impostazioni avanzate dei container.

Come appariva il problema di importazione

L'utente originale eseguiva ZimaOS 1.4.3 su un Beelink Mini e ha riscontrato che un'applicazione personalizzata precedentemente esportata non veniva più importata dopo una reinstallazione pulita.

Convalidare il file YAML prima di risolvere i problemi di ZimaOS

YAML è sensibile all'indentazione. Un singolo livello spostato da un'app per prendere appunti può trasformare un Compose valido in una struttura completamente diversa.

L'autore originale alla fine si è accorto che l'esportazione salvata era formattata male. Il suo flusso di lavoro per prendere appunti aveva alterato la struttura dopo che il file Compose era stato copiato dalla vecchia installazione di ZimaOS.

Prima di modificare l'host ZimaOS:

1. incollare il file Compose in un validatore YAML/Compose;
2. usare spazi, non tabulazioni;
3. controllare l'indentazione di ogni elemento dell'elenco e delle relative proprietà;
4. verificare che ogni montaggio bind abbia una destinazione sul lato container;
5. rimuovere le chiavi duplicate;
6. confrontare il risultato con la specifica Docker Compose attuale.

Un montaggio bind completo richiede sia l'origine sia la destinazione

Un montaggio bind valido in formato esteso è simile al seguente:

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

Docker Compose attualmente supporta anche impostazioni bind facoltative come:

bind:
  create_host_path: true

Il requisito principale è che la struttura YAML sia valida e che origine e destinazione sono nidificati sotto la stessa voce di montaggio.

I servizi Docker Compose fanno riferimento a

La sintassi estesa delle porte è valida, ma mantienila semplice

La vecchia esportazione conteneva voci delle porte dettagliate come:

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

Docker Compose attuale definisce modalità nella sintassi estesa delle porte, principalmente per il comportamento di pubblicazione di Swarm. Ciò significa che la chiave in sé non è universalmente non valida in Compose.

Tuttavia, l’importatore di ZimaOS del 2025 e il file YAML esportato danneggiato non gestivano correttamente la struttura salvata. Per un normale servizio ZimaOS su un singolo host, una sintassi più semplice è spesso più facile da convalidare:

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

Usa la forma estesa più avanzata solo quando ti servono effettivamente le relative opzioni.

Usa correttamente la rete host

Se l’applicazione necessita della rete host di Docker, Compose offre:

network_mode: host

Non combinare network_mode con una le reti list per lo stesso servizio; Docker Compose attuale rifiuta questa combinazione.

Questo è diverso dalla definizione di una normale rete creata dall’utente denominata host.

tmpfs è una funzionalità valida di Docker Compose

L’applicazione dell’autore originale richiedeva:

tmpfs:
  - /run

Docker Compose attuale supporta esplicitamente tmpfs montaggi. Può anche accettare opzioni:

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

Nella versione di ZimaOS in questione, il modulo visivo per le app personalizzate non offriva un campo per questa opzione; per questo l’utente doveva usare l’importazione Compose invece di inserire manualmente ogni impostazione.

ZimaOS continua a supportare l’importazione di Docker Compose

La documentazione attuale di ZimaOS descrive questo flusso di lavoro:

1. apri la dashboard;
2. seleziona Installa un’app personalizzata;
3. fai clic su Importa;
4. apri la scheda Docker Compose;
5. incolla lo YAML;
6. invia e verifica le impostazioni generate prima dell’installazione.

Documentazione sulle app personalizzate di ZimaOS

Come appariva il Compose danneggiato e quello corretto

Una struttura Syncthing più semplice

Una struttura pulita per un singolo host può avere concettualmente questo aspetto:

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

Usa PUID/PGID, percorsi, rete e tag dell'immagine appropriati per la tua distribuzione. La discussione originale usava gli ID root durante la risoluzione del problema, ma questo non è un motivo per eseguire come root ogni container Syncthing.

Un file Compose esportato da ZimaOS non è un formato di backup intoccabile

L'autore della fonte ha affermato che il file problematico proveniva dall'esportazione dei container prima della reinstallazione di ZimaOS. È un backup utile, ma le definizioni delle applicazioni esportate possono contenere metadati generati da ZimaOS o una sintassi più prolissa rispetto a uno stack Compose scritto manualmente.

Prima di affidarti ai file esportati per il ripristino in caso di emergenza:

• conservali in un formato di testo semplice o compatibile con il codice;
• inseriscili nel controllo versione, se appropriato;
• convalidali mentre il sistema originale funziona ancora;
• Esegui separatamente il backup delle cartelle AppData persistenti.

Checklist per l'importazione di Compose in ZimaOS

1. Convalida il YAML prima dell'importazione.
2. Sostituisci le tabulazioni con spazi.
3. Controlla l'indentazione dell'elenco sotto ports, volumes, environment e networks.
4. Fai in modo che ogni bind mount includa un'origine e una destinazione.
5. Usa network_mode: host se è previsto l'uso della rete dell'host.
6. Non combinare network_mode e il servizio le reti.
7. Mantieni tmpfs in Compose se l'interfaccia visiva non la espone.
8. Rimuovi le opzioni generate/avanzate che l'applicazione non necessita.
9. Conserva un backup separato dei dati dell'applicazione; Compose da solo non costituisce un backup dei dati.

FAQ sull'importazione di Docker Compose in ZimaOS

Il problema originale era causato dalla cache del browser?

No. L'autore ha riprodotto il problema dopo una reinstallazione pulita di ZimaOS e in un browser in incognito, confermando poi che il vero problema erano gli errori di formattazione nel file Compose salvato.

ZimaOS supporta tmpfs nel modulo visivo per le app personalizzate?

La discussione del 2025 affermava che la GUI non esponeva quell'opzione. Docker Compose supporta direttamente tmpfs, quindi l'importazione è il percorso avanzato appropriato.

Sono non valide in Docker Compose le opzioni mode: ingress e protocol: tcp?

Non universalmente. Compose attualmente supporta la sintassi estesa delle porte, inclusa modalità. La lezione pratica del caso originale è convalidare l'intero YAML e rimuovere la complessità non necessaria quando l'importatore di ZimaOS non riesce a utilizzare in modo affidabile il formato esportato.