Installare Home Assistant Core su Ubuntu 24.04 -- TrgtKLS • Tech, Sicurezza e Strumenti & guide per Webmaster

1 1 visite 24/04/2026 Pubblicato il: 24/04/2026 07:59 Tempo di lettura: 11 min

Su Ubuntu 24.04, Home Assistant Core si installa in modo pulito senza Docker: utente dedicato, virtualenv Python, servizio systemd e, se serve, reverse proxy davanti. È la strada giusta quando vuoi controllo fine sull’ambiente, meno stratificazione e una diagnostica più lineare rispetto a un container tutto-in-uno.

La scelta va fatta con un criterio semplice: se ti serve solo Home Assistant Core, cioè il motore applicativo senza supervisore, questa guida è adatta. Se invece vuoi add-on, backup gestiti e aggiornamenti orchestrati, stai cercando Home Assistant OS o Home Assistant Supervised, che seguono un percorso diverso e hanno vincoli più stretti sul sistema host.

Prerequisiti reali su Ubuntu 24.04

Ubuntu 24.04 porta Python 3.12 come base di sistema, ma non bisogna installare Home Assistant dentro il Python globale. Il punto chiave è separare i pacchetti del sistema dall’ambiente dell’applicazione, così eviti conflitti con librerie di distro e tieni il rollback semplice.

Servono privilegi sudo, connettività verso Internet per scaricare dipendenze e almeno 2 GB di RAM liberi per un uso minimo; nella pratica, 4 GB o più sono una scelta molto più serena se il nodo ospita anche altro. Se il server è dietro firewall o NAT, verifica già ora che la porta TCP 8123 sia raggiungibile solo dal segmento previsto, oppure che il reverse proxy sia pronto prima di esporre il servizio.

Account dedicato e struttura directory

La prima mossa è creare un utente dedicato e una directory applicativa sotto /srv. Questo limita i permessi, rende chiaro dove vivono i file e semplifica eventuali backup o restore.

Comandi consigliati:

sudo adduser --system --group --home /srv/homeassistant homeassistant
sudo mkdir -p /srv/homeassistant
sudo chown -R homeassistant:homeassistant /srv/homeassistant

Se l’utente viene creato con home directory già esistente, controlla che ownership e permessi siano coerenti. Il punto non è estetico: Home Assistant scrive database, cache, file di configurazione e log nella propria directory; se i permessi sono sporchi, il problema si manifesta come avvio fallito o configurazione non persistente.

Dipendenze di sistema e virtualenv Python

Installa i pacchetti necessari per compilazione, gestione del virtual environment e alcune librerie di sistema utili a molte integrazioni.

sudo apt update
sudo apt install -y python3 python3-venv python3-dev python3-pip \
  build-essential libssl-dev libffi-dev libjpeg-dev zlib1g-dev \
  libopenjp2-7 libtiff6 tzdata ca-certificates

La lista non è casuale: le dipendenze di compilazione servono quando qualche pacchetto Python richiede estensioni native, mentre le librerie grafiche e di compressione vengono spesso tirate in ballo da componenti accessorie. Se manca qualcosa, il problema emerge durante pip install e non al primo avvio, quindi meglio preparare il terreno subito.

Crea il virtualenv e aggiorna gli strumenti di base:

sudo -u homeassistant -H bash -c '
cd /srv/homeassistant
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip setuptools wheel
'

Qui il confine importante è quello tra sistema e applicazione: tutto ciò che Home Assistant installa deve restare nel virtualenv. Se in futuro serve ricreare l’ambiente, basta eliminare .venv e rifarlo, senza toccare il resto del server.

Installazione di Home Assistant Core

Dentro il virtualenv, installa il pacchetto principale. È un’operazione lunga ma lineare; su macchine più lente può richiedere diversi minuti perché viene risolto un albero di dipendenze ampio.

sudo -u homeassistant -H bash -c '
cd /srv/homeassistant
source .venv/bin/activate
pip install homeassistant
'

Al termine, verifica la versione installata:

sudo -u homeassistant -H bash -c '
cd /srv/homeassistant
source .venv/bin/activate
hass --version
'

Se il comando risponde con una versione valida, il pacchetto è presente e il virtualenv funziona. Se invece compare un errore di import o un problema di Python, la causa più probabile è un ambiente creato con interprete sbagliato o una dipendenza di sistema mancante. In quel caso conviene non “aggiustare a caso”: si controlla il log dell’installazione e si ricostruisce il virtualenv in modo pulito.

Configurazione iniziale di `configuration.yaml`

Home Assistant Core cerca la configurazione nella directory avviata come homeassistant, di norma /home/homeassistant/.homeassistant oppure quella definita dall’utente. Su questa installazione usiamo una struttura più esplicita sotto /srv/homeassistant per tenere insieme app, config e log in modo ordinato.

Crea la directory di configurazione e un file minimo:

