homarr/ops

Fork personnel — exploitation

Ce dossier n'existe pas en amont. Il ne créera donc jamais de conflit lors d'un rebase, ce qui est exactement pourquoi les fichiers d'exploitation vivent ici et pas dans scripts/.

Déployer

ops/deploy-lxc.sh --dry-run   # montre ce qui serait écrit, sans rien toucher
ops/deploy-lxc.sh

Le script exige un arbre propre, construit, compare les migrations et l'ABI Node avant de toucher quoi que ce soit, sauvegarde /opt/homarr et la base, arrête le service, synchronise, redémarre, puis affiche les journaux. La commande de retour arrière est imprimée à la fin, horodatage compris.

Ce qu'il ne remplace jamais : /etc/homarr/homarr.env, run.sh, entrypoint.sh, nginx.conf, redis.conf — ils appartiennent à l'installation du LXC, pas au build — ni /var/lib/homarr/db.sqlite, qui est sauvegardée mais laissée en place.

Après déploiement, le contrôle qui compte n'est pas que le nouveau widget s'affiche : c'est que les intégrations préexistantes fonctionnent encore. C'est la seule preuve que SECRET_ENCRYPTION_KEY n'a pas bougé.

Suivre les mises à jour d'Homarr

Aujourd'hui origin pointe sur le dépôt d'Homarr lui-même et aucune copie distante de ce travail n'existe : une panne de disque effacerait la branche. Premier geste, avant tout le reste :

git remote rename origin upstream
git remote add origin <url-de-ton-Gitea>/homarr.git
git push -u origin feat/unifi-os-integration

Le cycle de montée de version

Homarr publie souvent. Se caler sur une étiquette de version plutôt que sur dev évite de rebaser sur du code en cours :

git fetch upstream --tags
git log --oneline dev..upstream/dev | head        # ce qui est arrivé
git rebase v1.78.0 feat/unifi-os-integration      # remplace par la version visée

Puis, dans cet ordre — chaque étape a déjà attrapé quelque chose :

pnpm install                                       # le lockfile bouge presque à chaque version
pnpm turbo typecheck                               # les 37 paquets
pnpm test packages/integrations/ packages/widgets/
pnpm test packages/widgets/src/manifest.spec.ts    # les points d'enregistrement
ops/deploy-lxc.sh --dry-run

manifest.spec.ts mérite sa ligne à part : il compare l'icône du catalogue à celle de la définition par identité, et c'est le seul test qui détecte un point d'enregistrement perdu dans un conflit.

Où les conflits vont tomber

Le gros du travail vit dans des dossiers neufs — packages/integrations/src/unifi-os/, unifi-site-manager/, packages/widgets/src/unifi-*/ — qui ne peuvent pas entrer en conflit. Les points de friction sont les fichiers partagés où ce fork ajoute une ligne dans une liste que l'amont fait vivre aussi :

Fichier	Ce qu'on y ajoute
packages/definitions/src/integration.ts	les deux genres d'intégration
packages/definitions/src/widget.ts	les deux genres de widget
packages/definitions/src/widget-integration-map.ts	l'association widget ↔ intégration
packages/definitions/src/docs/integration-doc-slugs.ts	les slugs de documentation
packages/definitions/src/docs/widget-doc-slugs.ts	idem, côté widgets
packages/integrations/src/base/creator.ts	la construction des classes
packages/integrations/src/index.ts	les exports
packages/integrations/src/types.ts	les types réexportés côté client
packages/api/src/router/widgets/index.ts	les routeurs tRPC
packages/widgets/src/manifest.ts	deux cartes distinctes, module et composant
packages/widgets/src/index.tsx	l'import et l'entrée
packages/widgets/src/catalog.ts	l'icône
packages/widgets/src/refetch-intervals.ts	l'intervalle de rafraîchissement
apps/nextjs/src/components/integration/integration-grid-shared.ts	le libellé de catégorie
apps/nextjs/src/app/[locale]/manage/integrations/_components/secrets/integration-secret-icons.ts	l'icône du secret
packages/translation/src/lang/en.json	tous les libellés

Deux de ces lignes ne sont vérifiées par aucun compilateur, et les perdre dans un conflit passerait tous les tests :

• integration-grid-shared.ts est typé Record<string, string> : une entrée manquante affiche UNIFISITEMANAGER en majuscules collées au lieu du nom.
• en.json n'est pas typé du tout : une clé perdue affiche son chemin brut.

Les deux se voient d'un coup d'œil sur la page « New integration » — c'est le contrôle visuel à faire après chaque montée de version.

Rejouer les résolutions de conflit

Les mêmes conflits reviendront à chaque version, au même endroit. Git sait les rejouer tout seul :

git config rerere.enabled true

À activer avant le premier rebase : Git n'enregistre que ce qu'il voit résoudre. Une fois qu'une résolution est connue, les suivantes sont automatiques — à relire quand même, l'amont peut avoir changé la forme de la liste autour.