/tutoriels/ assistants-ia / home-assistant-sur-rpi4-(ha-os)-ou-en-docker.md

Home Assistant sur RPi4 (HA OS) ou en Docker

Installer Home Assistant OS sur RPi4 ou Home Assistant Docker sur N54L/VPS pour l'automatisation domotique IA.

CAT · ASSISTANTS IA LECTURE · 7 min PUBLIÉ · 2026-04-12

Temps estimé : 60 min (RPi4) / 45 min (Docker sur N54L ou VPS)

Résultat final : Home Assistant accessible via navigateur sur l’IP locale (ou Tailscale), avec API longue durée activée pour l’intégration OpenClaw.

Prérequis :

TUTO-01c (HomeServer local) ou VPS avec TUTO-02 complété
Tailscale installé sur le device hébergeant HA

Objectif

Installer Home Assistant et l’exposer uniquement via Tailscale — jamais sur Internet public. Deux méthodes selon le hardware :

Méthode A — RPi4 : Home Assistant OS (image dédiée, la plus simple)
Méthode B — N54L ou VPS Ubuntu : Home Assistant Container via Docker

Recommandation : Méthode A pour RPi4 (HA OS = updates simplifiées, add-ons natifs). Méthode B pour N54L ou VPS (Ubuntu déjà installé, pas besoin de reflasher).

Méthode A — RPi4 : Home Assistant OS

A1 — Flasher l’image HA OS

Sur ton poste local :

Télécharge Raspberry Pi Imager : https://www.raspberrypi.com/software/
Ouvre Imager
Choose OS → Other specific-purpose OS → Home Assistants and home automation → Home Assistant
Sélectionne Raspberry Pi 4 (64-bit)
Choose Storage → ta carte microSD (32 GB minimum)
Clique Write (efface tout le contenu de la SD)

⚠️ Sécurité

HA OS crée un compte admin sans mot de passe lors du premier démarrage. L’étape A3 (définir le compte admin) doit être faite avant toute connexion réseau autre que locale.

A2 — Premier démarrage

Insère la microSD dans le RPi4
Connecte Ethernet (WiFi non recommandé pour serveur domotique)
Branche l’alimentation

Le premier démarrage prend 5-10 minutes (téléchargement des composants de base).

# Depuis ton réseau local, vérifier que HA répond
# Remplacer par l'IP locale du RPi4 (voir ton routeur DHCP)
curl -s http://IP_LOCALE_RPI4:8123 | head -5
# Doit afficher du HTML avec "Home Assistant"

A3 — Configuration initiale via navigateur

Ouvre http://IP_LOCALE_RPI4:8123 dans un navigateur
Clique Create my smart home
Crée le compte admin :
- Nom, nom d’utilisateur (ex: admin)
- Mot de passe fort (généré, noté dans un gestionnaire de mots de passe)
Sélectionne ta localisation (pour météo, heure locale)
Passe la détection automatique des équipements (configurable plus tard)

⚠️ Sécurité

le mot de passe admin HA = accès complet à toute ta domotique. Utiliser un gestionnaire de mots de passe (Bitwarden, 1Password). Ne jamais réutiliser un mot de passe existant.

Checklist A :

HA OS flashé sur microSD
HA accessible sur http://IP_LOCALE:8123
Compte admin créé avec mot de passe fort
Localisation configurée

Méthode B — Docker sur N54L ou VPS Ubuntu

B1 — Installer Docker

# Sur le N54L ou VPS (connecté en SSH)
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

Déconnecte-toi et reconnecte-toi pour que le groupe prenne effet :

# Vérifier Docker
docker --version
# Doit afficher : Docker version 25.x.x ou supérieur

⚠️ Sécurité

usermod -aG docker $USER donne des droits équivalents root via Docker. Ne jamais ajouter un compte de service ou un user non-fiable dans ce groupe.

B2 — Créer le répertoire de données HA

mkdir -p ~/homeassistant/config

B3 — Démarrer Home Assistant Container

docker run -d \
  --name homeassistant \
  --privileged \
  --restart unless-stopped \
  -e TZ=Europe/Paris \
  -v ~/homeassistant/config:/config \
  --network host \
  ghcr.io/home-assistant/home-assistant:stable

# Vérifier que le container démarre
docker logs homeassistant --follow
# Attendre les lignes : "Home Assistant initialized" ou "Starting Home Assistant"
# Ctrl+C pour sortir du suivi

# Tester l'accès local
curl -s http://localhost:8123 | head -5
# Doit afficher du HTML avec "Home Assistant"

⚠️ Sécurité

--network host expose HA sur toutes les interfaces réseau du host. C’est nécessaire pour la découverte des équipements locaux (mDNS). Compenser en n’ouvrant jamais le port 8123 dans UFW vers Internet.