sudo -u homeassistant -H mkdir -p /srv/homeassistant/config
sudo -u homeassistant -H tee /srv/homeassistant/config/configuration.yaml > /dev/null <<'EOF'
default_config:
EOF

Per un primo avvio, default_config: basta. Aggiungere subito integrazioni, automazioni e componenti custom complica la diagnosi iniziale: se il servizio non parte, devi capire se il guasto è nel core o in una personalizzazione. Prima fai partire il motore, poi allarghi.

Se vuoi una posizione più rigorosa per i file, puoi usare il parametro -c nell’avvio systemd per puntare direttamente a /srv/homeassistant/config. È una scelta più trasparente e meno ambigua rispetto a percorsi impliciti.

Servizio systemd per avvio automatico

Per renderlo gestibile come servizio, crea un’unità systemd dedicata. È il punto che fa la differenza tra una prova manuale e un servizio mantenibile: restart policy, log in journal e avvio al boot diventano standard.

sudo tee /etc/systemd/system/home-assistant.service > /dev/null <<'EOF'
[Unit]
Description=Home Assistant Core
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=homeassistant
Group=homeassistant
WorkingDirectory=/srv/homeassistant
ExecStart=/srv/homeassistant/.venv/bin/hass -c /srv/homeassistant/config
Restart=on-failure
RestartSec=5
KillMode=mixed

[Install]
WantedBy=multi-user.target
EOF

Ricarica systemd e avvia il servizio:

sudo systemctl daemon-reload
sudo systemctl enable --now home-assistant.service

Controlla subito lo stato:

systemctl status home-assistant.service --no-pager
journalctl -u home-assistant.service -b --no-pager

Se il servizio resta in active (running) e nel journal compare l’ascolto sulla porta 8123, l’installazione base è andata a buon fine. Se invece vedi restart loop, la prima cosa da guardare non è il proxy ma il journal: errore di porta occupata, path sbagliato, file di configurazione non leggibile o dipendenza Python mancante sono le cause più frequenti.

Accesso web e prima verifica funzionale

Di default Home Assistant ascolta su http://0.0.0.0:8123. Su un host appena installato, la verifica più semplice è un curl locale e poi un accesso dal browser solo dalla rete amministrativa prevista.

curl -I http://127.0.0.1:8123

Un HTTP/1.1 200 OK o comunque una risposta coerente con il servizio attivo conferma che il processo è vivo. Se il comando fallisce ma systemd dice che il servizio è su, il problema può essere un bind diverso, un crash immediato o una fase di startup ancora incompleta. In quel caso il journal è la fonte primaria, non il browser.

Al primo accesso web, Home Assistant completa la procedura guidata iniziale. Qui conviene impostare subito il fuso orario corretto, l’unità di misura e l’utente amministratore con attenzione: sono scelte banali solo in apparenza, perché poi si riflettono su automazioni, orari e notifiche.

Reverse proxy con Nginx: quando serve davvero

Se esponi Home Assistant su Internet o vuoi integrarlo con TLS centralizzato, un reverse proxy è la soluzione più ordinata. Nginx è una scelta comune perché gestisce bene WebSocket, header corretti e terminazione TLS. Non è obbligatorio per uso locale, ma diventa utile appena vuoi separare l’app dall’esposizione pubblica.

Installa Nginx e abilita i moduli necessari:

sudo apt install -y nginx
sudo systemctl enable --now nginx

Configura un server block essenziale, con supporto a WebSocket e forwarding degli header:

sudo tee /etc/nginx/sites-available/homeassistant.conf > /dev/null <<'EOF'
server {
    listen 80;
    server_name ha.example.com;

    location / {
        proxy_pass http://127.0.0.1:8123;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        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;
    }
}
EOF
sudo ln -s /etc/nginx/sites-available/homeassistant.conf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Se metti TLS davanti, aggiungi certificati validi e mantieni il proxy come unica superficie esposta. L’errore classico è aprire sia 8123 sia 443 verso l’esterno: così duplichi il rischio senza vantaggi reali. La porta 8123 dovrebbe restare limitata alla macchina locale o alla rete di management.

Configurazione di Home Assistant dietro proxy

Quando Home Assistant sta dietro Nginx o un altro proxy, devi dichiarare gli IP fidati e abilitare il supporto proxy nella configurazione. Senza questo passaggio, l’app può mostrare IP client sbagliati, rifiutare richieste o interpretare male gli header.

sudo -u homeassistant -H tee -a /srv/homeassistant/config/configuration.yaml > /dev/null <<'EOF'
http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 127.0.0.1
    - ::1
EOF

Se il proxy non è locale ma sta su un altro host o su una subnet dedicata, sostituisci gli indirizzi con quelli reali della tua infrastruttura. Non usare wildcard o reti troppo larghe senza motivo: trusted_proxies è una superficie di fiducia, non un elenco decorativo.

Dopo la modifica, riavvia Home Assistant e verifica che l’interfaccia risponda correttamente tramite il dominio pubblico o interno previsto.

