Homarr sur CasaOS/ZimaOS : configuration actuelle de Docker Compose

En résumé : utilisez le flux Docker Compose actuel de Homarr plutôt que le modèle BigBear de 2023

L’ancien article sur CasaOS était utile lorsque BigBearCasaOS proposait Homarr pour une installation en un clic. Homarr a considérablement évolué. Son flux actuel d’auto-hébergement utilise Compose et conserve l’état sous /appdata, nécessite une SECRET_ENCRYPTION_KEY, et peut monter facultativement le socket Docker pour les intégrations de conteneurs.

Commencez par une définition Compose persistante

services:
  homarr:
    image: ghcr.io/homarr-labs/homarr:latest
    restart: unless-stopped
    ports:
      - "7575:7575"
    volumes:
      - /DATA/AppData/homarr:/appdata
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - SECRET_ENCRYPTION_KEY=REPLACE_WITH_64_HEX_CHARS

L’installation Docker actuelle de Homarr recommande Compose et documente /appdata.

Générez la clé de chiffrement avant le premier démarrage

openssl rand -hex 32

Homarr utilise ce secret pour protéger les données sensibles des intégrations. Conservez-le en dehors des exports Compose publics. La génération aléatoire sécurisée d’OpenSSL explique la commande.

Ne montez le socket Docker qu’en cas de besoin

Le socket Docker permet de contrôler puissamment l’hôte. Si Homarr a seulement besoin de liens, de favoris et de widgets externes, omettez-le. Ajoutez-le uniquement pour les intégrations compatibles avec Docker que vous utilisez volontairement.

Utilisez l’OpenAPI de ZimaOS pour les données de ZimaOS

Pour le stockage ou l’état du système, utilisez plutôt l’OpenAPI de ZimaOS publiée, au lieu d’analyser le code HTML du tableau de bord. Les exigences des applications ZimaOS couvrent la planification des ressources.

Gardez Homarr en interne jusqu’à ce que l’authentification soit prête

Un tableau de bord peut exposer les adresses IP internes, les ports et l’état de l’infrastructure. Ne le publiez pas directement sans authentification ni HTTPS. Le proxy HTTPS de ZimaOS fournit la couche d’accès public.

Mettre Homarr à jour en tant que conteneur

docker compose down
docker compose pull
docker compose up -d

Persistant /appdata survit à la recréation. C’est pourquoi le volume est plus important que la conservation de l’ancien conteneur.

Ne placez pas la configuration de Homarr uniquement dans le conteneur

Si /appdata n’est pas associé à un stockage hôte persistant, la recréation du conteneur peut effacer la configuration. Sauvegardez le dossier Homarr côté hôte. La sauvegarde ZimaOS fournit la couche de récupération.

Utilisez Homarr comme portail d’accès, pas comme contournement de l’administration

Homarr peut centraliser les liens et afficher des états en lecture seule, mais chaque application sous-jacente possède toujours sa propre authentification. N’intégrez pas d’identifiants administrateur dans des widgets publics pour permettre un accès en un clic.

Construisez le tableau de bord par étapes au lieu de tout connecter dès le premier jour

Commencez par de simples liens vers ZimaOS, Plex, Home Assistant et d’autres services. Une fois le tableau de bord lui-même stabilisé, ajoutez une intégration à la fois. Vous pourrez ainsi identifier clairement l’intégration responsable d’une boucle de connexion, d’un chargement de page lent ou d’un problème d’autorisation. Un tableau de bord avec vingt intégrations d’API peut donner l’impression qu’une seule application est défaillante, même lorsqu’un seul service backend ne répond plus.

Utilisez des noms d’hôte internes ou des adresses IP LAN stables

Les instructions actuelles d’Homarr pour les conteneurs recommandent un nom d’hôte ou une adresse IP directe que les clients de votre réseau peuvent résoudre. Si vous utilisez un proxy inverse, conservez un nom d’hôte public cohérent et assurez-vous que les requêtes WebSocket/API utilisent la même origine. Évitez de coder en dur des adresses IP Docker temporaires, car elles peuvent changer lorsque les conteneurs sont recréés.

Ne sauvegardez pas uniquement la jolie mise en page

Votre tableau de bord peut contenir des identifiants d’intégration chiffrés, des comptes utilisateur, des icônes et des métadonnées de services. Conservez l’intégralité du répertoire persistant /appdata répertoire ainsi que la clé de chiffrement. Testez une restauration dans un conteneur Homarr temporaire avant de vous fier à la sauvegarde.

Soyez prudent avec les mises à jour automatiques des conteneurs

Un tableau de bord est souvent le premier endroit où l’on remarque si le reste du homelab fonctionne correctement. Si Homarr se met à jour automatiquement et tombe en panne en même temps qu’un autre service, le diagnostic devient plus difficile. Épinglez une version connue comme fiable ou effectuez les mises à jour manuellement lorsque la disponibilité est importante, puis passez à une version plus récente après les tests.

Notez la balise exacte de l’image Homarr après chaque mise à niveau réussie afin de simplifier le retour en arrière.

FAQ

BigBearCasaOS est-il toujours nécessaire pour Homarr ?

Non. Homarr publie ses propres instructions à jour pour l’installation de Docker et de Compose.

Qu’est-ce que SECRET_ENCRYPTION_KEY ?

Il s’agit d’un secret persistant qu’Homarr utilise pour protéger les données sensibles des intégrations.

Ai-je besoin du socket Docker ?

Uniquement pour les intégrations compatibles avec Docker ou le contrôle des conteneurs.

Homarr peut-il afficher les données système de ZimaOS ?

Potentiellement via des intégrations personnalisées utilisant l’OpenAPI de ZimaOS.

Comment mettre à jour Homarr en toute sécurité ?

Conservez /appdata, récupérez l’image la plus récente, recréez le service et vérifiez le tableau de bord avant de supprimer les anciennes images.