L'installazione definitiva di Home Assistant: Docker, Plugin HACS e HTTPS

Perché non installare HomeAssistant? direttamente sul computer

Apparentemente installare HomeAssistant direttamente sul sistema operativo (sia su un Raspberry che su un normale pc) può sembrare la via migliore per sfruttare uno fra i software più diffusi al mondo in ambito domotica e automazione. Questa soluzione però porta con se anche diverse limitazioni, che si manifestano nei modi più fastidiosi possibili:

• Impossibilità di scegliere il sistema operativo dell’host su cui verrà installato HomeAssistant. Ci sono infatti molte situazioni per cui non possiamo reinstallare il sistema operativo da 0, basti pensare ad una NAS o l’eventualità di impiegare un computer con incompatibilità o con altri servizi già configurati.
• Hai bisogno di usare il computer per altri servizi e vuoi letteralmente impazzire per far funzionare tutte le dipendenze fra Home Assistant e i tuoi software?
• Se ho bisogno di migrare la mia istanza di Home Assistant devo reinstallare tutto da capo sul nuovo pc.
• Essendo un sistema già pronto e inscatolato, i file di configurazione e di log saranno su path predefiniti all’interno della macchina. Per andare a salvarli altrove o prevedere meccanismi di backup manuale dei file dovremmo modificare il sistema e rischiare di dover riconfigurare tutto ad ogni aggiornamento.
• Hai fatto un aggiornamento di HomeAssistant o di sicurezza e non si accende più il computer? Bel problema quando l’unica soluzione fattibile è quella di reinstallare tutto da capo.

Per dirla in due parole, si rischia di perdere tanto tempo, avere un sistema poco affidabile e poco flessibile.

L’alternativa a container: Docker

La soluzione Docker prevede di installare la nostra istanza di HomeAssistant dentro un container Docker, svincolandoci quasi del tutto dal sistema operativo di base. Si può dire che in questa modalità andiamo ad evitare tutti gli svantaggi che abbiamo individuato sopra nell’installazione semplice.

Con il giusto approccio, inoltre, possiamo sfruttare tutta una serie di funzionalità in più con facilità, come la cifratura HTTPS, l’impiego di un url senza doversi ricordare numeri di porta, la possibilità di cambiare versione senza sforzo e senza “danneggiare” l’ambiente.

*** Ma è più complicato installare HomeAssistant in questa modalità? è difficile ottenere una instanza con HTTPS abilitato? E posso comunque utilizzare i miei plugin HACS? *** *** è tutto nella guida! continua a leggere e te lo ritroverai già fatto ***

La soluzione definitiva per installare Home Assistant

Prerequisiti

• Un server locale, come un vecchio pc o uno di quelli a risparmio energetico che sia sempre acceso. Va bene di tutto, dai server da rack agli Intel NUC (personalmente mi trovo bene con il Gigabyte Brix) e magari perché no, un Raspberry.
  Note

  Nella guida sono descritti i passaggi in caso di utilizzo di architettura intel x64 su sistema operativo basato su Linux. In caso di architettura ARM (ad esempio un Raspberry) o altri sistemi operativi non preoccuparti, con pochi adattamenti riuscirai a raggiungere lo stesso obiettivo.
