Serveur

Administration du serveur

Démarrer, sauvegarder, restaurer, mettre à jour, dépanner.

Toutes les opérations courantes passent par myhabitactl, installé dans /usr/local/sbin. Lancez-le en root (sudo).

sudo myhabitactl status          # services, version active, santé
sudo myhabitactl doctor          # diagnostic : services, ports, disque, sauvegarde, certificat
sudo myhabitactl logs            # journal du moteur en direct (Ctrl+C pour quitter)
sudo myhabitactl logs myhabita-zigbee2mqtt

Démarrer, arrêter, redémarrer

sudo myhabitactl start | stop | restart   # le moteur My Habita
sudo systemctl restart mosquitto          # broker MQTT
sudo systemctl restart myhabita-zigbee2mqtt myhabita-matter

Tous les services démarrent automatiquement avec la machine : myhabita, mosquitto, nginx, avahi-daemon, myhabita-matter et le minuteur myhabita-backup.timer. myhabita-zigbee2mqtt démarre seulement une fois le coordinateur choisi dans l'assistant.

Première connexion

1. Ouvrez http://<adresse-du-serveur>/ ou http://<nom-du-serveur>.local/.
2. Affichez le code d'installation : sudo myhabitactl setup-code.
3. Suivez l'assistant (administrateur, maison, pièces). Le code est ensuite supprimé.

Mot de passe oublié : sudo myhabitactl reset-password <identifiant>. Le nouveau mot de passe est affiché une seule fois.

Mettre à jour

Les mises à jour ne sont jamais automatiques : ni celles de My Habita, ni celles de Zigbee2MQTT et du serveur Matter (versions épinglées), ni Node.js (branche 24 figée par un pin apt). Il n'y a pas non plus de unattended-upgrades sur cette machine.

cd /opt/myhabita && git log --oneline | head   # la version à déployer doit être validée (commit)
sudo myhabitactl update                         # ou : sudo myhabitactl update <commit|étiquette>

Déroulement : construction de la version depuis le commit Git (releases/<date>-<commit>/), vérification des types, compilation, test de démarrage à vide, sauvegarde complète (motif pre-update), activation, contrôle de santé. En cas d'échec, retour automatique à la version précédente. Si la base a été migrée entre-temps, les données de la sauvegarde pre-update sont restaurées aussi.

Les 4 dernières versions sont conservées : sudo myhabitactl releases.

Mises à jour d'une installation par le site

Sur une installation faite avec le script d'installation (et non depuis le dépôt Git), les mises à jour se font aussi depuis Réglages → Système, carte « Mises à jour » (administrateurs) :