Backup minimo e rollback sensato

Prima di cambiare configurazione o aggiornare il pacchetto, salva almeno tre elementi: configuration.yaml, eventuali file inclusi e il virtualenv se vuoi una fotografia completa. In pratica, il backup più utile è spesso quello della directory /srv/homeassistant/config, più una nota della versione installata.

Per un rollback rapido, la sequenza minima è questa: fermi il servizio, ripristini i file di configurazione noti buoni, eventualmente ricrei il virtualenv e riavvii. Se hai aggiornato Home Assistant e qualcosa si rompe, la via più sicura è tornare a una snapshot della directory applicativa oppure reinstallare la versione precedente nel medesimo ambiente, dopo aver verificato compatibilità delle dipendenze.

Comandi utili per il controllo prima del cambio:

cp /srv/homeassistant/config/configuration.yaml /srv/homeassistant/config/configuration.yaml.bak
systemctl stop home-assistant.service

Se il problema nasce da un errore di configurazione, il rollback è quasi sempre immediato: ripristini il file e riavvii. Se invece il guasto è nel virtualenv o in dipendenze Python, il rollback richiede più disciplina e conviene ricostruire l’ambiente da zero anziché sporcarlo con patch casuali.

Errori tipici e lettura rapida dei log

Ci sono alcuni guasti ricorrenti che vale la pena riconoscere al volo. Se la porta 8123 è già occupata, Home Assistant non parte e il journal lo dice chiaramente. Se il file di configurazione contiene YAML invalido, il servizio può andare in crash all’avvio. Se il proxy non passa gli header giusti, l’interfaccia può comportarsi in modo incoerente con login o WebSocket.

Per una diagnosi rapida, questi sono i controlli che fanno risparmiare tempo:

journalctl -u home-assistant.service -b -n 200 --no-pager
ss -ltnp | grep 8123
python3 -c 'import yaml; print("yaml ok")'

Il primo comando ti dice perché il servizio è caduto. Il secondo conferma se la porta è già presa da un altro processo. Il terzo non valida la configurazione di Home Assistant, ma ti aiuta a escludere problemi di base sul parsing YAML se stai testando il sistema fuori dal servizio.

Aggiornamenti e manutenzione ordinaria

Gli aggiornamenti di Home Assistant Core non andrebbero trattati come pacchetti di sistema qualsiasi. Prima controlla la release note della versione che vuoi installare, poi esegui il cambio nel virtualenv e osserva i log al primo avvio. Il comportamento corretto è: aggiornamento, verifica, eventuale ritorno indietro se compare regressione.

La manutenzione utile non è solo versioning. Conta anche il monitoraggio di spazio disco, RAM e stabilità del servizio. Un database o una cronologia delle entità che cresce senza controllo può saturare lo storage e produrre sintomi apparentemente casuali: lentezza, errori di scrittura, riavvii o crash. Qui il segnale più importante è la metrica, non l’impressione visiva dell’interfaccia.

Un controllo periodico minimale dovrebbe includere:

Stato servizio: systemctl is-active home-assistant.service
Log recenti: journalctl -u home-assistant.service -n 50 --no-pager
Spazio disco: df -h /srv
Porta in ascolto: ss -ltnp | grep 8123

Quando ha senso fermarsi e cambiare approccio

Se il nodo deve ospitare anche altri servizi critici, oppure se vuoi automazione di lifecycle, snapshot integrati e gestione add-on, Home Assistant Core può diventare troppo “manuale” per il tuo modello operativo. In quel caso la scelta non è “forzare Core a fare da piattaforma completa”, ma passare a un’architettura più adatta, come Home Assistant OS su VM dedicata.

La regola pratica è semplice: Core su Ubuntu è ottimo se vuoi controllo, leggerezza e una superficie di manutenzione prevedibile. Se vuoi un appliance con un ecosistema gestito, scegli un’altra strada. Mischiare i due obiettivi produce quasi sempre più lavoro operativo del previsto.

Checklist finale di installazione

Prima di considerare chiuso il lavoro, verifica almeno questi punti: servizio attivo, accesso web funzionante, configurazione salvata, log puliti e, se presente, reverse proxy correttamente configurato. È una checklist semplice, ma evita il classico scenario in cui l’installazione “sembra andare” finché non arriva il primo reboot o il primo aggiornamento.

Utente e directory: homeassistant esiste e possiede /srv/homeassistant.
Virtualenv: /srv/homeassistant/.venv è presente e hass --version risponde.
Servizio: systemctl status home-assistant.service è active (running).
Porta: ss -ltnp | grep 8123 mostra il processo corretto.
Interfaccia: il browser raggiunge la UI e completa il login iniziale.
Proxy: se usato, Nginx passa correttamente WebSocket e header.

Assunzione operativa: questa installazione è pensata per un host Ubuntu 24.04 dedicato o semi-dedicato, con Home Assistant Core gestito via systemd e configurazione sotto /srv/homeassistant.