Corriger les erreurs d’importation de Docker Compose dans ZimaOS pour les applications personnalisées

Si ZimaOS rejette un fichier Docker Compose lors de Installer une application personnalisée → Importer, ne supposez pas que l’installation de ZimaOS est corrompue. Dans le cas de la communauté datant de septembre 2025, la réinstallation de ZimaOS et une nouvelle tentative dans un navigateur privé n’ont rien changé. Le véritable problème venait du fichier YAML Compose enregistré : son format avait été altéré lors de sa copie dans une application de prise de notes, et la définition exportée comportait une complexité supérieure à celle requise par l’application.

L’utilisateur a corrigé le YAML, simplifié le service Syncthing et confirmé que le problème d’importation était résolu. Le fil met également en évidence un cas d’utilisation important de ZimaOS : des options telles que tmpfs ne dispose peut-être pas d’un champ dédié dans l’éditeur visuel, ce qui rend l’importation Compose nécessaire pour les paramètres avancés des conteneurs.

À quoi ressemblait l’échec de l’importation

L’utilisateur initial exécutait ZimaOS 1.4.3 sur un Beelink Mini et a constaté qu’une application personnalisée précédemment exportée ne pouvait plus être importée après une réinstallation propre.

Validez le YAML avant de dépanner ZimaOS

YAML est sensible à l’indentation. Un seul niveau décalé par une application de prise de notes peut transformer un fichier Compose valide en une structure complètement différente.

L’auteur de la source a finalement constaté que l’exportation enregistrée était mal formatée. Son flux de prise de notes avait modifié la structure après la copie du fichier Compose depuis l’ancienne installation de ZimaOS.

Avant de modifier l’hôte ZimaOS :

1. collez le fichier Compose dans un validateur YAML/Compose ;
2. utilisez des espaces, pas des tabulations ;
3. vérifiez l’indentation de chaque élément de liste et de chaque propriété enfant ;
4. confirmez que chaque montage lié possède une cible côté conteneur ;
5. supprimez les clés en double ;
6. comparez le résultat avec la spécification actuelle de Docker Compose.

Un montage lié complet nécessite une source et une cible

Voici à quoi ressemble un montage lié valide au format long :

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

Docker Compose prend également en charge des paramètres de liaison facultatifs tels que :

bind:
  create_host_path: true

L’exigence principale est que la structure YAML soit valide et que source et cible sont imbriqués sous la même entrée de montage.

Les services Docker Compose font référence à

La syntaxe longue des ports est valide, mais restez simple

L’ancien export contenait des entrées de port détaillées telles que :

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

Docker Compose actuel définit bien mode dans la syntaxe longue des ports, principalement pour le comportement de publication de Swarm. Cela signifie que la clé elle-même n’est pas universellement invalide dans Compose.

Cependant, l’importateur 2025 de ZimaOS et le fichier YAML exporté endommagé ne géraient pas correctement la structure enregistrée. Pour un service ZimaOS normal sur un seul hôte, une syntaxe plus simple est souvent plus facile à valider :

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

N’utilisez la forme longue plus avancée que lorsque vous avez réellement besoin de ses options.

Utiliser correctement le réseau de l’hôte

Si l’application a besoin du réseau de l’hôte Docker, Compose fournit :

network_mode: host

Ne combinez pas network_mode avec un networks liste pour le même service ; Docker Compose actuel rejette cette combinaison.

Cela diffère de la définition d’un réseau normal créé par l’utilisateur, nommé hôte.

tmpfs est une fonctionnalité valide de Docker Compose

L’application de l’auteur de la source nécessitait :

tmpfs:
  - /run

Docker Compose prend explicitement en charge actuellement tmpfs montages. Il peut également accepter des options :

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

Dans la version source de ZimaOS, le formulaire visuel des applications personnalisées ne proposait pas de champ pour cette option, d’où la nécessité pour l’utilisateur d’utiliser l’importation Compose plutôt que de saisir chaque paramètre manuellement.

ZimaOS prend toujours en charge l’importation Docker Compose

La documentation actuelle de ZimaOS décrit ce processus :

1. ouvrez le tableau de bord ;
2. choisissez Installer une application personnalisée ;
3. cliquez sur Importer ;
4. ouvrez l’onglet Docker Compose ;
5. collez le YAML ;
6. soumettre et vérifier les paramètres générés avant l’installation.

Documentation des applications personnalisées de ZimaOS

À quoi ressemblaient les fichiers Compose défectueux et corrigés

Une structure Syncthing plus simple

Une structure simple sur un seul hôte peut conceptuellement ressembler à ceci :

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

Utilisez le PUID/PGID, les chemins, la configuration réseau et le tag d’image appropriés à votre propre déploiement. Le fil source utilisait des identifiants root lors du dépannage, mais ce n’est pas une raison pour exécuter tous les conteneurs Syncthing en tant que root.

Un fichier Compose ZimaOS exporté n’est pas un format de sauvegarde intouchable

L’auteur de la source a indiqué que le fichier problématique provenait de l’exportation de conteneurs avant la réinstallation de ZimaOS. Il s’agit d’une sauvegarde utile, mais les définitions d’applications exportées peuvent contenir des métadonnées générées par ZimaOS ou une syntaxe plus verbeuse qu’une pile Compose rédigée manuellement.

Avant de vous fier aux fichiers exportés pour la reprise après sinistre :

• stockez-les dans un format texte brut ou adapté au code ;
• placez-les sous contrôle de version si nécessaire ;
• validez-les tant que le système d’origine fonctionne encore ;
• Sauvegardez séparément les dossiers AppData persistants.

Liste de vérification pour l’importation de Compose dans ZimaOS

1. Validez le YAML avant l’importation.
2. Remplacez les tabulations par des espaces.
3. Vérifiez l’indentation sous ports, volumes, environment et networks.
4. Faites en sorte que chaque montage bind comporte une source et une cible.
5. Utilisez network_mode: host si le réseau de l’hôte est souhaité.
6. Ne combinez pas network_mode et le service networks.
7. Conservez tmpfs dans Compose si l’interface visuelle ne l’expose pas.
8. Supprimez les options générées ou avancées dont l’application n’a pas besoin.
9. Conservez une sauvegarde distincte des données de l’application ; Compose ne contient pas les données elles-mêmes.

FAQ sur l’importation de Docker Compose dans ZimaOS

Le problème initial était-il dû au cache du navigateur ?

Non. L’auteur a reproduit le problème après une réinstallation propre de ZimaOS et dans un navigateur en mode navigation privée, puis a confirmé que les problèmes de formatage dans le fichier Compose enregistré étaient la véritable cause.

ZimaOS prend-il en charge tmpfs dans le formulaire visuel d’application personnalisée ?

Le fil de discussion de 2025 indiquait que l’interface graphique n’exposait pas cette option. Docker Compose prend lui-même en charge tmpfs; l’importation est donc la voie avancée appropriée.

Les paramètres mode: ingress et protocol: tcp ne sont-ils pas valides dans Docker Compose ?

Compose prend actuellement en charge la syntaxe longue des ports, notamment modeLa leçon pratique à retenir du cas source est de valider l’intégralité du YAML et de supprimer toute complexité inutile lorsque l’importateur de ZimaOS ne peut pas utiliser de manière fiable le format exporté.