Mosquitto Docker: come configurare il broker MQTT Eclipse Mosquitto con Docker e Docker Compose
Guida passo passo al deployment di un broker MQTT Mosquitto pronto per la produzione con container Docker. Include autenticazione, crittografia TLS, configurazione della persistenza e integrazione con Home Assistant.
Configurare un broker MQTT da zero non dovrebbe richiedere ore di settaggi e troubleshooting.
Eclipse Mosquitto è un broker MQTT open source che implementa i protocolli MQTT v5, 3.1.1 e 3.1, rendendolo perfetto per dispositivi IoT, sistemi di domotica, applicazioni cloud e qualsiasi architettura basata su messaggi. Ma installare e configurare Mosquitto direttamente sul tuo sistema spesso porta a conflitti di dipendenze, problemi di permessi e grattacapi specifici della piattaforma che ti mangiano il tempo di sviluppo. Finirai per passare più tempo a combattere con il setup che a costruire la tua applicazione.
Docker elimina questi mal di testa fornendo un ambiente coerente e isolato per eseguire Mosquitto su qualsiasi piattaforma. In pochi minuti puoi avere un broker MQTT pienamente funzionante, completo di configurazioni personalizzate, autenticazione e persistenza.
In questa guida ti accompagno nel deployment di Eclipse Mosquitto usando Docker e Docker Compose, configurando autenticazione e logging, impostando la persistenza dei dati e testando il broker con veri client MQTT.
Se sei completamente nuovo a Docker, ti consiglio di iniziare dal nostro corso Introduction to Docker per apprendere le basi.
Cos'è Mosquitto e perché usarlo in Docker
Non ti serve un sistema di messaggistica pesante quando tutto ciò che vuoi è una comunicazione veloce e affidabile tra dispositivi.
MQTT è un protocollo publish-subscribe leggero, pensato per situazioni in cui la banda è limitata e l'affidabilità conta. Pensa a sensori IoT, app mobile o qualsiasi scenario in cui i dispositivi devono scambiarsi piccoli messaggi rapidamente, senza polling continuo.
Mosquitto funge da intermediario - il broker - tra publisher e subscriber.
I publisher inviano messaggi a topic specifici. I subscriber ascoltano quei topic. Mosquitto gestisce l'instradamento, assicurando che i messaggi arrivino nei posti giusti senza che publisher e subscriber debbano conoscersi a vicenda.
Ecco perché Docker rende ancora migliori i setup Mosquitto in Docker:
Setup coerente su tutte le piattaforme: Windows, macOS o Linux: il container Docker gira esattamente allo stesso modo. Niente più caccia agli installer specifici per piattaforma o conflitti di dipendenze.
Gestione semplice delle versioni: puoi bloccare versioni specifiche di Mosquitto usando i tag delle immagini, fare rollback se qualcosa si rompe e testare nuove versioni senza toccare il sistema host.
Portabilità vera: lo stesso setup di Mosquitto in Docker funziona in sviluppo, staging e produzione. Il tuo ambiente locale rispecchia quello in esecuzione sui server.
Mosquitto è disponibile in due varianti: la versione open source (che copre la maggior parte dei casi d'uso) e la Pro Edition commerciale di Cedalo con funzionalità avanzate come clustering e sicurezza potenziata. Per la maggior parte dei progetti, la versione open source fa tutto ciò che serve.
Di seguito vediamo i prerequisiti, poi passiamo all'installazione di Mosquitto.
Prerequisiti
Prima di poter distribuire Mosquitto, devi avere Docker in esecuzione sul tuo sistema.
Docker Desktop è l'ideale per chi usa Windows e macOS, perché include tutto in un unico pacchetto. Gli utenti Linux possono installare direttamente la Docker CLI tramite il proprio gestore pacchetti o dal repository ufficiale di Docker.
Docker Compose non è obbligatorio, ma rende la gestione di setup multi-container molto più semplice. La maggior parte delle installazioni di Docker Desktop include Compose di default. Se sei su Linux, potresti doverlo installare separatamente.
Ti serviranno anche competenze di base da riga di comando. Niente di complicato: saper eseguire comandi, navigare tra directory e modificare file di testo.
Setup passo per passo
Per avviare Mosquitto in Docker servono tre passaggi: creare le directory, eseguire il container e, facoltativamente, impostare Docker Compose per una gestione più semplice.
Creazione delle directory richieste
Mosquitto ha bisogno di uno storage organizzato per configurazione, dati e log.
Creale per iniziare:
mkdir mosquitto-docker
cd mosquitto-docker
mkdir config data logsOfferto da
Questo ti dà cartelle organizzate per i file di configurazione di Mosquitto, i dati persistenti e l'output dei log.
Ecco a cosa serve ciascuna directory:
/mosquitto/config contiene mosquitto.conf e altri file di configurazione
/mosquitto/data conserva i dati dei messaggi persistenti e le informazioni sulle sottoscrizioni
/mosquitto/log contiene i file di log di Mosquitto per debug e monitoraggio
Queste directory vengono montate come volumi all'interno del container Docker, così impostazioni e dati sopravvivono ai riavvii del container.
Eseguire Mosquitto con Docker
Il comando Docker di base avvia Mosquitto con il corretto mapping delle porte e i volumi montati.
docker run -d\--name mosquitto \-p1883:1883 \-v$(pwd)/mosquitto/config:/mosquitto/config \-v$(pwd)/mosquitto/data:/mosquitto/data \-v$(pwd)/mosquitto/log:/mosquitto/log \
eclipse-mosquitto:latestOfferto da
Immagine 1 - Esecuzione di Mosquitto con Docker
Ecco una spiegazione delle opzioni:
-d esegue il container in background (modalità detached)
--name mosquitto assegna al container un nome leggibile per riferimenti facili
-p 1883:1883 mappa la porta 1883 dell'host alla 1883 del container
-v monta directory locali come volumi nel container
Mosquitto 2.0+ è in modalità solo locale per impostazione predefinita. Significa che accetta connessioni solo da localhost a meno che tu non lo configuri diversamente. Dovrai creare un file di configurazione per consentire connessioni esterne.
Usare Docker Compose
Docker Compose per Mosquitto semplifica molto la gestione dell'installazione, soprattutto quando esegui più servizi.
Crea un file docker-compose.yml e incolla il seguente contenuto:
Immagine 2 - Esecuzione di Mosquitto con Docker Compose
I mapping dei volumi funzionano come con il comando Docker, ma Compose gestisce la complessità. La configurazione delle porte copre tutti i protocolli MQTT comuni: MQTT standard (1883), MQTTS sicuro (8883) e connessioni WebSocket (9001).
Compose dà il meglio con setup multi-servizio. Per esempio, se esegui Home Assistant, Node-RED o altri strumenti IoT insieme a Mosquitto, puoi definire tutto in un unico file e avviare tutti i servizi insieme.
Ora approfondiamo la configurazione.
Trovi confusi i concetti Docker più avanzati? Il nostro corso Intermediate Docker va ben oltre le basi.
Configurare Mosquitto
Mosquitto non accetta connessioni esterne out of the box: serve un file di configurazione per abilitarle.
Configurazione di base (mosquitto.conf)
Crea un file mosquitto.conf nella directory mosquitto/config e aggiungi quanto segue:
L'impostazione allow_anonymous true consente ai client di connettersi senza credenziali. Va bene per sviluppo o reti interne, ma in produzione vorrai disabilitarla. Quando imposti allow_anonymous false, ogni client deve autenticarsi con username e password.
Il listener WebSocket sulla porta 9001 abilita i client MQTT basati su browser. Le applicazioni web possono connettersi direttamente al broker usando librerie JavaScript come Paho MQTT.
Impostare l'autenticazione
L'autenticazione richiede la creazione di un file delle password e l'aggiornamento della configurazione.
Genera un file delle password all'interno del container:
dockerexec-it mosquitto mosquitto_passwd -c /mosquitto/config/passwd usernameOfferto da
Immagine 3 - Autenticazione Mosquitto
Questo crea un nuovo file delle password e ti chiede di inserirne una. Per utenti aggiuntivi, rimuovi il flag -c:
dockerexec-it mosquitto mosquitto_passwd /mosquitto/config/passwd another_userOfferto da
Ora aggiorna il tuo mosquitto.conf per forzare l'autenticazione:
Dovrai ottenere i certificati SSL per il tuo dominio. Let's Encrypt fornisce certificati gratuiti, oppure puoi usare reverse proxy come Caddy Server che gestiscono automaticamente la generazione dei certificati. Metti i file dei certificati nella directory mosquitto/config in modo che siano disponibili nel container.
Persistenza e logging
La persistenza salva su disco messaggi e sottoscrizioni, mentre un logging adeguato ti aiuta a diagnosticare problemi di connessione.
Puoi configurare la persistenza in mosquitto.conf così:
# Enable persistence
persistence true
persistence_location /mosquitto/data/
# Save to disk every 300 seconds
autosave_interval 300# Keep messages for offline clients
persistent_client_expiration 1dOfferto da
Per quanto riguarda il logging, ecco come impostare un logging dettagliato:
# Log to file and stdout
log_dest file /mosquitto/log/mosquitto.log
log_dest stdout
# Choose what to log
log_type error
log_type warning
log_type notice
log_type information
log_type debug
# Log connection details
connection_messages true
log_timestamp trueOfferto da
Le opzioni log_type ti permettono di filtrare cosa registrare:
error e warning per il monitoraggio in produzione
notice e information per informazioni operative generali
debug per risolvere problemi di connessione
I volumi montati assicurano che sia i dati persistenti che i log sopravvivano ai riavvii del container. La directory dei dati archivia tutti i messaggi persistenti e le informazioni sulle sottoscrizioni, mentre la directory dei log mantiene le informazioni di debug accessibili dall'host.
I file di configurazione ti danno il pieno controllo del comportamento di Mosquitto senza dover ricostruire i container.
Test del setup
Il tuo broker non è utile finché non verifichi che i client possano connettersi e scambiarsi messaggi.
Usare mosquitto_pub e mosquitto_sub
Gli strumenti da riga di comando mosquitto_pub e mosquitto_sub sono il modo più rapido per testare il broker.
Inizia installando Mosquitto, a seconda della piattaforma:
Linux (Ubuntu/Debian): sudo apt-get install mosquitto-clients
macOS:brew install mosquitto
Windows: Scarica dal sito ufficiale di Eclipse Mosquitto o usa WSL
Iniziamo a testare senza autenticazione. Ti servono due finestre o tab del terminale. Esegui questi comandi in sessioni separate:
# Subscribe to a topic (run this first)
mosquitto_sub -h localhost -p1883-t test/topic
# Publish a message (run in another terminal)
mosquitto_pub -h localhost -p1883-t test/topic -m"Hello MQTT"Offerto da
Nel tab di pubblicazione vedrai questo:
Immagine 4 - Pubblicazione di un messaggio
E nel tab di sottoscrizione vedrai immediatamente il messaggio:
Immagine 5 - Sottoscrizione a un topic Mosquitto
Se richiedi l'autenticazione, i comandi sono molto simili: ti basta passare username e password:
# Subscribe with username and password
mosquitto_sub -h localhost -p1883-t test/topic -u username -P password
# Publish with credentials
mosquitto_pub -h localhost -p1883-t test/topic -m"Authenticated message"-u username -P passwordOfferto da
Se non vuoi installare i client Mosquitto in locale, eseguili all'interno del tuo container Docker:
# Subscribe using the containerdockerexec-it mosquitto mosquitto_sub -h localhost -t test/topic
# Publish using the containerdockerexec-it mosquitto mosquitto_pub -h localhost -t test/topic -m"Container message"Offerto da
Nel tab di pubblicazione vedrai questo:
Immagine 6 - Pubblicazione di un messaggio senza auth
E nel tab di sottoscrizione vedrai il messaggio:
Immagine 7 - Sottoscrizione a un topic Mosquitto senza auth
Test con client MQTT
I client con interfaccia grafica semplificano il test di scenari complessi e il monitoraggio del traffico dei messaggi in corso.
MQTT Explorer offre un'interfaccia pulita per esplorare i topic e inviare messaggi. Connettiti a localhost:1883 e vedrai una vista ad albero di tutti i topic attivi. È perfetto per il debug dei flussi di messaggi e per comprendere la struttura dei topic.
Immagine 8 - App MQTT Explorer
MQTTX offre funzionalità più avanzate come scripting e invio massivo di messaggi. Entrambi i client supportano autenticazione, connessioni TLS e protocolli WebSocket.
Chi usa Home Assistant può testare l'integrazione MQTT direttamente dagli strumenti per sviluppatori. Aggiungi i dettagli del broker all'integrazione MQTT e usa l'interfaccia di publish/subscribe integrata.
Per test programmati, il client Paho MQTT per Python funziona bene:
import paho.mqtt.client as mqtt
defon_connect(client, userdata, flags, rc):print(f"Connected with result code {rc}")
client.subscribe("test/topic")defon_message(client, userdata, msg):print(f"Received: {msg.payload.decode()}")
client = mqtt.Client()# client.username_pw_set("username", "password") # If using auth
client.on_connect = on_connect
client.on_message = on_message
client.connect("localhost",1883,60)
client.loop_forever()Offerto da
Esegui questo script in un terminale, poi pubblica messaggi da un altro terminale o client GUI. Lo script stamperà qualsiasi messaggio ricevuto, confermando che il broker instrada correttamente il traffico.
Ecco cosa devi fare per pubblicare un messaggio:
Immagine 9 - Pubblicazione di un messaggio per l'esempio Python
E vedrai questo nella sessione del terminale in cui gira lo script Python:
Immagine 10 - Ricezione di un messaggio per l'esempio Python
Pubblicazione e sottoscrizione funzionanti significano che il tuo setup Mosquitto in Docker è pronto per applicazioni reali.
Integrazione di Mosquitto in Docker con Home Assistant
Eseguire Mosquitto insieme a Home Assistant in Docker crea un hub di messaggistica IoT completo senza problemi di configurazione di rete.
Docker Compose rende semplice tutto ciò. Entrambi i servizi possono comunicare tramite la rete interna di Docker senza esporre porte aggiuntive o gestire indirizzi IP.
Ecco un docker-compose.yml completo che esegue entrambi i servizi:
La sezione networks crea una rete condivisa in cui entrambi i container possono raggiungersi per nome. Home Assistant può connettersi a mosquitto:1883 invece di usare localhost o indirizzi IP.
Poi configura l'integrazione MQTT tramite l'interfaccia web di Home Assistant. Vai su Impostazioni > Dispositivi e Servizi > Aggiungi Integrazione, quindi cerca "MQTT".
Inserisci questi dettagli di connessione:
Broker: mosquitto (il nome del container)
Porta: 1883
Username/Password: le tue credenziali se l'autenticazione è abilitata
Lascia le altre impostazioni ai valori predefiniti
Clicca Invia e Home Assistant testerà la connessione. Se va a buon fine, vedrai MQTT nella lista delle integrazioni.
Immagine 11 - Configurazione di Mosquitto con Homelab
Ora puoi aggiungere dispositivi MQTT, creare automazioni che pubblicano messaggi e monitorare i dati dei sensori tramite i topic. L'integrazione MQTT di Home Assistant gestisce automaticamente il discovery dei dispositivi compatibili.
Risoluzione dei problemi comuni
La maggior parte dei problemi con Mosquitto in Docker si riduce a permessi, porte o errori di configurazione che bloccano le connessioni.
Errori di permesso con volumi montati
Si verificano quando il container non può scrivere nelle directory dell'host. Nei log vedrai messaggi come "Permission denied" o "Cannot create directory".
Risolvi impostando la proprietà corretta sulle directory:
Il container Mosquitto gira come utente con ID 1883, quindi le directory dell'host devono corrispondere. Su alcuni sistemi potresti dover prima creare l'utente:
sudouseradd-u1883 mosquitto
sudochown-R mosquitto:mosquitto mosquitto/Offerto da
Conflitti di porta
Si verificano quando qualcos'altro usa la porta 1883. Controlla cosa sta girando su quella porta:
# Linux/macOSsudolsof-i :1883
# Windowsnetstat-an| findstr :1883Offerto da
Se un altro servizio usa la porta, fermalo oppure mappa Mosquitto su un'altra porta:
docker run -p1884:1883 eclipse-mosquitto:latestOfferto da
La modalità solo locale impedisce le connessioni esterne
Questo accade anche se il container è in esecuzione. Dalla versione 2.0+, Mosquitto accetta per default connessioni solo da localhost a meno di configurazioni diverse.
Crea un mosquitto.conf di base per consentire connessioni esterne:
Causano problemi di permessi persistenti. Il container si aspetta di girare come utente 1883, ma il tuo host potrebbe avere esigenze diverse di ownership.
Forza l'esecuzione del container come il tuo utente:
docker run --user$(id-u):$(id-g) eclipse-mosquitto:latestOfferto da
Oppure adegua i permessi delle directory sull'host per soddisfare le aspettative del container. L'approccio del container è migliore in sviluppo, mentre correggere i permessi sull'host funziona meglio in produzione.
Controlla i log del container quando qualcosa non funziona: di solito ti dicono esattamente qual è il problema.
Avanzato: funzionalità di Mosquitto Pro Edition
La versione open source di Mosquitto copre la maggior parte dei casi d'uso, ma gli ambienti enterprise necessitano di funzionalità che solo la Pro Edition offre.
Gestione utenti basata sui ruoli ti consente di definire permessi granulari per diversi gruppi di utenti. Invece di gestire l'accesso dei singoli, crei ruoli come "sensor-readers", "actuator-controllers" o "admin-users" e assegni permessi ai ruoli. Gli utenti ereditano i permessi dei ruoli assegnati, semplificando la gestione degli accessi su centinaia o migliaia di dispositivi.
Puoi limitare l'accesso per pattern di topic, intervalli IP o finestre temporali. È molto meglio che configurare manualmente file ACL quando gestisci deployment IoT complessi con esigenze di sicurezza diverse.
Opzioni di autenticazione avanzate vanno oltre la semplice combinazione username/password. L'autenticazione tramite token JWT si integra con identity provider esistenti come Auth0, Okta o il sistema SSO della tua azienda. L'integrazione LDAP si collega direttamente ad Active Directory o ad altri servizi di directory enterprise.
Ispezione e monitoraggio approfonditi ti danno visibilità in tempo reale sui flussi di messaggi, i pattern di connessione e le prestazioni del broker. La Pro Edition include dashboard integrate che mostrano quali client consumano più banda, quali topic hanno i tassi di messaggi più alti e dove si stanno formando colli di bottiglia.
Ottieni metriche dettagliate su latenza dei messaggi, profondità delle code e pattern di comportamento dei client. Questi dati ti aiutano a ottimizzare le strutture dei topic e a individuare client problematici prima che impattino l'intero sistema.
Integrazioni con database e servizi cloud eliminano la necessità di applicazioni bridge personalizzate. La Pro Edition può inoltrare automaticamente i messaggi verso PostgreSQL, MongoDB, InfluxDB, AWS IoT Core, Azure IoT Hub o Google Cloud IoT. Definisci regole di instradamento che determinano dove vanno i messaggi in base ai pattern dei topic, al contenuto dei messaggi o ai metadati del client.
Code persistenti per scenari ad alto volume in cui la persistenza standard di Mosquitto non basta. La Pro Edition può bufferizzare milioni di messaggi per client offline e distribuire il carico su più istanze del broker. Include una gestione automatica delle code che previene l'esaurimento della memoria e mantiene le garanzie di ordinamento dei messaggi.
Il supporto al clustering ti consente di eseguire più istanze del broker che condividono il carico dei messaggi e forniscono protezione dal failover. Quando un broker va giù, i client si riconnettono automaticamente alle istanze sane senza perdere messaggi o sottoscrizioni.
La Pro Edition ha senso quando ti servono affidabilità e funzionalità di gestione di livello enterprise che richiederebbero mesi per essere costruite in proprio.
Pro e contro dell'uso di Mosquitto in Docker
Docker semplifica il deployment, ma non è la soluzione perfetta per ogni scenario.
Pro
Coerenza cross-platform elimina i mal di testa delle installazioni specifiche per OS. Lo stesso comando Docker funziona su Windows, macOS e Linux senza dover cercare diversi gestori pacchetti o affrontare conflitti di dipendenze. Il tuo setup di sviluppo rispecchia esattamente la produzione, quindi meno sorprese al deploy.
Upgrade di versione semplici avvengono cambiando i tag delle immagini. Invece di disinstallare la vecchia versione sperando che l'upgrade non rompa la config, ti basta fare pull di una nuova immagine e riavviare il container. Il rollback richiede pochi secondi se qualcosa va storto.
Backup e migrazione facili grazie all'uso dei volumi per i dati. Copia la directory mosquitto su un'altra macchina, esegui lo stesso comando Docker e sei di nuovo operativo. Spostarsi tra provider cloud o aggiornare l'hardware diventa un semplice trasferimento di file.
Contro
Docker non è solo vantaggi.
Problemi di permessi sui volumi affliggono alcuni sistemi operativi, soprattutto passando tra host Windows e Linux. Perderai tempo a correggere ownership e a gestire mismatch di UID/GID che non esisterebbero con un'installazione nativa.
Configurazioni extra per sicurezza di livello produzione significano che Docker aggiunge complessità invece di rimuoverla. Devi gestire policy di rete, contesti di sicurezza dei container e crittografia dei volumi oltre alle funzionalità di sicurezza di Mosquitto. Le installazioni native ti permettono di usare direttamente i framework di sicurezza del sistema operativo.
Possibile impatto sulle prestazioni in scenari ad alto throughput in cui conta ogni microsecondo. Il livello di networking dei container e i volumi montati aggiungono overhead che le installazioni native evitano. Per la maggior parte delle applicazioni IoT la differenza è trascurabile, ma i sistemi industriali real-time potrebbero notare la latenza.
Docker vince quando ti servono deployment coerenti e gestione semplice su ambienti diversi.
Conclusione
Eseguire Mosquitto in Docker ti dà un broker MQTT affidabile che funziona in modo coerente in tutti gli ambienti. Che tu stia prototipando dispositivi IoT, costruendo sistemi di domotica o collegando sensori in sviluppo, Docker elimina la complessità del setup e ti permette di concentrarti sul progetto vero e proprio.
Se prevedi di portare Mosquitto in produzione, ricorda questo:
Proteggi il broker prima di esporlo a internet
Abilita l'autenticazione con mosquitto_passwd, configura la crittografia TLS con certificati adeguati
Limita l'accesso solo ai client che ne hanno bisogno
Un broker MQTT non protetto diventa una porta aperta per gli attaccanti per monitorare le comunicazioni dei dispositivi o iniettare comandi malevoli.
Per deployment enterprise che richiedono funzionalità avanzate come controllo degli accessi basato sui ruoli, clustering o integrazione LDAP, Mosquitto Pro Edition fornisce strumenti di gestione e scalabilità che vanno oltre la versione open source.
Qual è la differenza tra eseguire Mosquitto nativamente e in Docker?⌄
Docker offre coerenza cross-platform ed elimina i conflitti di dipendenze che affliggono le installazioni native. Il tuo setup Mosquitto funziona in modo identico su Windows, macOS e Linux senza dover cercare pacchetti specifici per piattaforma. Docker rende anche semplici upgrade e rollback di versione: basta cambiare il tag dell'immagine e riavviare il container. Tuttavia, le installazioni native possono offrire prestazioni leggermente migliori in scenari ad alto throughput.
Ho bisogno di Docker Compose per eseguire Mosquitto o posso usare i comandi Docker normali?⌄
Puoi assolutamente eseguire Mosquitto con i normali comandi Docker usando docker run. Docker Compose rende solo la gestione più semplice, soprattutto quando esegui più servizi come Home Assistant o Node-RED insieme a Mosquitto. Se stai eseguendo solo Mosquitto, un semplice comando docker run va benissimo.
Mosquitto in Docker è abbastanza sicuro per l'uso in produzione?⌄
Mosquitto in Docker può essere pronto per la produzione con la giusta configurazione. Dovrai disabilitare l'accesso anonimo, impostare l'autenticazione con mosquitto_passwd, configurare la crittografia TLS e limitare l'accesso di rete solo ai client fidati. Il container in sé non aggiunge vulnerabilità, ma spetta a te mettere in sicurezza sia la configurazione di Mosquitto sia l'ambiente Docker.
Perché il mio container Mosquitto si avvia ma rifiuta connessioni esterne?⌄
Dalla versione 2.0+, Mosquitto è in modalità solo locale, che accetta connessioni solo da localhost all'interno del container. Devi creare un file mosquitto.conf con listener 1883 e allow_anonymous true (per test) oppure impostazioni di autenticazione adeguate. Metti questo file di configurazione nella directory montata /mosquitto/config e riavvia il container.
Come risolvo gli errori "Permission denied" quando Mosquitto prova a scrivere nei volumi montati?⌄
Il container Mosquitto gira come utente con ID 1883, ma le directory dell'host potrebbero avere un'ownership diversa. Esegui sudo chown -R 1883:1883 mosquitto/ per correggere la proprietà, oppure crea prima l'utente mosquitto con sudo useradd -u 1883 mosquitto e poi cambia la proprietà. Su alcuni sistemi puoi anche eseguire il container con --user $(id -u):$(id -g) per farlo corrispondere al tuo utente host.
Senior Data Scientist con base in Croazia. Top Tech Writer con oltre 700 articoli pubblicati, per più di 10 milioni di visualizzazioni. Autore del libro Machine Learning Automation with TPOT.
Scopri i 15 migliori server MCP remoti che stanno trasformando lo sviluppo AI nel 2026. Scopri come migliorano automazione, ragionamento, sicurezza e velocità dei workflow.
Configurare un broker MQTT da zero non dovrebbe richiedere ore di settaggi e troubleshooting.
Eclipse Mosquitto è un broker MQTT open source che implementa i protocolli MQTT v5, 3.1.1 e 3.1, rendendolo perfetto per dispositivi IoT, sistemi di domotica, applicazioni cloud e qualsiasi architettura basata su messaggi. Ma installare e configurare Mosquitto direttamente sul tuo sistema spesso porta a conflitti di dipendenze, problemi di permessi e grattacapi specifici della piattaforma che ti mangiano il tempo di sviluppo. Finirai per passare più tempo a combattere con il setup che a costruire la tua applicazione.
Docker elimina questi mal di testa fornendo un ambiente coerente e isolato per eseguire Mosquitto su qualsiasi piattaforma. In pochi minuti puoi avere un broker MQTT pienamente funzionante, completo di configurazioni personalizzate, autenticazione e persistenza.
In questa guida ti accompagno nel deployment di Eclipse Mosquitto usando Docker e Docker Compose, configurando autenticazione e logging, impostando la persistenza dei dati e testando il broker con veri client MQTT.
Se sei completamente nuovo a Docker, ti consiglio di iniziare dal nostro corso Introduction to Docker per apprendere le basi.
Cos'è Mosquitto e perché usarlo in Docker
Non ti serve un sistema di messaggistica pesante quando tutto ciò che vuoi è una comunicazione veloce e affidabile tra dispositivi.
MQTT è un protocollo publish-subscribe leggero, pensato per situazioni in cui la banda è limitata e l'affidabilità conta. Pensa a sensori IoT, app mobile o qualsiasi scenario in cui i dispositivi devono scambiarsi piccoli messaggi rapidamente, senza polling continuo.
Mosquitto funge da intermediario - il broker - tra publisher e subscriber.
I publisher inviano messaggi a topic specifici. I subscriber ascoltano quei topic. Mosquitto gestisce l'instradamento, assicurando che i messaggi arrivino nei posti giusti senza che publisher e subscriber debbano conoscersi a vicenda.
Ecco perché Docker rende ancora migliori i setup Mosquitto in Docker:
Mosquitto è disponibile in due varianti: la versione open source (che copre la maggior parte dei casi d'uso) e la Pro Edition commerciale di Cedalo con funzionalità avanzate come clustering e sicurezza potenziata. Per la maggior parte dei progetti, la versione open source fa tutto ciò che serve.
Di seguito vediamo i prerequisiti, poi passiamo all'installazione di Mosquitto.
Prerequisiti
Prima di poter distribuire Mosquitto, devi avere Docker in esecuzione sul tuo sistema.
Docker Desktop è l'ideale per chi usa Windows e macOS, perché include tutto in un unico pacchetto. Gli utenti Linux possono installare direttamente la Docker CLI tramite il proprio gestore pacchetti o dal repository ufficiale di Docker.
Docker Compose non è obbligatorio, ma rende la gestione di setup multi-container molto più semplice. La maggior parte delle installazioni di Docker Desktop include Compose di default. Se sei su Linux, potresti doverlo installare separatamente.
Ti serviranno anche competenze di base da riga di comando. Niente di complicato: saper eseguire comandi, navigare tra directory e modificare file di testo.
Setup passo per passo
Per avviare Mosquitto in Docker servono tre passaggi: creare le directory, eseguire il container e, facoltativamente, impostare Docker Compose per una gestione più semplice.
Creazione delle directory richieste
Mosquitto ha bisogno di uno storage organizzato per configurazione, dati e log.
Creale per iniziare:
Questo ti dà cartelle organizzate per i file di configurazione di Mosquitto, i dati persistenti e l'output dei log.
Ecco a cosa serve ciascuna directory:
/mosquitto/configcontienemosquitto.confe altri file di configurazione/mosquitto/dataconserva i dati dei messaggi persistenti e le informazioni sulle sottoscrizioni/mosquitto/logcontiene i file di log di Mosquitto per debug e monitoraggioQueste directory vengono montate come volumi all'interno del container Docker, così impostazioni e dati sopravvivono ai riavvii del container.
Eseguire Mosquitto con Docker
Il comando Docker di base avvia Mosquitto con il corretto mapping delle porte e i volumi montati.
Immagine 1 - Esecuzione di Mosquitto con Docker
Ecco una spiegazione delle opzioni:
-desegue il container in background (modalità detached)--name mosquittoassegna al container un nome leggibile per riferimenti facili-p 1883:1883mappa la porta 1883 dell'host alla 1883 del container-vmonta directory locali come volumi nel containerMosquitto 2.0+ è in modalità solo locale per impostazione predefinita. Significa che accetta connessioni solo da localhost a meno che tu non lo configuri diversamente. Dovrai creare un file di configurazione per consentire connessioni esterne.
Usare Docker Compose
Docker Compose per Mosquitto semplifica molto la gestione dell'installazione, soprattutto quando esegui più servizi.
Crea un file
docker-compose.ymle incolla il seguente contenuto:Avvialo con:
Immagine 2 - Esecuzione di Mosquitto con Docker Compose
I mapping dei volumi funzionano come con il comando Docker, ma Compose gestisce la complessità. La configurazione delle porte copre tutti i protocolli MQTT comuni: MQTT standard (1883), MQTTS sicuro (8883) e connessioni WebSocket (9001).
Compose dà il meglio con setup multi-servizio. Per esempio, se esegui Home Assistant, Node-RED o altri strumenti IoT insieme a Mosquitto, puoi definire tutto in un unico file e avviare tutti i servizi insieme.
Ora approfondiamo la configurazione.
Trovi confusi i concetti Docker più avanzati? Il nostro corso Intermediate Docker va ben oltre le basi.
Configurare Mosquitto
Mosquitto non accetta connessioni esterne out of the box: serve un file di configurazione per abilitarle.
Configurazione di base (mosquitto.conf)
Crea un file
mosquitto.confnella directorymosquitto/confige aggiungi quanto segue:L'impostazione
allow_anonymous trueconsente ai client di connettersi senza credenziali. Va bene per sviluppo o reti interne, ma in produzione vorrai disabilitarla. Quando impostiallow_anonymous false, ogni client deve autenticarsi con username e password.Il listener WebSocket sulla porta 9001 abilita i client MQTT basati su browser. Le applicazioni web possono connettersi direttamente al broker usando librerie JavaScript come Paho MQTT.
Impostare l'autenticazione
L'autenticazione richiede la creazione di un file delle password e l'aggiornamento della configurazione.
Genera un file delle password all'interno del container:
Immagine 3 - Autenticazione Mosquitto
Questo crea un nuovo file delle password e ti chiede di inserirne una. Per utenti aggiuntivi, rimuovi il flag
-c:Ora aggiorna il tuo
mosquitto.confper forzare l'autenticazione:Il file delle password viene archiviato nel volume di configurazione montato, quindi persiste ai riavvii del container.
Abilitare TLS/SSL
La crittografia TLS protegge il traffico MQTT da intercettazioni e manomissioni.
Aggiungi queste righe al tuo
mosquitto.conf:Dovrai ottenere i certificati SSL per il tuo dominio. Let's Encrypt fornisce certificati gratuiti, oppure puoi usare reverse proxy come Caddy Server che gestiscono automaticamente la generazione dei certificati. Metti i file dei certificati nella directory
mosquitto/configin modo che siano disponibili nel container.Persistenza e logging
La persistenza salva su disco messaggi e sottoscrizioni, mentre un logging adeguato ti aiuta a diagnosticare problemi di connessione.
Puoi configurare la persistenza in
mosquitto.confcosì:Per quanto riguarda il logging, ecco come impostare un logging dettagliato:
Le opzioni
log_typeti permettono di filtrare cosa registrare:errorewarningper il monitoraggio in produzionenoticeeinformationper informazioni operative generalidebugper risolvere problemi di connessioneI volumi montati assicurano che sia i dati persistenti che i log sopravvivano ai riavvii del container. La directory dei dati archivia tutti i messaggi persistenti e le informazioni sulle sottoscrizioni, mentre la directory dei log mantiene le informazioni di debug accessibili dall'host.
I file di configurazione ti danno il pieno controllo del comportamento di Mosquitto senza dover ricostruire i container.
Test del setup
Il tuo broker non è utile finché non verifichi che i client possano connettersi e scambiarsi messaggi.
Usare mosquitto_pub e mosquitto_sub
Gli strumenti da riga di comando
mosquitto_pubemosquitto_subsono il modo più rapido per testare il broker.Inizia installando Mosquitto, a seconda della piattaforma:
sudo apt-get install mosquitto-clientsbrew install mosquittoIniziamo a testare senza autenticazione. Ti servono due finestre o tab del terminale. Esegui questi comandi in sessioni separate:
Nel tab di pubblicazione vedrai questo:
Immagine 4 - Pubblicazione di un messaggio
E nel tab di sottoscrizione vedrai immediatamente il messaggio:
Immagine 5 - Sottoscrizione a un topic Mosquitto
Se richiedi l'autenticazione, i comandi sono molto simili: ti basta passare username e password:
Se non vuoi installare i client Mosquitto in locale, eseguili all'interno del tuo container Docker:
Nel tab di pubblicazione vedrai questo:
Immagine 6 - Pubblicazione di un messaggio senza auth
E nel tab di sottoscrizione vedrai il messaggio:
Immagine 7 - Sottoscrizione a un topic Mosquitto senza auth
Test con client MQTT
I client con interfaccia grafica semplificano il test di scenari complessi e il monitoraggio del traffico dei messaggi in corso.
MQTT Explorer offre un'interfaccia pulita per esplorare i topic e inviare messaggi. Connettiti a
localhost:1883e vedrai una vista ad albero di tutti i topic attivi. È perfetto per il debug dei flussi di messaggi e per comprendere la struttura dei topic.Immagine 8 - App MQTT Explorer
MQTTX offre funzionalità più avanzate come scripting e invio massivo di messaggi. Entrambi i client supportano autenticazione, connessioni TLS e protocolli WebSocket.
Chi usa Home Assistant può testare l'integrazione MQTT direttamente dagli strumenti per sviluppatori. Aggiungi i dettagli del broker all'integrazione MQTT e usa l'interfaccia di publish/subscribe integrata.
Per test programmati, il client Paho MQTT per Python funziona bene:
Esegui questo script in un terminale, poi pubblica messaggi da un altro terminale o client GUI. Lo script stamperà qualsiasi messaggio ricevuto, confermando che il broker instrada correttamente il traffico.
Ecco cosa devi fare per pubblicare un messaggio:
Immagine 9 - Pubblicazione di un messaggio per l'esempio Python
E vedrai questo nella sessione del terminale in cui gira lo script Python:
Immagine 10 - Ricezione di un messaggio per l'esempio Python
Pubblicazione e sottoscrizione funzionanti significano che il tuo setup Mosquitto in Docker è pronto per applicazioni reali.
Integrazione di Mosquitto in Docker con Home Assistant
Eseguire Mosquitto insieme a Home Assistant in Docker crea un hub di messaggistica IoT completo senza problemi di configurazione di rete.
Docker Compose rende semplice tutto ciò. Entrambi i servizi possono comunicare tramite la rete interna di Docker senza esporre porte aggiuntive o gestire indirizzi IP.
Ecco un
docker-compose.ymlcompleto che esegue entrambi i servizi:La sezione
networkscrea una rete condivisa in cui entrambi i container possono raggiungersi per nome. Home Assistant può connettersi amosquitto:1883invece di usare localhost o indirizzi IP.Avvia entrambi i servizi con:
Poi configura l'integrazione MQTT tramite l'interfaccia web di Home Assistant. Vai su Impostazioni > Dispositivi e Servizi > Aggiungi Integrazione, quindi cerca "MQTT".
Inserisci questi dettagli di connessione:
mosquitto(il nome del container)1883Clicca Invia e Home Assistant testerà la connessione. Se va a buon fine, vedrai MQTT nella lista delle integrazioni.
Immagine 11 - Configurazione di Mosquitto con Homelab
Ora puoi aggiungere dispositivi MQTT, creare automazioni che pubblicano messaggi e monitorare i dati dei sensori tramite i topic. L'integrazione MQTT di Home Assistant gestisce automaticamente il discovery dei dispositivi compatibili.
Risoluzione dei problemi comuni
La maggior parte dei problemi con Mosquitto in Docker si riduce a permessi, porte o errori di configurazione che bloccano le connessioni.
Errori di permesso con volumi montati
Si verificano quando il container non può scrivere nelle directory dell'host. Nei log vedrai messaggi come "Permission denied" o "Cannot create directory".
Risolvi impostando la proprietà corretta sulle directory:
Il container Mosquitto gira come utente con ID 1883, quindi le directory dell'host devono corrispondere. Su alcuni sistemi potresti dover prima creare l'utente:
Conflitti di porta
Si verificano quando qualcos'altro usa la porta 1883. Controlla cosa sta girando su quella porta:
Se un altro servizio usa la porta, fermalo oppure mappa Mosquitto su un'altra porta:
La modalità solo locale impedisce le connessioni esterne
Questo accade anche se il container è in esecuzione. Dalla versione 2.0+, Mosquitto accetta per default connessioni solo da localhost a meno di configurazioni diverse.
Crea un
mosquitto.confdi base per consentire connessioni esterne:Metti questo file nella directory
mosquitto/confige riavvia il container.Directory vuote all'avvio
Significa che i volumi non sono montati correttamente. Verifica che i percorsi siano assoluti e che le directory esistano:
Crea le directory prima di avviare il container:
UID/GID in conflitto tra host e container
Causano problemi di permessi persistenti. Il container si aspetta di girare come utente 1883, ma il tuo host potrebbe avere esigenze diverse di ownership.
Forza l'esecuzione del container come il tuo utente:
Oppure adegua i permessi delle directory sull'host per soddisfare le aspettative del container. L'approccio del container è migliore in sviluppo, mentre correggere i permessi sull'host funziona meglio in produzione.
Controlla i log del container quando qualcosa non funziona: di solito ti dicono esattamente qual è il problema.
Avanzato: funzionalità di Mosquitto Pro Edition
La versione open source di Mosquitto copre la maggior parte dei casi d'uso, ma gli ambienti enterprise necessitano di funzionalità che solo la Pro Edition offre.
Gestione utenti basata sui ruoli ti consente di definire permessi granulari per diversi gruppi di utenti. Invece di gestire l'accesso dei singoli, crei ruoli come "sensor-readers", "actuator-controllers" o "admin-users" e assegni permessi ai ruoli. Gli utenti ereditano i permessi dei ruoli assegnati, semplificando la gestione degli accessi su centinaia o migliaia di dispositivi.
Puoi limitare l'accesso per pattern di topic, intervalli IP o finestre temporali. È molto meglio che configurare manualmente file ACL quando gestisci deployment IoT complessi con esigenze di sicurezza diverse.
Opzioni di autenticazione avanzate vanno oltre la semplice combinazione username/password. L'autenticazione tramite token JWT si integra con identity provider esistenti come Auth0, Okta o il sistema SSO della tua azienda. L'integrazione LDAP si collega direttamente ad Active Directory o ad altri servizi di directory enterprise.
Ispezione e monitoraggio approfonditi ti danno visibilità in tempo reale sui flussi di messaggi, i pattern di connessione e le prestazioni del broker. La Pro Edition include dashboard integrate che mostrano quali client consumano più banda, quali topic hanno i tassi di messaggi più alti e dove si stanno formando colli di bottiglia.
Ottieni metriche dettagliate su latenza dei messaggi, profondità delle code e pattern di comportamento dei client. Questi dati ti aiutano a ottimizzare le strutture dei topic e a individuare client problematici prima che impattino l'intero sistema.
Integrazioni con database e servizi cloud eliminano la necessità di applicazioni bridge personalizzate. La Pro Edition può inoltrare automaticamente i messaggi verso PostgreSQL, MongoDB, InfluxDB, AWS IoT Core, Azure IoT Hub o Google Cloud IoT. Definisci regole di instradamento che determinano dove vanno i messaggi in base ai pattern dei topic, al contenuto dei messaggi o ai metadati del client.
Code persistenti per scenari ad alto volume in cui la persistenza standard di Mosquitto non basta. La Pro Edition può bufferizzare milioni di messaggi per client offline e distribuire il carico su più istanze del broker. Include una gestione automatica delle code che previene l'esaurimento della memoria e mantiene le garanzie di ordinamento dei messaggi.
Il supporto al clustering ti consente di eseguire più istanze del broker che condividono il carico dei messaggi e forniscono protezione dal failover. Quando un broker va giù, i client si riconnettono automaticamente alle istanze sane senza perdere messaggi o sottoscrizioni.
La Pro Edition ha senso quando ti servono affidabilità e funzionalità di gestione di livello enterprise che richiederebbero mesi per essere costruite in proprio.
Pro e contro dell'uso di Mosquitto in Docker
Docker semplifica il deployment, ma non è la soluzione perfetta per ogni scenario.
Pro
mosquittosu un'altra macchina, esegui lo stesso comando Docker e sei di nuovo operativo. Spostarsi tra provider cloud o aggiornare l'hardware diventa un semplice trasferimento di file.Contro
Docker non è solo vantaggi.
Docker vince quando ti servono deployment coerenti e gestione semplice su ambienti diversi.
Conclusione
Eseguire Mosquitto in Docker ti dà un broker MQTT affidabile che funziona in modo coerente in tutti gli ambienti. Che tu stia prototipando dispositivi IoT, costruendo sistemi di domotica o collegando sensori in sviluppo, Docker elimina la complessità del setup e ti permette di concentrarti sul progetto vero e proprio.
Se prevedi di portare Mosquitto in produzione, ricorda questo:
mosquitto_passwd, configura la crittografia TLS con certificati adeguatiUn broker MQTT non protetto diventa una porta aperta per gli attaccanti per monitorare le comunicazioni dei dispositivi o iniettare comandi malevoli.
Per deployment enterprise che richiedono funzionalità avanzate come controllo degli accessi basato sui ruoli, clustering o integrazione LDAP, Mosquitto Pro Edition fornisce strumenti di gestione e scalabilità che vanno oltre la versione open source.
Pronto a migliorare le tue competenze su Docker e Kubernetes? Iscriviti al nostro Containerization and Virtualization with Docker and Kubernetes skill track per sviluppare competenze pertinenti e farti assumere.