B4 — Configurer UFW pour HA (Méthode B uniquement)

# Autoriser HA uniquement depuis le réseau local et Tailscale
# Réseau local (adapter selon ton sous-réseau)
sudo ufw allow from 192.168.1.0/24 to any port 8123
# Tailscale
sudo ufw allow from 100.64.0.0/10 to any port 8123

sudo ufw status | grep 8123
# Doit afficher les 2 règles d'autorisation

⚠️ Sécurité

ne jamais faire sudo ufw allow 8123 sans restriction de source. Cela ouvrirait l’interface HA sur Internet public.

Checklist B :

Docker installé, docker --version OK
Container homeassistant en état “Up”
HA accessible sur http://localhost:8123 (ou IP locale)
UFW : port 8123 autorisé uniquement depuis réseau local + Tailscale

B5 — Configuration initiale (identique Méthode A)

Suivre les étapes A3 ci-dessus (navigateur sur http://IP_LOCALE:8123).

Étape commune : Installer Tailscale sur le host HA [si pas déjà fait]

Si HA tourne sur le RPi4 (Méthode A), Tailscale s’installe via l’add-on HA :

HA → Paramètres → Add-ons → Boutique des add-ons
Chercher Tailscale
Installer → Démarrer
Ouvrir l’interface → se connecter au compte Tailscale

Si HA tourne sur Ubuntu (Méthode B), Tailscale est déjà installé (TUTO-01c ou TUTO-02).

# Vérifier l'IP Tailscale du host HA
tailscale ip -4
# Exemple : 100.y.y.y (différente de l'IP du VPS)

Étape finale : Activer l’API longue durée (Long-Lived Access Token)

OpenClaw a besoin d’un token pour accéder à l’API HA. Ce token sera configuré dans TUTO-05.

Dans HA → clique sur ton avatar (en bas à gauche)
Onglet Sécurité → section Tokens d’accès longue durée
Clique Créer un token
Nom : openclaw-ha-agent
Copier le token — il ne sera affiché qu’une seule fois

Sauvegarder le token dans le fichier infra (NON versionné) :

# En local sur ton poste
nano ~/.openclaw-infra.env

Ajouter :

# Home Assistant
HA_IP_TAILSCALE=100.y.y.y
HA_PORT=8123
HA_TOKEN=REDACTED_HA_TOKEN...

chmod 600 ~/.openclaw-infra.env

⚠️ Sécurité

le Long-Lived Token HA donne un accès complet à toute ta domotique. Traiter comme un mot de passe root. Ne jamais le committer, ne jamais l’afficher dans des logs ou des messages Telegram.

Checklist finale :

HA accessible via http://IP_TAILSCALE_HA:8123 depuis le VPS
Compte admin HA créé avec mot de passe fort
Token openclaw-ha-agent créé et sauvegardé dans ~/.openclaw-infra.env
~/.openclaw-infra.env chmod 600

Dépannage

HA non accessible sur http://IP:8123

Méthode A (HA OS) :

# Vérifier que le RPi4 a une IP (depuis ton routeur ou Tailscale admin)
# Attendre 10 minutes après le premier démarrage (download initial)
ping IP_LOCALE_RPI4

Méthode B (Docker) :

docker ps | grep homeassistant
# Si absent : docker start homeassistant
docker logs homeassistant --tail 50

HA accessible en local mais pas via Tailscale

# Sur le VPS, tester la connectivité
curl -s http://$HA_IP_TAILSCALE:8123/api/ \
  -H "Authorization: Bearer $HA_TOKEN"
# Attendu : {"message": "API running."}

Si timeout : vérifier UFW sur le host HA (Méthode B) ou que l’add-on Tailscale est actif (Méthode A).

Token API refusé (401 Unauthorized)

Le token a expiré ou a été révoqué → recréer via HA → Sécurité → Tokens
L’en-tête Authorization: Bearer est manquant ou mal formaté

RPi4 : HA OS “stuck” au démarrage

Attendre 15 min — le premier boot télécharge beaucoup
Vérifier l’alimentation (5V 3A officielle minimum)
Vérifier la microSD (tests avec f3 ou h2testw)

Références

Home Assistant OS pour RPi4 : https://www.home-assistant.io/installation/raspberrypi
Home Assistant Container (Docker) : https://www.home-assistant.io/installation/linux#docker-compose
HA API REST : https://developers.home-assistant.io/docs/api/rest/
Tailscale add-on HA : https://github.com/hassio-addons/addon-tailscale

Tuto suivant : TUTO-05

VR · 2026-04-12 · vraffin.dev FIN DU DOCUMENT