• My Habita vérifie le serveur de mises à jour quelques minutes après son démarrage, puis toutes les 12 h environ (updates.checkHours dans /etc/myhabita/myhabita.json). Le bouton « Rechercher les mises à jour » vérifie tout de suite. Une nouvelle version est signalée une fois par une notification.
• Canal : « Stable » (par défaut) ou « Bêta » (versions d'essai, publiées avant). Le choix fait sur le site remplace celui de /etc/myhabita/myhabita.json.
• La liste des versions est signée : un manifeste dont la signature ne correspond pas à la clé installée (/etc/myhabita/update-key.pub) est refusé (« Signature du serveur de mises à jour invalide »).
• Rien ne s'installe sans votre accord : « Installer la mise à jour » fait d'abord une sauvegarde complète, puis My Habita redémarre (environ une minute d'indisponibilité). En cas d'échec, retour automatique à la version précédente, avec les données d'avant si la base avait changé. La page suit l'avancement et propose de se recharger une fois la nouvelle version en service.
• Le moteur n'a toujours aucun droit root : il dépose la demande dans /var/lib/myhabita/update-request.json et démarre myhabita-update.service (règle polkit : démarrage seulement), qui fait la mise à jour et écrit son avancement dans /var/lib/myhabita/update-run.json. Journal : journalctl -u myhabita-update.

sudo myhabitactl update fonctionne toujours sur le serveur, avec le même déroulement. Sur une installation de développement (dépôt Git), le site ne vérifie rien : la mise à jour se fait depuis le dépôt, comme ci-dessus.

En ligne de commande, sur une installation faite avec le script d'installation :

sudo myhabitactl version                 # version active, canal, commit
sudo myhabitactl check-update            # une version plus récente existe-t-elle ? (rien n'est installé)
sudo myhabitactl update                  # télécharger, vérifier et installer la dernière version du canal
sudo myhabitactl update --version 1.2.0  # une version précise du canal
sudo myhabitactl channel beta            # changer de canal (stable ou beta)

Revenir en arrière : application ou données ?

Ce sont deux opérations distinctes.

• Revenir à une version antérieure de l'application : sudo myhabitactl rollback [version]. C'est possible tant que le schéma de données n'a pas changé (le 18/10/2026, la base est passée en version 2 puis 3 : revenir avant ces versions demande aussi les données d'avant la migration, voir ci-dessous). My Habita refuse de démarrer sur une base plus récente que son code, pour ne rien abîmer.
• Restaurer les données d'avant une migration : une version qui migre la base crée d'abord une copie dans /var/lib/myhabita/pre-migration/, et la mise à jour a aussi fait une sauvegarde pre-update. Pour revenir à la fois au code et aux données :

  sudo myhabitactl rollback <version> --with-data /var/backups/myhabita/myhabita-<date>-pre-update.tar.zst
  

  Les changements faits depuis cette sauvegarde (nouveaux appareils, historique récent) sont alors perdus.

Mettre à jour Zigbee2MQTT ou le serveur Matter

Changez la version épinglée, après avoir lu les notes de version et fait une sauvegarde :

sudo myhabitactl backup
sudo Z2M_VERSION=2.15.0 /opt/myhabita/scripts/install-zigbee2mqtt.sh && sudo systemctl restart myhabita-zigbee2mqtt
sudo MATTER_VERSION=1.5.0 /opt/myhabita/scripts/install-matter.sh

Pensez à reporter la nouvelle version épinglée dans docs/versions-et-sources.md.

Vidéosurveillance

sudo myhabitactl nvr-install --restart     # ffmpeg (Debian) + go2rtc (publication officielle, empreinte vérifiée) + analyse IA, puis redémarrage du moteur
sudo myhabitactl nvr-install --no-ai       # sans l'analyse IA
sudo myhabitactl nvr-install --check       # état seulement
sudo myhabitactl nvr-storage list          # dossiers d'enregistrement autorisés
sudo myhabitactl nvr-storage add /srv/videos
sudo myhabitactl nvr-storage nfs 192.168.1.10:/volume1/cameras [nom]
sudo myhabitactl nvr-storage smb //nas/cameras utilisateur [nom]

• go2rtc est lancé et surveillé par le moteur (pas de service séparé) : API sur 127.0.0.1:1984, RTSP sur 127.0.0.1:8554, WebRTC sur le port 8555 (TCP et UDP), à laisser joignable depuis le réseau local pour le direct à faible latence (sinon le direct passe par le moteur).
• Les enregistrements (/var/lib/myhabita/recordings par défaut) et leur index video.db ne sont pas sauvegardés ; la clé des codes de l'alarme (alarm-codes.key) l'est. L'index se reconstruit : Sécurité → Réglages → Stockage → « Relire les dossiers ».
• Analyse IA (personnes, véhicules, animaux ; visages, animaux et véhicules nommés ; inventaire et objets surveillés) : ONNX Runtime et les modèles YOLOX-Tiny, YuNet, SFace et MobileNetV2 dans /opt/myhabita/vendor/ai/ (≈ 115 Mo, versions et empreintes épinglées dans scripts/install-ai.sh, voir docs/versions-et-sources.md ; une installation plus ancienne est complétée par sudo myhabitactl nvr-install --restart, qui ne télécharge que les modèles manquants). Données (identités, visages, inventaire) : tables de video.db et photos dans /var/lib/myhabita/video/ai/, non sauvegardées ; tout effacer : Sécurité → Analyse IA → Réglages → « Effacer toutes les données des visages ». Le moteur lance l'analyse dans un processus séparé (node …/dist/ai-worker.mjs, priorité basse, 2 fils de calcul) seulement quand une caméra en a besoin, et l'arrête après 10 minutes sans travail ; état dans Sécurité → Réglages → Stockage et système vidéo. Après une installation, redémarrez le moteur (--restart). Désinstaller : sudo rm -rf /opt/myhabita/vendor/ai puis sudo myhabitactl restart.
• Un autre disque ou un NAS doit être autorisé par nvr-storage (protection systemd du service : ReadWritePaths), puis ajouté dans Sécurité → Réglages → Stockage et choisi pour les caméras.

Audio et Bluetooth

sudo myhabitactl audio-install --check     # état seulement : paquets, groupes, services, adaptateur, cartes son
sudo myhabitactl audio-install --restart   # BlueZ, PipeWire, WirePlumber, pipewire-pulse, pactl, ffmpeg + service audio, puis redémarrage du moteur
journalctl -u myhabita-audio -n 80         # journal du service audio

• Adaptateur Bluetooth sur la machine virtuelle : brancher une clé Bluetooth USB sur l'hôte, puis la passer à la VM (Proxmox : VM → Matériel → Ajouter → Périphérique USB, de préférence par identifiant fabricant/produit pour qu'elle suive la clé d'un port à l'autre). Elle apparaît dans la VM en /sys/class/bluetooth/hci0 ; puis sudo systemctl restart bluetooth myhabita-audio. Une carte son USB se passe de la même façon.
• Le service myhabita-audio (PipeWire, WirePlumber, pipewire-pulse) tourne sous le compte myhabita, sans session ; le moteur le joint par /run/myhabita-audio/pulse/native. Le script désactive les instances PipeWire « par utilisateur » de Debian, ajoute myhabita aux groupes bluetooth et audio et écrit /etc/systemd/system/myhabita.service.d/audio.conf (groupes, PULSE_SERVER).
• Redémarrer My Habita après l'installation (--restart ou sudo myhabitactl restart) : c'est ce qui donne au moteur l'accès au Bluetooth.
• Une modification de myhabita-audio.service dans une nouvelle version s'applique par sudo myhabitactl update (si le service est installé) ou en relançant sudo myhabitactl audio-install.
• Récepteurs des enceintes My Habita (Spotify Connect, AirPlay) : audio-install installe aussi shairport-sync (paquet Debian ; son service par défaut est désactivé) et librespot (binaire seul, tiré du paquet raspotify épinglé avec son empreinte SHA-256, dans /opt/myhabita/vendor/librespot/). Le moteur lance un processus par enceinte et par récepteur, annoncé par Avahi (avahi-daemon doit tourner). Ports (réseau local) : Spotify Connect 48200 + n, AirPlay 7100 + n (TCP) et 6200 + 10·n à +9 (UDP), métadonnées AirPlay 48400 + n sur 127.0.0.1 (n : rang de l'enceinte My Habita). Un pare-feu sur le serveur doit les laisser passer, avec le mDNS (UDP 5353).
• Le script n'a jamais été lancé sur un serveur réel (pas d'adaptateur ici) : à essayer avec la clé branchée, puis à corriger d'après le journal si besoin.

