Installer Home Assistant sur un VPS Linux avec Docker

Home Assistant sur un VPS Linux avec Docker

Home Assistant est une plateforme domotique open source qui centralise le pilotage de vos objets connectés : éclairage, thermostat, caméras, capteurs, volets roulants et plus de 2 000 intégrations. L'installer sur un VPS Linux plutôt que sur un Raspberry Pi résout trois problèmes récurrents : la carte SD qui lâche après quelques mois d'écritures intensives, le manque de puissance lorsque le nombre d'intégrations et d'automatisations augmente, et la nécessité de configurer un accès distant via port forwarding sur la box internet.

Sur un VPS, Home Assistant est accessible depuis n'importe quel réseau, tourne sur du stockage SSD fiable, et reste disponible 24 h/24 sans dépendre de votre connexion domestique. Ce guide installe Home Assistant Container (version 2026.10) via Docker Compose sur Ubuntu 24.04 LTS ou Debian 12, avec un reverse proxy Nginx HTTPS et un nom de domaine.

Si Docker n'est pas encore installé sur votre serveur, commencez par notre guide installer Docker sur un VPS. Pour les bases de Docker Compose (volumes, réseaux, syntaxe YAML) : Docker Compose sur VPS Linux.

Prérequis

• Un VPS Linux avec au moins 2 Go de RAM et 20 Go de stockage SSD ;
• Docker Engine 23.0 ou supérieur et Docker Compose v2 installés (guide d'installation Docker) ;
• Un nom de domaine (ou sous-domaine) pointant vers l'adresse IP publique du VPS (enregistrement DNS de type A) ;
• Un accès SSH avec un utilisateur non root membre du groupe docker (sécuriser SSH sur VPS Linux) ;
• Les ports 80 et 443 ouverts dans le pare-feu du VPS (ouvrir les ports avec UFW).

Préparer l'arborescence

Créez un répertoire dédié sur le VPS pour regrouper la configuration de Home Assistant et le fichier Docker Compose :

mkdir -p ~/home-assistant
cd ~/home-assistant

Le répertoire config contiendra les fichiers de configuration de Home Assistant, y compris configuration.yaml, les automatisations et les intégrations :

mkdir -p ~/home-assistant/config

Le fichier docker-compose.yml

Ce fichier décrit le service Home Assistant Container. L'image officielle ghcr.io/home-assistant/home-assistant:stable est maintenue par le projet Home Assistant et mise à jour à chaque nouvelle version.

cat > ~/home-assistant/docker-compose.yml <<'EOF'
services:
  homeassistant:
    container_name: homeassistant
    image: ghcr.io/home-assistant/home-assistant:stable
    volumes:
      - ./config:/config
      - /etc/localtime:/etc/localtime:ro
    restart: unless-stopped
    stop_grace_period: 60s
    ports:
      - "127.0.0.1:8123:8123"
EOF

Points importants de cette configuration Docker Compose :

• ./config:/config monte le répertoire local config dans le conteneur. Tous les fichiers de configuration, automatisations et bases de données Home Assistant y sont persistés entre les redémarrages.
• /etc/localtime:/etc/localtime:ro synchronise le fuseau horaire du conteneur avec celui du VPS, pour que les automatisations horaires se déclenchent à la bonne heure.
• 127.0.0.1:8123:8123 expose le port uniquement en local. Le reverse proxy Nginx se chargera de l'accès HTTPS depuis l'extérieur. Ne publiez jamais le port 8123 sur 0.0.0.0 sans chiffrement TLS.
• stop_grace_period: 60s laisse à Home Assistant le temps de sauvegarder sa base de données avant l'arrêt du conteneur.

La documentation officielle recommande network_mode: host pour la découverte automatique des appareils sur le réseau local. Sur un VPS distant sans réseau domotique local, le mode bridge avec mapping de port est suffisant et plus sécurisé.

Premier démarrage

Depuis le répertoire ~/home-assistant, démarrez le conteneur :

cd ~/home-assistant
docker compose up -d

Docker télécharge l'image Home Assistant et crée le conteneur. Vérifiez qu'il tourne :

docker compose ps

Le conteneur homeassistant doit afficher le statut Up. Si le conteneur redémarre en boucle, consultez les logs :

docker compose logs homeassistant

Home Assistant génère automatiquement le fichier configuration.yaml dans le répertoire config au premier lancement. L'interface web est accessible localement sur http://127.0.0.1:8123.

Configurer Nginx en reverse proxy HTTPS

Le reverse proxy Nginx reçoit les connexions HTTPS des utilisateurs depuis Internet et les transfère au conteneur Home Assistant sur le port local 8123. Pour un guide complet sur Nginx en reverse proxy, consultez notre guide Nginx reverse proxy sur VPS Linux.

Installez Nginx et Certbot :

sudo apt update
sudo apt install -y nginx certbot python3-certbot-nginx

Créez le fichier de configuration du virtual host :

sudo nano /etc/nginx/sites-available/homeassistant.conf

Contenu du fichier de configuration Nginx pour Home Assistant :

map $http_upgrade $connection_upgrade {
    default upgrade;
    ""      close;
}

server {
    listen 80;
    server_name domotique.exemple.fr;

    location / {
        proxy_pass http://127.0.0.1:8123;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
    }
}

Le bloc map et les en-têtes Upgrade/Connection sont indispensables. Home Assistant utilise des WebSockets pour la mise à jour en temps réel de l'interface. Sans cette configuration, le tableau de bord affiche des erreurs de connexion.

Activez le site et obtenez un certificat HTTPS Let's Encrypt :

sudo ln -s /etc/nginx/sites-available/homeassistant.conf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
sudo certbot --nginx -d domotique.exemple.fr

Certbot ajoute automatiquement le bloc listen 443 ssl, les chemins vers le certificat et la redirection HTTP vers HTTPS. Le renouvellement est automatique (en savoir plus sur Certbot et Let's Encrypt).

Configurer les proxies de confiance

Home Assistant doit savoir que les requêtes passent par un reverse proxy pour enregistrer correctement les adresses IP des utilisateurs et autoriser la connexion. Sans cette configuration, Home Assistant renvoie une erreur 400 Bad Request.

Ajoutez les lignes suivantes dans le fichier config/configuration.yaml :

http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 127.0.0.1
  ip_ban_enabled: true
  login_attempts_threshold: 5

127.0.0.1 correspond à Nginx installé sur le même VPS que le conteneur Home Assistant. ip_ban_enabled bloque automatiquement une adresse IP après 5 tentatives de connexion échouées, ce qui protège l'interface contre les attaques par force brute.

Redémarrez le conteneur pour appliquer la configuration :

docker compose restart homeassistant

Ouvrez https://domotique.exemple.fr dans un navigateur. L'assistant d'intégration de Home Assistant s'affiche : créez votre compte administrateur, donnez un nom à votre maison et configurez votre fuseau horaire.

Alternative : Caddy comme reverse proxy

Caddy est une alternative à Nginx qui obtient et renouvelle automatiquement les certificats HTTPS sans intervention manuelle. La configuration complète tient en trois lignes dans un fichier Caddyfile :

domotique.exemple.fr {
    reverse_proxy 127.0.0.1:8123
}

Caddy gère automatiquement les WebSockets, le HTTPS via Let's Encrypt et la redirection HTTP vers HTTPS. C'est la solution la plus rapide à mettre en place si vous n'avez pas d'autre service Nginx déjà installé sur le VPS.

Mettre à jour Home Assistant

Pour mettre à jour Home Assistant vers la dernière version stable, récupérez la nouvelle image et relancez le conteneur :

cd ~/home-assistant
docker compose pull
docker compose up -d

Home Assistant applique automatiquement les migrations de base de données au démarrage. Avant une mise à jour majeure, sauvegardez le répertoire de configuration :

tar czf home-assistant-config-$(date +%F).tar.gz -C ~/home-assistant/config .

Pour automatiser les sauvegardes de votre VPS vers un serveur distant : sauvegarder un VPS avec rsync.

VPS Linux vs Raspberry Pi pour Home Assistant

Le VPS est le meilleur choix pour une installation Home Assistant qui centralise des automatisations cloud (API, notifications, intégrations en ligne), des tableaux de bord accessibles de partout et des automatisations fiables sans interruption. Le Raspberry Pi reste pertinent uniquement si vous avez besoin d'un accès direct aux dongles USB Zigbee ou Z-Wave branchés physiquement sur la machine.

Surveiller le conteneur Home Assistant

Vérifiez régulièrement que le conteneur tourne et que les ressources du VPS ne sont pas saturées. Quelques commandes utiles :

docker compose ps
docker stats homeassistant --no-stream
docker compose logs --tail=50 homeassistant

Pour une supervision complète de votre VPS avec des alertes en cas de problème, consultez notre guide alertes et monitoring sur VPS Linux. Pour gérer vos conteneurs Docker via une interface web, Portainer, Dockge ou Cosmos simplifient le suivi et les mises à jour.

Conclusion

Votre instance Home Assistant fonctionne sur un VPS Linux, accessible en HTTPS via un reverse proxy Nginx (ou Caddy), avec un certificat Let's Encrypt renouvelé automatiquement. Le conteneur Docker se met à jour en deux commandes (docker compose pull et docker compose up -d) et la configuration persiste dans un répertoire local que vous pouvez sauvegarder et versionner.

Pour renforcer la sécurité de votre VPS au-delà de Home Assistant, consultez nos guides sécuriser SSH sur VPS Linux et Fail2ban pour protéger SSH.