Comment auto-héberger Homarr en 2026 : dashboards, secrets et tuiles en temps réel

Un container Homarr peut être au vert alors que la fonctionnalité qui importe aux utilisateurs est en panne. Pour Homarr, cette panne invisible vient généralement du fait que les widgets ne parviennent pas à joindre les services parce qu’ils utilisent des adresses locales à l’hôte. Ce guide considère comme test d’acceptation le scénario suivant : « créer un tableau de bord, ajouter une tuile de service, configurer une intégration avec identifiants et confirmer l’état en temps réel ainsi que la recherche après un redémarrage », puis construit le déploiement à rebours à partir de ce résultat.

Homarr a un rôle bien précis dans la stack : fournir un dashboard avec recherche et tuiles en temps réel pour les services auto-hébergés. La question à se poser en production n’est donc pas de savoir si le port 7575 répond une fois, mais si l’état, les dépendances et l’adresse publique restent cohérents après un redémarrage, une mise à jour et une restauration.

Définir d’abord la réussite de Homarr

Ne laissez pas l’image Homarr choisir accidentellement l’architecture de production. L’image fournit un processus sur le port 7575 ; le stockage, le routage et les exigences externes nécessitent toujours des cycles de vie définis avec soin. L’exigence du runtime local est de disposer de données applicatives persistantes et d’identifiants pour les intégrations en temps réel. Cela doit figurer dans le plan de capacité et de montage, avec un responsable et une limite mesurable.

Le déploiement est prêt pour des tests plus poussés lorsqu’il peut créer un tableau de bord, ajouter une tuile de service, configurer une intégration avec identifiants et confirmer l’état en temps réel ainsi que la recherche après un redémarrage. Suivez la transaction dans les logs et surveillez la multiplication des requêtes des widgets, la latence des API en aval, la taille des données applicatives et le nombre de clients simultanés du dashboard. Ces observations permettent de déterminer si la topologie actuelle isole le bon composant.

Répéter la modification Homarr à risque

Un container au vert est nécessaire, mais pas suffisant. L’indicateur de niveau de service est la réussite du scénario « créer un tableau de bord, ajouter une tuile de service, configurer une intégration avec identifiants et confirmer l’état en temps réel ainsi que la recherche après un redémarrage », tandis que les principaux signaux de pression sont la multiplication des requêtes des widgets, la latence des API en aval, la taille des données applicatives et le nombre de clients simultanés du dashboard.

La gestion des changements est importante, car les migrations de schéma Homarr et la continuité de la clé de chiffrement peuvent affecter les identifiants d’intégration stockés. Conservez l’ancienne image, testez les migrations sur une copie de l’état et documentez la prise en charge ou non du rollback après l’évolution du schéma. Si les widgets ne parviennent pas à joindre les services parce qu’ils utilisent des adresses locales à l’hôte, identifiez la première frontière qui diffère de l’environnement fonctionnel.

Documenter un déploiement Homarr connu comme fonctionnel

Ne faites pas du trafic du premier utilisateur le test d’acceptation de Homarr. Préparez un état d’exemple sans risque et exécutez l’action complète suivante : « créer un tableau de bord, ajouter une tuile de service, configurer une intégration avec identifiants et confirmer l’état en temps réel ainsi que la recherche après un redémarrage ». Notez l’URL publique exacte, le résultat, la référence de l’image et l’intervalle de logs associés à cette exécution.

Remplacez le container et recommencez sans reconstruire les données. Ensuite, effectuez une récupération sur un hôte vide ; la condition de récupération est que les tableaux de bord, les utilisateurs, les intégrations et les assets personnalisés soient restaurés et que les widgets utilisant des identifiants se reconnectent. Observez la multiplication des requêtes des widgets, la latence des API en aval, la taille des données applicatives et le nombre de clients simultanés du dashboard à chaque étape, puis définissez une alerte autour de la dégradation de la transaction plutôt qu’autour de métriques de container inactif.

Un dernier contrôle doit volontairement échouer : envoyez une entrée sans risque proche de la limite de ressource ou de format associée à cette frontière : les widgets ne parviennent pas à joindre les services parce qu’ils utilisent des adresses locales à l’hôte. Vérifiez que le message Homarr qui en résulte identifie la frontière concernée au lieu de déclencher une suppression de données ou un redémarrage sans fin. Rétablissez la condition valide et confirmez que la même transaction d’exemple réussit. Conservez ce court exercice dans la checklist de release.

Lancer la première instance représentative de la production

Le premier container doit être facile à supprimer et à recréer. Conservez les données en dehors de la writable layer, ne liez le port 7575 que là où le proxy peut l’atteindre et transmettez la configuration au runtime.

docker run -d \
  --name homarr \
  --restart unless-stopped \
  -p 127.0.0.1:7575:7575 \
  -v homarr-data:/appdata \
  -e SECRET_ENCRYPTION_KEY=replace-with-a-long-random-value \
  ghcr.io/homarr-labs/homarr:latest

Figez la version de l’image après le test initial. Lisez la première erreur de démarrage plutôt que le dernier message de redémarrage, vérifiez chaque montage avec docker inspect et suivez les logs pendant que vous créez un tableau de bord, ajoutez une tuile de service, configurez une intégration avec identifiants et confirmez l’état en temps réel ainsi que la recherche après un redémarrage. Cette séquence permet de distinguer une mauvaise commande d’image d’un problème de dépendance ou de permissions.