Multimédia

• Bibliothèque : les dossiers ajoutés dans Multimédia → Réglages doivent être lisibles par le compte myhabita (les dossiers personnels /home sont invisibles). Partage d'un NAS : sudo myhabitactl nvr-storage nfs <serveur:/export> <nom> ou … smb //nas/partage <utilisateur> <nom> (monté sous /srv/myhabita/<nom>), puis ajoutez ce dossier. ffprobe et ffmpeg (installés par nvr-install) lisent les étiquettes, les pochettes et convertissent les vidéos ; sans eux, seuls les noms de fichiers servent.
• Index et caches : <données>/media.db (bibliothèque, caches Spotify, radios, podcasts) et <données>/multimedia/art/ (pochettes, affiches) ne sont pas sauvegardés : ils se reconstruisent (« Analyser maintenant », synchronisation Spotify). Favoris, playlists, reprises, zones, abonnements et comptes Spotify sont dans myhabita.db (sauvegardée). media-stream.key (clé des adresses de lecture) est sauvegardée ; la perdre n'invalide que les lectures en cours.
• Diffusion : les enceintes et téléviseurs lisent http://<serveur>/api/v1/multimedia/stream/… (port 80, nginx sans mise en tampon, plages transmises). Adresse du serveur détectée, à préciser dans Multimédia → Réglages → Général si les appareils sont sur un autre réseau (VLAN) ou si vous passez par un nom.
• Charge : 3 conversions vidéo au plus en même temps (ffmpeg, libx264 veryfast) ; une conversion 1080p occupe environ un cœur et demi.

Sauvegarder

• Automatique : chaque nuit vers 3 h 30 (myhabita-backup.timer), et avant chaque mise à jour ou restauration.
• Manuelle : sudo myhabitactl backup, ou Réglages → Sauvegardes → « Sauvegarder maintenant ».
• Emplacement : /var/backups/myhabita/myhabita-<date>-<motif>.tar.zst. Rotation : 14 quotidiennes, 8 avant mise à jour, 10 manuelles, 5 avant restauration.
• Contenu : bases SQLite (copie cohérente à chaud), /etc/myhabita (configuration, secrets, certificats), fichiers publics, données Zigbee2MQTT (clé réseau Zigbee, base des appareils, sauvegarde du coordinateur), comptes MQTT, stockage Matter, et un manifeste avec empreintes SHA-256.

