Home Assistant avec Docker

Home Assistant est une plateforme open-source de domotique qui permet de contrôler et automatiser tous vos appareils connectés. Ce guide vous montre comment l’installer avec Docker et ajouter HACS, le store d’applications communautaire.

Sommaire

• Pourquoi Home Assistant ?
• Prérequis
• Installation avec Docker Compose
• Configuration initiale
• Installation de HACS
• Dépannage

Pourquoi Home Assistant ?

En une phrase: Home Assistant centralise tous vos appareils connectés (lumières, capteurs, caméras…) dans une seule interface, avec contrôle total sur vos données.

Pourquoi c’est intéressant:

• Privacy-first: Vos données restent chez vous, pas dans le cloud
• Compatible avec tout: Plus de 2000 intégrations (Philips Hue, Sonoff, Xiaomi, Google Home…)
• Automatisations puissantes: “Si la température < 18°C et que je rentre à la maison, allume le chauffage”
• Interface moderne: Application mobile + interface web personnalisable

Pourquoi Docker ?

• Installation propre et isolée
• Facile à sauvegarder et migrer
• Pas de conflit avec d’autres services
• Mise à jour simple (juste changer la version de l’image)

Prérequis

Avant de commencer, assurez-vous d’avoir:

1. Docker et Docker Compose installés

   docker --version
   docker compose version

2. Un système Linux (recommandé: Debian, Ubuntu, Raspberry Pi OS)

   • Home Assistant fonctionne aussi sur Windows/macOS mais avec moins de fonctionnalités

3. Accès root ou sudo pour les permissions réseau

4. Port 8123 disponible (interface web de Home Assistant)

Installation avec Docker Compose

Étape 1: Créer la structure du projet

# Créer un dossier pour Home Assistant
mkdir -p ~/homeassistant
cd ~/homeassistant

# Créer le dossier de configuration (sera monté dans le container)
mkdir config

Pourquoi ce dossier ? Toute la configuration de Home Assistant (intégrations, automatisations, historique) sera stockée dans ./config. C’est ce dossier que vous sauvegarderez pour préserver votre setup.

Étape 2: Créer le docker-compose.yml

Créez un fichier docker-compose.yml avec ce contenu:

version: '3.9'
services:
  homeassistant:
    container_name: homeassistant
    image: ghcr.io/home-assistant/home-assistant:stable
    volumes:
      - ./config:/config
      - /etc/localtime:/etc/localtime:ro
      - /run/dbus:/run/dbus:ro
    environment:
      - TZ=Europe/Paris
    restart: unless-stopped
    privileged: true
    network_mode: host

Décortiquons ce fichier ligne par ligne:

Paramètre	Explication	Pourquoi c’est important
image: ...stable	Version stable officielle	Évite les bugs des versions beta
./config:/config	Monte le dossier local dans le container	Vos données survivent aux redémarrages
/etc/localtime:ro	Partage l’heure du système	Automatisations basées sur l’heure correcte
/run/dbus:ro	Accès au bus système Linux	Nécessaire pour Bluetooth et certaines intégrations
TZ=Europe/Paris	Fuseau horaire	Logs et automatisations avec la bonne heure
privileged: true	Donne plus de droits au container	Accès aux périphériques USB (Zigbee, Z-Wave…)
network_mode: host	Partage le réseau de l’hôte	Découverte automatique des appareils (Chromecast, Philips Hue…)

Sécurité

privileged: true et network_mode: host donnent beaucoup de permissions. C’est normal pour Home Assistant car il doit accéder au matériel, mais n’utilisez pas ces options pour d’autres services par défaut.

Étape 3: Lancer Home Assistant

# Démarrer le container
docker compose up -d

# Vérifier que ça tourne
docker compose logs -f homeassistant

Ce qui se passe:

1. Docker télécharge l’image Home Assistant (~1-2 GB)
2. Le container démarre et initialise la configuration
3. Au bout de 1-2 minutes, l’interface web est accessible

Premier démarrage: Attendez voir ce message dans les logs:

INFO (MainThread) [homeassistant.core] Starting Home Assistant

Étape 4: Accéder à l’interface web

Ouvrez votre navigateur:

http://VOTRE_IP:8123

Exemples:

• Sur la même machine: http://localhost:8123
• Depuis un autre PC du réseau: http://192.168.1.50:8123

Configuration initiale

Premier accès

Lors de la première connexion, Home Assistant vous guide:

1. Créer votre compte admin

   • Nom, identifiant, mot de passe
   • ⚠️ Gardez ce mot de passe en sécurité !

2. Configurer votre maison

   • Nom de votre maison
   • Localisation (pour la météo et le lever/coucher du soleil)
   • Unités (métriques en Europe)

3. Découverte automatique

   • Home Assistant scanne votre réseau
   • Il détecte automatiquement vos appareils compatibles (TV, enceintes, lumières…)

Astuce

Laissez Home Assistant tourner 10 minutes avant de configurer. La découverte automatique continue en arrière-plan.

Fichiers importants créés

Après l’initialisation, regardez votre dossier config:

ls -la config/

Vous verrez:

• configuration.yaml: Fichier principal de config
• automations.yaml: Vos automatisations (éditable depuis l’UI)
• .storage/: Base de données interne (ne pas toucher)
• home-assistant.log: Logs pour débuguer

