Come installare Home Assistant Container con Docker Compose

Prerequisiti & Hardware Necessario

• Hardware: host Linux 64-bit con almeno 2 GiB di RAM disponibili e storage affidabile. Puoi usare un Raspberry Pi 5 4GB con alimentatore ufficiale oppure una VM Debian su Proxmox.
• Software: Linux aggiornato, Docker Engine 23.0.0 o superiore e Docker Compose v2 come plugin. Home Assistant Container è Home Assistant Core dentro un container; non è Home Assistant OS e non include Supervisor né app/add-on.
• Accesso: utente con sudo, IP locale stabile e directory persistente per /config. Useremo /opt/homeassistant.
• Dispositivi: la rete host facilita discovery e mDNS. Zigbee, Z-Wave e Bluetooth richiedono mapping device e permessi specifici.

Procedura passo-passo

1. Verifica Docker e Compose.

   docker version
   docker compose version
   sudo systemctl is-active docker

   Il runtime deve essere Docker Engine, non Docker Desktop su Linux server.
2. Crea la directory persistente.

   sudo install -d -m 0755 /opt/homeassistant
   sudo chown "$USER":"$USER" /opt/homeassistant
   cd /opt/homeassistant

   Il percorso host è il dato persistente; quello interno deve rimanere /config.
3. Crea /opt/homeassistant/compose.yaml.

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

   /run/dbus serve per Bluetooth e altre integrazioni D-Bus; rimuovilo se non necessario. privileged: true amplia i privilegi e va mantenuto solo se richiesto.

4. Valida e avvia.

   cd /opt/homeassistant
   docker compose config
   docker compose pull
   docker compose up -d

5. Controlla stato e log.

   docker compose ps
   docker compose logs --tail=100 homeassistant

   Attendi l’inizializzazione e non avviare una seconda istanza sulla porta 8123.
6. Completa l’onboarding. Apri http://IP_DEL_SERVER:8123, crea l’utente amministratore e configura posizione, unità e fuso orario. Il contenuto di /config deve entrare nei backup.
7. Mappa una periferica USB solo se necessaria. Identifica il device stabile con ls -l /dev/serial/by-id/, poi aggiungi sotto homeassistant: il mapping reale, ad esempio

       devices:
         - /dev/serial/by-id/usb-ADAPTER_REALE:/dev/ttyUSB0

   Non copiare /dev/ttyUSB0 senza verifica.
8. Controlla la configurazione.

   docker exec homeassistant python -m homeassistant --script check_config --config /config
   docker compose restart homeassistant

   Gli errori YAML di Home Assistant non sono errori Docker.
9. Aggiorna in modo controllato. Dopo un backup di /opt/homeassistant:

   cd /opt/homeassistant
   docker compose pull homeassistant
   docker compose up -d
   docker compose logs --tail=100 homeassistant

   Il tag stable segue l’ultima release stabile; per riproducibilità usa un tag versione specifico.

Verifica del funzionamento

La configurazione è corretta quando docker compose ps mostra il servizio attivo, la porta 8123 risponde, /opt/homeassistant contiene la configurazione e i log non mostrano errori. Riavvia il server e verifica l’avvio automatico con restart: unless-stopped. Questa installazione non include app/add-on.

Problemi comuni

FAQ essenziali

Container è equivalente a Home Assistant OS?

No. Container richiede gestione separata di sistema operativo, Docker, backup e servizi. Home Assistant OS integra Supervisor e app.

Posso eseguire due istanze sullo stesso host?

Sì solo in ambienti separati e con porte diverse; non avviare due istanze sulla stessa porta 8123.