⚠ Les archives contiennent des secrets : copiez-les régulièrement hors de ce serveur (NAS, disque externe), dans un endroit protégé. Une sauvegarde sur le même disque ne protège pas d'une panne de disque.

Restaurer

sudo myhabitactl backups
sudo myhabitactl restore /var/backups/myhabita/myhabita-20261018-033000-daily.tar.zst
# options : --no-history (garder l'historique actuel), --yes (sans confirmation)

La restauration vérifie l'archive (empreintes) et la compatibilité du schéma, sauvegarde d'abord l'état actuel (pre-restore), arrête les services, remet exactement l'état sauvegardé en place, corrige les droits, puis redémarre et vérifie.

Procédure testée sur cette installation le 18/10/2026 : modification des données, restauration, données retrouvées, sessions conservées ; puis retour à l'état vierge.

Migrer vers un autre serveur

1. Sur le nouveau serveur (Debian 13) : copiez /opt/myhabita (dépôt Git), puis lancez sudo /opt/myhabita/scripts/install.sh --with-zigbee --with-matter.
2. Copiez une sauvegarde récente, puis sudo myhabitactl restore <archive>.
3. Branchez le coordinateur Zigbee sur le nouveau serveur. Si son chemin /dev/serial/by-id/… est identique, rien d'autre à faire ; sinon, relancez l'assistant « Configurer le coordinateur ». Ne faites jamais tourner les deux serveurs avec le même coordinateur ou la même sauvegarde Zigbee en même temps.
4. Matter : le fabric est restauré avec le stockage du serveur Matter. Les appareils doivent être joignables depuis le nouveau réseau (IPv6 local).
5. Le certificat HTTPS est régénéré si les adresses ont changé (sudo myhabitactl tls --renew).

HTTPS sur le réseau local

My Habita génère sa propre autorité de certification (/etc/myhabita/tls) et un certificat pour <nom-du-serveur>, <nom-du-serveur>.local et ses adresses IP. Ce certificat est valable 825 jours et renouvelé automatiquement chaque nuit s'il expire dans moins de 30 jours.

Pour que vos appareils fassent confiance à https://<adresse-du-serveur>/ :

1. Téléchargez http://<adresse-du-serveur>/ca.crt.
2. Installez ce certificat d'autorité :
   • iOS : Réglages → Profil téléchargé, puis Réglages → Général → Informations → Réglages des certificats → activer.
   • Android : Paramètres → Sécurité → Installer un certificat → Certificat CA.
   • Windows : double-clic → « Autorités de certification racines de confiance ».
   • macOS : Trousseau → Système → « Toujours approuver ».
   • Firefox : Paramètres → Certificats → Importer.

Le HTTPS est recommandé pour les écrans muraux (maintien de l'écran allumé) et la géolocalisation.

Application Android

sudo scripts/install-android-sdk.sh   # une seule fois (JDK 21, SDK Android)
sudo myhabitactl android              # construit, signe et publie l'application sur ce serveur

Les téléphones téléchargent l'application depuis Réglages → Téléphones et se mettent à jour depuis le serveur. La clé de signature (/etc/myhabita/android/) est incluse dans les sauvegardes : en cas de migration, restaurez-la avant de republier, sinon les téléphones devront réinstaller l'application. myhabitactl doctor affiche la version publiée et les empreintes des certificats (à comparer lors de la première connexion en HTTPS). Voir application-mobile.md.

Dépannage

Désinstaller

Sur une installation faite avec le script d'installation :

sudo myhabitactl uninstall                                    # questions : garder ou effacer les données, retirer les paquets
sudo myhabitactl uninstall --keep-data                        # garde /etc/myhabita et /var/lib/myhabita (réinstallation possible)
sudo myhabitactl uninstall --delete-data --remove-packages --yes

Sont retirés : les services, le programme (/opt/myhabita), les sites nginx, la configuration de Mosquitto, la règle polkit, l'annonce Avahi, la commande myhabitactl et, si les données sont effacées, les comptes de service. Une dernière sauvegarde est toujours gardée dans /var/backups/myhabita (à supprimer à la main). Avec --remove-packages, seuls les paquets Debian ajoutés par l'installation et dont plus rien ne dépend sont retirés : un logiciel installé depuis qui en a besoin les garde. --purge efface aussi les sauvegardes. Une installation de développement (dépôt Git) n'est jamais désinstallée par cette commande.

Politique de versions et compatibilité