• Porta 80 e 443 non devono essere già utilizzate dal server locale.
• il server locale deve avere un indirizzo statico in LAN (e.g. 192.168.1.X).
• La rete di casa dovrà essere connessa a internet. In caso non abbia un indirizzo ip statico (in Italia per quello che so vengono concessi prettamente a contratti business) non c’è problema, è richiesta solo la registrazione di dns dinamico.
• Tramite il router di casa la porta 80 e 443 dell’interfaccia WAN dovranno essere instradate verso il server locale (port forwarding).
• docker e docker-compose devono essere installati sul server di casa. In caso non li avessi già installati, il sito ufficiale di docker fornisce delle guide semplici e efficaci a riguardo.
• Un “dynamic DNS name” (come quelli offerti da NoIP e dyn.com) o un nome statico dns nel caso in cui abbia un indirizzo ip statico. In sostanza, per far lavorare i certificati per l’https è necessario in questo caso procurarsi un url simbolico che punti all’indirizzo pubblico di casa, il solo ip non basta. A proposito, nella configurazione del dynamic dns è importante ricordarsi di indirizzare tutti i sottodomini con la wildcard asterisco-punto prima del nome. Nella guida indicherò con “YourPersonalHomeLabSite.dyndns.org” il tuo dynamic dns.
• Opzionale - Sul tuo server di casa puoi lavorare come preferisci, usando tastiera e mouse, tramite ssh, o kvm. Il mio consiglio è di utilizzare Visual Studio CODE con l’estensione Remote Development, è davvero comodo.

Cos’è un proxy inverso e perché ne abbiamo bisogno?

Il prodotto Nginx Proxy Manager è composto dal proxy Nginx (configurato come proxy inverso) e una interfaccia di gestione e configurazione. Il proxy inverso lo possiamo immaginare come un server web che risponde ad ogni pagina richiesta inviando dei contenuti da un altro server. In pratica, quando chiedo qualcosa ad un reverse proxy lui non possiede il contenuto e deve richiederlo al vero server in maniera sincrona alla mia richiesta.

Avviamo i container

Sul server locale troviamo una cartella per organizzare tutte le configurazioni e i file afferenti ai servizi esposti. Usualmente sono abituato a /opt/homelab o /homelab (puoi scegliere qualsiasi altra cartella, dovrai modificare i path che trovi di seguito nella guida concordemente alla tua scelta). Dentro questa cartella andiamo a creare gli spazi per proxy e HomeAssistant:

• /opt/homelab/homeassistant
• /opt/homelab/nginxproxymanager

Adesso configuriamo il file docker-compose del proxy /opt/homelab/nginxproxymanager/docker-compose.yaml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

version: '3.2'
services:
  app:
    image: 'jc21/nginx-proxy-manager:latest'
    deploy:
      mode: global
    restart: always
    network_mode: host # with network_mode: host all ports are potentially exposed. if you want to select only few of them comment this line and uncomments "ports" chapter.
    #ports: 
    #  - target: 80
    #    published: 80 # Public HTTP Port
    #    protocol: tcp
    #    mode: host
    #  - target: 443
    #    published: 443 # Public HTTPS Port
    #    protocol: tcp
    #    mode: host
    #  - '81:81' # Admin Web Port - This port will be exposed only in the LAN
    volumes:
      - /opt/homelab/nginxproxymanager/config.json:/app/config/production.json
      - /opt/homelab/nginxproxymanager/data:/data
      - /opt/homelab/nginxproxymanager/letsencrypt:/etc/letsencrypt
    dns:
      - 8.8.8.8

  dns:
    restart: always
    image: strm/dnsmasq
    volumes:
      - /opt/homelab/nginxproxymanager/dnsmasq.conf:/etc/dnsmasq.conf
    ports:
      - "53:53/udp"
    cap_add:
      - NET_ADMIN

Ok, avviamo il proxy Nginx lanciando dal terminale:

1
2

cd /opt/homelab/nginxproxymanager
sudo docker-compose up -d

Allo stesso modo configuriamo i container per HomeAssistant creando il file /opt/homelab/homeassistant/docker-compose.yaml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

version: '3'
services:
  homeassistant:
    container_name: homeassistant
    image: "ghcr.io/home-assistant/home-assistant:stable"
    volumes:
      - /opt/homelab/homeassistant/config:/config
      - /etc/localtime:/etc/localtime:ro
    restart: always
    privileged: true
    network_mode: host

Ladies and Gentlemen, start your engines:

1
2

cd /opt/homelab/homeassistant
sudo docker-compose up -d