Installation de HACS

C’est quoi HACS ? HACS (Home Assistant Community Store) est un “app store” non-officiel qui donne accès à des milliers d’intégrations et de thèmes créés par la communauté.

Exemples de ce que ça apporte:

• Intégrations custom (Livebox, Freebox, Linky…)
• Thèmes visuels modernes
• Cartes d’interface avancées
• Automatisations prêtes à l’emploi

Étape 1: Accéder au container

# Entrer dans le container Home Assistant
docker exec -it homeassistant bash

Vous êtes maintenant dans le container. Tout ce que vous tapez s’exécute à l’intérieur.

Étape 2: Télécharger HACS

# Se placer dans le dossier config
cd /config

# Télécharger le script d'installation
wget -O - https://get.hacs.xyz | bash -

Ce que fait ce script:

1. Télécharge les fichiers HACS
2. Les place dans /config/custom_components/hacs/
3. Configure les permissions

Sécurité

Ce script vient du site officiel de HACS. Vous pouvez vérifier le code sur github.com/hacs.

Étape 3: Redémarrer Home Assistant

# Sortir du container
exit

# Redémarrer depuis l'hôte
docker compose restart homeassistant

# Attendre que ça redémarre (30-60 secondes)
docker compose logs -f homeassistant

Étape 4: Configurer HACS dans l’interface

1. Aller dans Configuration → Intégrations

   • URL: http://VOTRE_IP:8123/config/integrations

2. Ajouter une intégration

   • Cliquer sur + Ajouter une intégration
   • Chercher “HACS”
   • Cliquer dessus

3. Lier votre compte GitHub

   • HACS a besoin d’un compte GitHub (c’est gratuit)
   • Cliquer sur le lien d’autorisation
   • Copier le code fourni
   • Le coller dans Home Assistant

4. Finaliser

   • Cocher les cases des conditions d’utilisation
   • HACS est maintenant installé !

Utiliser HACS

Une fois installé, un nouveau menu “HACS” apparaît dans la barre latérale.

Pour installer quelque chose:

1. HACS → Intégrations (ou Frontend, ou Thèmes)
2. ⊕ Explorer et télécharger des dépôts
3. Chercher ce que vous voulez
4. Cliquer → Télécharger
5. Redémarrer Home Assistant

Exemples populaires:

• Browser Mod: Contrôle des navigateurs (notifications, popups…)
• Mushroom Cards: Cartes d’interface ultra modernes
• Xiaomi Miot Auto: Intégration complète des appareils Xiaomi

Dépannage

Le port 8123 ne répond pas

Vérifier que le container tourne:

docker ps | grep homeassistant

Si absent:

docker compose logs homeassistant

Problème fréquent: Le port est déjà utilisé

# Vérifier qui utilise le port 8123
sudo lsof -i :8123

Erreur “Unhealthy” ou crash au démarrage

Vérifier les permissions du dossier config:

ls -la ~/homeassistant/

Le dossier config doit être accessible. Si besoin:

sudo chown -R $(whoami):$(whoami) ~/homeassistant/config

Les appareils ne sont pas découverts

Avec network_mode: host:

• C’est normal si votre réseau a un firewall strict
• Vérifiez que Home Assistant et vos appareils sont sur le même sous-réseau

Alternative sans network_mode: host: Si vous avez des problèmes, vous pouvez mapper les ports manuellement:

services:
  homeassistant:
    # ... autres configs
    network_mode: bridge # au lieu de host
    ports:
      - '8123:8123' # Interface web

Limitation

Sans network_mode: host, la découverte automatique (mDNS) ne fonctionne pas. Vous devrez ajouter vos appareils manuellement.

HACS n’apparaît pas après installation

1. Vérifier que les fichiers sont là:

   ls ~/homeassistant/config/custom_components/hacs/

2. Vider le cache du navigateur:

   • Ctrl + F5 sur l’interface Home Assistant

3. Vérifier les logs:

   docker compose logs homeassistant | grep -i hacs

Aller plus loin

Sauvegarder votre configuration

Méthode simple:

# Arrêter Home Assistant
docker compose down

# Sauvegarder le dossier config
tar -czf ha-backup-$(date +%Y%m%d).tar.gz config/

# Redémarrer
docker compose up -d

Gardez ce fichier .tar.gz précieusement. En cas de problème, vous pourrez tout restaurer.

Mettre à jour Home Assistant

cd ~/homeassistant

# Télécharger la nouvelle version
docker compose pull

# Redémarrer avec la nouvelle image
docker compose up -d

Bonne pratique

Faites une sauvegarde avant chaque mise à jour majeure.

Accès depuis l’extérieur

Option 1: Nabu Casa (payant, 6.50€/mois)

• Service officiel de Home Assistant
• Accès sécurisé sans config
• Supporte le projet

Option 2: Reverse proxy (gratuit, plus technique)

• Utilisez Nginx ou Caddy
• Configurez HTTPS avec Let’s Encrypt
• Voir le guide Reverse Proxy

Ressources utiles

• Documentation officielle: home-assistant.io
• Forum communautaire: community.home-assistant.io
• HACS: hacs.xyz
• Awesome HA: github.com/frenck/awesome-home-assistant

---

C’est clair ou tu veux que je détaille une section spécifique (automatisations, intégrations particulières, sécurité) ?