Come installare Eclipse Mosquitto MQTT con Docker Compose

Prerequisiti & Hardware Necessario

• Hardware: server Linux, Raspberry Pi 5 o VM Debian con Docker Engine, rete locale stabile e storage persistente. Per un host compatto puoi usare un Raspberry Pi 5 4GB con alimentatore ufficiale.
• Software: Docker Engine, Docker Compose v2 ed Eclipse Mosquitto, broker MQTT open source. Mosquitto è il software broker; Home Assistant è un client MQTT e non sostituisce il broker.
• Rete: porta TCP 1883 per MQTT non cifrato nella LAN. Non esporla direttamente su Internet; per accesso remoto usa VPN o configura TLS con certificati.
• Dati: directory persistenti per /mosquitto/config, /mosquitto/data e /mosquitto/log.

Procedura passo-passo

1. Crea le directory del broker.

   sudo install -d -m 0755 /opt/mosquitto/config /opt/mosquitto/data /opt/mosquitto/log
   cd /opt/mosquitto

2. Crea la configurazione iniziale. Salva in /opt/mosquitto/config/mosquitto.conf:

   persistence true
   persistence_location /mosquitto/data/
   log_dest stdout
   listener 1883
   allow_anonymous false
   password_file /mosquitto/config/password_file

   Definire un listener richiede esplicitamente autenticazione: non abilitare allow_anonymous true su una rete domestica non isolata.

3. Crea il file delle credenziali. Sostituisci il nome utente e inserisci una password lunga quando richiesto:

   docker run --rm -it -v /opt/mosquitto/config:/mosquitto/config eclipse-mosquitto:2 mosquitto_passwd -c /mosquitto/config/password_file homeassistant

4. Crea /opt/mosquitto/compose.yaml.

   services:
     mosquitto:
       image: eclipse-mosquitto:2
       container_name: mosquitto
       restart: unless-stopped
       ports:
         - "1883:1883"
       volumes:
         - /opt/mosquitto/config:/mosquitto/config
         - /opt/mosquitto/data:/mosquitto/data
         - /opt/mosquitto/log:/mosquitto/log

5. Avvia e controlla il broker.

   cd /opt/mosquitto
   docker compose config
   docker compose up -d
   docker compose ps
   docker compose logs --tail=100 mosquitto

   Lo stato deve essere Up e il log non deve riportare errori di lettura di configurazione o password.
6. Prova autenticazione e pubblicazione. Apri un terminale e sottoscrivi un topic:

   docker run --rm -it --network host eclipse-mosquitto:2 mosquitto_sub -h 127.0.0.1 -p 1883 -u homeassistant -P 'PASSWORD_REALE' -t domotica/test -v

   In un secondo terminale pubblica:

   docker run --rm eclipse-mosquitto:2 mosquitto_pub -h HOST_MQTT -p 1883 -u homeassistant -P 'PASSWORD_REALE' -t domotica/test -m 'ok'

7. Collega Home Assistant. Vai in Impostazioni → Dispositivi e servizi → Aggiungi integrazione → MQTT. Inserisci hostname o IP del server Mosquitto, porta 1883, utente homeassistant e password. Se Home Assistant gira sulla stessa macchina ma in un container separato, usa l’IP del server o una rete Docker condivisa: non assumere che 127.0.0.1 punti al broker.
8. Verifica MQTT Discovery. Pubblica solo dopo aver collegato l’integrazione. Il prefisso discovery predefinito di Home Assistant è homeassistant; controllalo nelle opzioni MQTT e non usare topic casuali per i messaggi di discovery.
9. Aggiorna con backup. Salva /opt/mosquitto/config e /opt/mosquitto/data, poi esegui

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

   Non usare docker compose down -v: potrebbe eliminare volumi e dati persistenti.

Verifica del funzionamento

La configurazione è corretta quando il container Mosquitto è attivo, la porta 1883 è in ascolto, una sottoscrizione autenticata riceve il messaggio di test e Home Assistant completa la configurazione MQTT. Una connessione senza credenziali deve essere rifiutata. Riavvia il server e verifica che i messaggi retained e la persistenza restino disponibili dove previsto.

Problemi comuni

FAQ essenziali

Posso usare Mosquitto senza password?

Solo in un ambiente isolato e temporaneo. Per una rete domotica usa autenticazione; allow_anonymous false evita client sconosciuti.

Devo usare MQTT 1883 o 8883?

1883 è MQTT TCP senza TLS, adatto alla LAN protetta. 8883 è una convenzione comune per MQTT con TLS, ma richiede certificati e una configurazione esplicita del listener.