Adesso è necessario andare ad autorizzare l’indirizzo del proxy inverso direttamente edntro la configurazione di Home Assistant. Andiamo nel file /opt/services/homeassistant/config/configuration.yaml e aggiungere alla voce trusted proxies:

1
2

    - IP_OF_YOUR_HOME_LAB_SERVER # type here the local ip. needed if you use network_mode:host
    - 172.16.0.0/12 # needed if you don't use network_mode:host on nginx proxy

In questo modo il file di configurazione diventerà una cosa del genere:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# Loads default set of integrations. Do not remove.
default_config:

# Text to speech
tts:
  - platform: google_translate

automation: !include automations.yaml
script: !include scripts.yaml
scene: !include scenes.yaml
http:
  use_x_forwarded_for: true
  trusted_proxies:
    - IP_OF_YOUR_HOME_LAB_SERVER
    - 172.16.0.0/12

Setup del server DNS locale

Per usare le access list basate sull’ip del mittente è necessario che le richieste locali vengano gestite all’interno della rete senza passare per la wan. Se stai richiedendo una pagina da internet, ad esempio da una connessione mobile, un dns pubblico ti instraderà verso l’interfaccia pubblica del tuo router di casa che a sua volta ti instraderà verso il tuo server locale. E fin qui tutto fila. Al contrario, se la richiesta proviene dalla lan stessa, magari un pc collegato alla stessa rete, allora dobbiamo far in modo di non essere indirizzati al nostro router, uscendo e rientrando dalla nostra rete, ma dobbiamo andare direttamente verso il server locale e il reverse proxy. Solo in questo modo il nostro ip mittente rientrerà all’interno della sottorete e riusciremo a distinguerlo dal traffico che proviene dall’esterno della rete. Per fare questo configureremo un piccolo server dns interno. Per farlo crea il file /opt/homelab/nginxproxymanager/dnsmasq.conf:

1
2
3
4
5
6
7

server=1.1.1.1
server=8.8.8.8
#explicitly define host-ip mappings
address=/YourPersonalHomeLabSite.dyndns.org/IP_OF_THE_HOMELAB_SERVER
address=/.YourPersonalHomeLabSite.dyndns.org/IP_OF_THE_HOMELAB_SERVER
address=/#.YourPersonalHomeLabSite.dyndns.org/IP_OF_THE_HOMELAB_SERVER
address=/homeassistant.YourPersonalHomeLabSite.dyndns.org/IP_OF_THE_HOMELAB_SERVER

Una volta configurato il server dns interno dovrai configurarlo nella pagina del dhcp del router e/o direttamente sui device stessi come server dns primario della configurazione ip.

Configurazione del Nginx Reverse Proxy

Da un pc nella rete LAN o dal server stesso navighiamo con un browser verso la pagina di gestione del proxy:

http://IP_OF_THE_HOMELAB_SERVER:81

Come prima cosa dobbiamo creare 2 Access List. Iniziamo dalla prima che chiamiamo LAN.

Ora passiamo a creare “LAN or Password”. In questo caso è importante indicare il flag “Pass authentication to host” per passare le credenziali all’applicazione che servirà la richiesta, in questo caso HomeAssistant.

Adesso possiamo configurare gli host, i puntamenti del nostro proxy inverso. Andiamo su Hosts->Proxy Host->Add Proxy Host. Andiamo a configurare come host proprio HomeAssistant. Nel caso voleessi configurare una homepage (dai un’occhiata alla dashboard che propongo) o altri servizi lo puoi fare allo stesso modo.