Les volumes ne constituent que la première couche de récupération

Pour Homarr, la sécurité d’un redéploiement commence par les tableaux de bord, les utilisateurs, les intégrations, les secrets et les assets personnalisés. Montez /appdata avant le bootstrap, écrivez des données d’exemple sans risque et remplacez le container afin de prouver que ce chemin est effectivement persistant. Testez le chemin en remplaçant le container alors que les données d’exemple sont présentes ; cela révèle les montages pointant un répertoire trop haut ou trop bas.

Testez ensuite la reprise après sinistre sur un hôte vierge. Utilisez si nécessaire un export de base de données cohérent au niveau applicatif et vérifiez que les tableaux de bord, les utilisateurs, les intégrations et les assets personnalisés sont restaurés et que les widgets utilisant des identifiants se reconnectent. Le guide sur les sauvegardes de bases de données dont la restauration a été testée constitue une cible plus solide que la simple vérification de la création d’un fichier d’archive.

Éviter que la réussite du proxy masque une panne applicative

Le navigateur, le client API et Homarr doivent utiliser une même origin. Pour y parvenir, définissez le hostname HTTPS externe et les origins autorisées. Conservez l’hôte et le protocole d’origine tout en empêchant le port 7575 de devenir une autre adresse publique concurrente.

Le guide de dépannage d’un site inaccessible aide à distinguer une route inaccessible d’une application qui répond. Cette distinction est importante ici : les widgets ne parviennent pas à joindre les services parce qu’ils utilisent des adresses locales à l’hôte. Seule la première situation se résout par des changements d’ingress ; la seconde nécessite d’inspecter les logs, l’état ou la charge de travail Homarr.

Fermer les accès temporaires de configuration

Un déploiement Homarr sécurisé commence par la suppression des droits superflus. Évitez de modifier la clé de chiffrement une fois les secrets d’intégration stockés ; gardez plutôt SECRET_ENCRYPTION_KEY stable, protégez la modification des tableaux de bord et limitez les identifiants de chaque widget.

Générez SECRET_ENCRYPTION_KEY une seule fois, ne le stockez pas dans Git et conservez-le avec le manifeste de récupération, car sa modification peut invalider l’état applicatif chiffré ou signé. Limitez les routes d’administration, utilisez un DNS privé pour les dépendances et examinez chaque bind mount. Lorsque les logs sont envoyés vers un système centralisé, filtrez les secrets et le contenu privé avant leur sortie du serveur.

Déplacer le travail d’infrastructure répétable vers Dockup

Pour Homarr, Dockup est particulièrement utile à la frontière entre une image et un service durable. Il conserve la route vers 7575, le TLS, les valeurs de secrets et le stockage lors des remplacements de containers, que le compute soit fourni par Dockup ou par votre serveur connecté.

Terminez avec les éléments propres à l’application : définissez le hostname HTTPS externe et les origins autorisées ; confirmez l’exigence locale — des données applicatives persistantes et des identifiants pour les intégrations en temps réel — puis exécutez cette vérification : créer un tableau de bord, ajouter une tuile de service, configurer une intégration avec identifiants et confirmer l’état en temps réel ainsi que la recherche après un redémarrage. Conservez le résultat comme contrôle de déploiement afin que la prochaine mise à jour de l’image soit évaluée sur son comportement plutôt que sur l’état du container.

Foire aux questions

De quoi Homarr a-t-il besoin pour un déploiement en production ?

Faites passer le container Homarr sur le port 7575 via une seule origin HTTPS. L’exigence du runtime local est de disposer de données applicatives persistantes et d’identifiants pour les intégrations en temps réel. Ne considérez pas Homarr comme prêt tant que vous ne pouvez pas créer un tableau de bord, ajouter une tuile de service, configurer une intégration avec identifiants et confirmer l’état en temps réel ainsi que la recherche après un redémarrage.

Quelles données Homarr doivent figurer dans une sauvegarde ?

Faites persister /appdata et incluez les tableaux de bord, les utilisateurs, les intégrations, les secrets et les assets personnalisés dans le même manifeste de récupération. Une restauration Homarr propre n’est validée que lorsque les tableaux de bord, les utilisateurs, les intégrations et les assets personnalisés sont restaurés et que les widgets utilisant des identifiants se reconnectent.

Homarr nécessite-t-il HTTPS derrière un reverse proxy ?

Utilisez HTTPS pour l’origin publique de Homarr et conservez le port 7575 sur la route interne. Appliquez correctement le paramètre Homarr : définissez le hostname HTTPS externe et les origins autorisées. Pour Homarr, HTTPS protège les identifiants ou le contenu utilisateur pendant leur transmission et garantit un comportement cohérent du client lorsque celui-ci dépend de l’origin.

Comment tester une mise à niveau de Homarr ?

Restaurez l’état actuel de Homarr dans un déploiement isolé, appliquez la version candidate et répétez sa transaction d’acceptation. Soyez particulièrement attentif, car les migrations de schéma Homarr et la continuité de la clé de chiffrement peuvent affecter les identifiants d’intégration stockés. Conservez l’ancienne image Homarr jusqu’à ce que les limites de migration des données et de rollback soient bien comprises.