![Proxy Host for Proxy GUI -SSL](proxy_host_ssl.png “Se scegli “Request a new SSL Certificate” Nginx proxy manager si preoccuperà di richiedere, configurare e manutenere il certificato ssl per le connessioni https automaticamente!")

Nel tab “location” aggiungi qualche configurazione specifica di HomeAssistant al path “/":

1
2
3
4
5

# Cross-Origin Resource Sharing.
# Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Origin, Accept, X-Requested-With, Content-type, X-HA-access
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

Salva, aspetta e BOOM, adesso puoi navigare verso https://homeassistant.YourPersonalHomeLabSite.dyndns.org per accedere alla tua istanza di HomeAssistant, sia dalla tua rete che dall’esterno (ad esempio dal telefono su rete mobile), a patto tu abbia configurato il port forwarding sul router come indicato nei prerequisiti.

Attivazione dei plugin HACS su HomeAssistant con Docker

1
2

wget https://get.hacs.xyz -O /opt/homelab/homeassistant/config/hacs.sh 
sudo bash /opt/homelab/homeassistant/config/hacs.sh

E alla fine un bel riavvio per partire da una condizione pulita.

1
2
3

cd /opt/homelab/homeassistant
sudo docker-compose down
sudo docker-compose up -d

Navigare ora con il browser su https://homeassistant.YourPersonalHomeLabSite.dyndns.org e avviare l’applicazione creando il primo utente se necessario. Nella schermata principale dell’applicazione, andare su Impostazioni e cliccare su “Dispositivi e servizi”. Cliccare sul tasto + in basso e cercare HACS. Una volta selezionato il pacchetto l’applicazione vi chiederà di accedere o registrarvi ad un account su github.

Boom, ce l’hai fatta

Adesso non ti rimane altro che configurare HomeAssistant con tutti i dispositivi che hai dentro casa.

Ti prudono ancora le mani?

• Stanco di doverti ricordare dozzine di ip, porte, url per ognuna delle tue applicazioni installate in casa? Dai uno sguardo alla semplice dashboard che è possibile realizzare.
• Una buona idea quando si espone un servizio web su internet è quella di adottare un Web Application Firewall per controllare e supervisionare il traffico con l’esterno.

Avvertenze

Di base stai esponendo il proxy inverso e tutti gli host su internet, a meno delle access list configurate, e questo può costituire un rischio per la privacy e la sicurezza cibernetica. Per tale motivo è necessario avere sempre un occhio di riguardo per i test e per raffinare la configurazione, accertandosi che tutto stia funzionando correttamente e le uniche cose accessibili su internet siano quelle desiderate.

Se navighi dall’esterno verso il tuo ip pubblico noterai una schermata di errore 404, motivata dal fatto che al proxy inverso è richiesta la pagina web associata a quell’indirizzo ip. Il proxy inverso però non sa quale contenuto fornire, in quanto non è configurato alcun host associato ad un indirizzo ip.

Se vuoi limitare al massimo i servizi esposti su internet ti basta impostare tutti gli host, ad eccezione del principale della dashboard, sulla Access list “LAN”.

Un’ultima cosa. Google Chrome, Edge e i dispositivi Google sembra che abbiano iniziato ad utilizzare i propri servizi dns al posto di quelli del sistema operativo. Questo può creare qualche problema al traffico interno, in quanto noteremo che le richieste interne andranno verso la wan e poi torneranno indietro. Per evitare il problema, dalle impostazioni del browser basta impostare su off la configurazione “use secure dns”. In alternativa, se la tua casa è dotata di firewall, puoi bloccare le richieste di dns verso i server autoritativi di Google (magari consentendoli solo al tuo server locale). Ho notato inoltre che è meglio disabilitare il flag #use-dns-https-svcb-alpn in edge://flags/ e chrome://flags/. Ne parlo qui

10 Bisogno di una mano?

Se qualcosa non funziona come dovrebbe non preoccuparti, sei sulla strada giusta. Fai una passata per verificare punto per punto che i prerequisiti siano soddisfatti e assicurati di partire da un ambiente il più possibile pulito. In caso ci siano ancora dei problemi non esitare a lasciare un commento in modo che io o qualcun altro ti possa aiutare.