Mosquitto Docker: Eclipse Mosquitto MQTT-broker instellen met Docker en Docker Compose
Stapsgewijze gids voor het uitrollen van een productieklare Mosquitto MQTT-broker met Docker-containers. Inclusief authenticatie, TLS-versleuteling, persistentieconfiguratie en integratie met Home Assistant.
Een MQTT-broker vanaf nul opzetten zou geen uren aan configuratie en troubleshooting mogen kosten.
Eclipse Mosquitto is een open-source MQTT-broker die de protocollen MQTT v5, 3.1.1 en 3.1 implementeert, waardoor het perfect is voor IoT-apparaten, domoticasystemen, cloudapplicaties en elke berichtgestuurde architectuur. Maar Mosquitto direct op je systeem installeren en configureren leidt vaak tot afhankelijkheidsconflicten, permissieproblemen en platformspecifieke kwesties die je ontwikkeltijd opslokken. Je bent meer tijd kwijt aan het gevecht met de setup dan aan het bouwen van je eigen applicatie.
Docker neemt deze hoofdpijn weg door een consistente, geïsoleerde omgeving te bieden voor het draaien van Mosquitto op elk platform. Je kunt binnen enkele minuten een volledig functionele MQTT-broker hebben, compleet met aangepaste configuraties, authenticatie en persistentie.
In deze gids laat ik je zien hoe je Eclipse Mosquitto uitrolt met Docker en Docker Compose, hoe je authenticatie en logging configureert, data-persistentie instelt en je broker test met echte MQTT-clients.
Ben je compleet nieuw met Docker? Ik raad je aan te beginnen met onze Introduction to Docker-cursus om de basis onder de knie te krijgen.
Wat is Mosquitto en waarom het in Docker gebruiken
Je hebt geen zwaar berichtensysteem nodig als je alleen snelle, betrouwbare communicatie tussen apparaten wilt.
MQTT is een lichtgewicht publish-subscribe-protocol, ontworpen voor situaties met beperkte bandbreedte en waar betrouwbaarheid telt. Denk aan IoT-sensoren, mobiele apps of elke situatie waarin apparaten snel kleine berichten moeten uitwisselen zonder constant te polleren.
Mosquitto fungeert als de tussenpersoon — de broker — tussen publishers en subscribers.
Publishers sturen berichten naar specifieke topics. Subscribers luisteren naar die topics. Mosquitto regelt de routering en zorgt dat berichten op de juiste plekken terechtkomen, zonder dat publishers en subscribers elkaar hoeven te kennen.
Dit is waarom Docker Mosquitto-setups nóg beter maakt:
Consistente setup op alle platforms: Windows, macOS of Linux — de Docker-container draait overal exact hetzelfde. Geen gezoek naar platformspecifieke installers of gedoe met afhankelijkheidsconflicten.
Eenvoudig versiebeheer: Je kunt specifieke Mosquitto-versies vastpinnen met image-tags, terugdraaien als er iets breekt en nieuwe versies testen zonder je hostsysteem aan te raken.
Echte portabiliteit: Dezelfde Docker Mosquitto-setup werkt in development, staging en productie. Je lokale omgeving komt overeen met wat er op je servers draait.
Mosquitto is er in twee smaken: de open-sourceversie (die de meeste use-cases dekt) en de commerciële Pro Edition van Cedalo met geavanceerde functies zoals clustering en verbeterde beveiliging. Voor de meeste projecten doet de open-sourceversie alles wat je nodig hebt.
Hierna behandel ik de vereisten en daarna duiken we in de installatie van Mosquitto.
Vereisten
Je hebt Docker op je systeem nodig voordat je Mosquitto kunt uitrollen.
Docker Desktop werkt het beste voor Windows- en macOS-gebruikers omdat het alles in één pakket bevat. Linux-gebruikers kunnen de Docker CLI rechtstreeks installeren via hun pakketbeheerder of uit de officiële repository van Docker.
Docker Compose is niet vereist, maar maakt het beheren van multi-container setups veel eenvoudiger. De meeste Docker Desktop-installaties bevatten Compose standaard. Op Linux moet je het mogelijk apart installeren.
Je hebt ook basisvaardigheden met de command line nodig. Niets ingewikkelds — alleen commando’s kunnen uitvoeren, door mappen navigeren en tekstbestanden bewerken.
Stapsgewijze setup
Mosquitto met Docker aan de praat krijgen kost drie stappen: mappen aanmaken, de container starten en optioneel Docker Compose instellen voor eenvoudiger beheer.
Vereiste mappen aanmaken
Mosquitto heeft een georganiseerde opslag nodig voor configuratie, data en logs.
Maak deze aan om te beginnen:
mkdir mosquitto-docker
cd mosquitto-docker
mkdir config data logsMogelijk gemaakt door
Dit geeft je overzichtelijke mappen voor de configuratiebestanden van Mosquitto, persistente data en loguitvoer.
Dit doet elke map:
/mosquitto/config slaat mosquitto.conf en eventuele extra configuratiebestanden op
/mosquitto/data bevat persistente berichtdata en abonnementsinformatie
/mosquitto/log bevat de logbestanden van Mosquitto voor debugging en monitoring
Deze mappen worden als volumes in de Docker-container gemount, zodat je instellingen en data behouden blijven bij container-herstarts.
Mosquitto draaien met Docker
Het basis-Docker-commando start Mosquitto met correcte poortkoppelingen en volumemounts.
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:latestMogelijk gemaakt door
Afbeelding 1 - Mosquitto draaien met Docker
Laat me die flags even toelichten:
-d draait de container op de achtergrond (detached mode)
--name mosquitto geeft de container een herkenbare naam
-p 1883:1883 koppelt poort 1883 op je host aan poort 1883 in de container
-v mount lokale mappen als volumes in de container
Mosquitto 2.0+ draait standaard in local-only-modus. Dat betekent dat alleen verbindingen vanaf localhost worden geaccepteerd, tenzij je het anders configureert. Je moet een configuratiebestand maken om externe verbindingen toe te staan.
Docker Compose gebruiken
Met Mosquitto Docker Compose wordt het beheer van de installatie veel eenvoudiger, zeker als je meerdere services draait.
Maak een docker-compose.yml-bestand en plak de volgende inhoud:
services:mosquitto:image: eclipse-mosquitto:latest
container_name: mosquitto
restart: unless-stopped
ports:-"1883:1883"# MQTT-"8883:8883"# MQTTS (secure)-"9001:9001"# WebSocketsvolumes:- ./mosquitto/config:/mosquitto/config
- ./mosquitto/data:/mosquitto/data
- ./mosquitto/log:/mosquitto/logMogelijk gemaakt door
Afbeelding 2 - Mosquitto draaien met Docker Compose
De volumekoppelingen werken hetzelfde als bij het Docker-commando, maar Compose handelt de complexiteit af. De poortconfiguratie dekt alle gangbare MQTT-protocollen: standaard MQTT (1883), beveiligde MQTTS (8883) en WebSocket-verbindingen (9001).
Compose komt echt tot zijn recht bij multi-service setups. Als je bijvoorbeeld Home Assistant, Node-RED of andere IoT-tools naast Mosquitto draait, kun je alles in één bestand definiëren en alle services samen starten.
Laten we nu dieper ingaan op de configuratie.
Vind je meer geavanceerde Docker-concepten verwarrend? Onze Intermediate Docker-cursus gaat verder dan de basis.
Mosquitto configureren
Mosquitto accepteert out-of-the-box geen externe verbindingen; je hebt een configuratiebestand nodig om dat mogelijk te maken.
Basisconfiguratie (mosquitto.conf)
Maak een mosquitto.conf-bestand in je mosquitto/config-map en voeg het volgende toe:
De instelling allow_anonymous true laat clients zonder inloggegevens verbinden. Dat is prima voor ontwikkeling of interne netwerken, maar in productie wil je dit uitschakelen. Wanneer je allow_anonymous false instelt, moet elke client zich authenticeren met een gebruikersnaam en wachtwoord.
De WebSocket-listener op poort 9001 maakt browsergebaseerde MQTT-clients mogelijk. Webapplicaties kunnen direct met je broker verbinden via JavaScript-bibliotheken zoals Paho MQTT.
Authenticatie instellen
Authenticatie vereist het aanmaken van een wachtwoordbestand en het bijwerken van je configuratie.
Genereer een wachtwoordbestand in de container:
dockerexec-it mosquitto mosquitto_passwd -c /mosquitto/config/passwd usernameMogelijk gemaakt door
Afbeelding 3 - Mosquitto-authenticatie
Dit maakt een nieuw wachtwoordbestand aan en vraagt je een wachtwoord in te voeren. Voor extra gebruikers laat je de -c-vlag weg:
dockerexec-it mosquitto mosquitto_passwd /mosquitto/config/passwd another_userMogelijk gemaakt door
Werk nu je mosquitto.conf bij om authenticatie te verplichten:
Je moet SSL-certificaten voor je domein verkrijgen. Let's Encrypt levert gratis certificaten, of je kunt reverse proxies zoals Caddy Server gebruiken die certificaatgeneratie automatisch afhandelen. Plaats je certificaatbestanden in de map mosquitto/config zodat ze in de container beschikbaar zijn.
Persistentie en logging
Persistentie slaat berichten en abonnementen op schijf op, terwijl goede logging helpt bij het debuggen van verbindingsproblemen.
Je kunt persistentie in mosquitto.conf zo configureren:
# 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 1dMogelijk gemaakt door
Voor logging kun je gedetailleerde logging zo instellen:
# 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 trueMogelijk gemaakt door
Met de opties log_type kun je filteren wat er gelogd wordt:
error en warning voor monitoring in productie
notice en information voor algemene operationele inzichten
debug voor het troubleshooten van verbindingsproblemen
Je volumemounts zorgen ervoor dat zowel persistente data als logs container-herstarts overleven. De datamap slaat alle persistente berichten en abonnementsinformatie op, terwijl de logmap je debuginformatie toegankelijk houdt vanaf het hostsysteem.
Configuratiebestanden geven je volledige controle over het gedrag van Mosquitto zonder containers te moeten herbouwen.
De setup testen
Je broker is pas nuttig als je verifieert dat clients kunnen verbinden en berichten kunnen uitwisselen.
Gebruik van mosquitto_pub en mosquitto_sub
De command-line tools mosquitto_pub en mosquitto_sub zijn de snelste manier om je broker te testen.
Begin met het installeren van Mosquitto, afhankelijk van je platform:
Linux (Ubuntu/Debian): sudo apt-get install mosquitto-clients
macOS:brew install mosquitto
Windows: Download van de officiële Eclipse Mosquitto-website of gebruik WSL
Laten we beginnen met testen zonder authenticatie. Je hebt twee terminalvensters of -tabs nodig. Voer deze commando’s in aparte sessies uit:
# 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"Mogelijk gemaakt door
In de publicerende tab zie je dit:
Afbeelding 4 - Een bericht publiceren
En in de subscribe-tab zie je het bericht direct verschijnen:
Afbeelding 5 - Abonneren op een Mosquitto-topic
Als authenticatie vereist is, zijn de commando’s vrijwel hetzelfde — je geeft alleen gebruikersnaam en wachtwoord mee:
# 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 passwordMogelijk gemaakt door
Wil je de Mosquitto-clients niet lokaal installeren, voer ze dan uit in je Docker-container:
# 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"Mogelijk gemaakt door
Dit zie je in de publicerende tab:
Afbeelding 6 - Een bericht publiceren zonder auth
En in de subscribe-tab zie je het bericht:
Afbeelding 7 - Abonneren op een Mosquitto-topic zonder auth
Testen met MQTT-clients
GUI-clients maken het makkelijker om complexe scenario’s te testen en lopend berichtenverkeer te monitoren.
MQTT Explorer biedt een overzichtelijke interface om topics te verkennen en berichten te versturen. Verbind met localhost:1883 en je ziet een boomweergave van alle actieve topics. Perfect om berichtstromen te debuggen en je topic-structuur te begrijpen.
Afbeelding 8 - MQTT Explorer-app
MQTTX biedt meer geavanceerde functies zoals scripting en bulkverzending. Beide clients ondersteunen authenticatie, TLS-verbindingen en WebSocket-protocollen.
Home Assistant-gebruikers kunnen de MQTT-integratie direct testen via de developer tools. Voeg je brokergegevens toe aan de MQTT-integratie en gebruik de ingebouwde publish/subscribe-interface.
Voor programmatische tests werkt de Paho MQTT Python-client goed:
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()Mogelijk gemaakt door
Voer dit script uit in één terminal en publiceer berichten vanuit een andere terminal of GUI-client. Het script print elk ontvangen bericht, wat bevestigt dat je broker het verkeer correct routeert.
Dit moet je doen om een bericht te publiceren:
Afbeelding 9 - Een bericht publiceren voor het Python-voorbeeld
En dit zie je in de terminalsessie waarin het Python-script draait:
Afbeelding 10 - Een bericht ontvangen voor het Python-voorbeeld
Werkende publish- en subscribe-acties betekenen dat je Mosquitto Docker-setup klaar is voor echte applicaties.
Mosquitto Docker integreren met Home Assistant
Mosquitto naast Home Assistant in Docker draaien creëert een complete IoT-berichtenhub zonder netwerkconfiguratiegedoe.
Docker Compose maakt dit eenvoudig. Beide services kunnen via het interne Docker-netwerk communiceren zonder extra poorten open te zetten of met IP-adressen te werken.
Hier is een complete docker-compose.yml die beide services draait:
De sectie networks creëert een gedeeld netwerk waar beide containers elkaar via naam kunnen bereiken. Home Assistant kan verbinden met mosquitto:1883 in plaats van localhost of IP-adressen te gebruiken.
Configureer vervolgens de MQTT-integratie via de webinterface van Home Assistant. Ga naar Instellingen > Apparaten & Services > Integratie toevoegen en zoek op "MQTT".
Voer deze verbindingsgegevens in:
Broker: mosquitto (de containernaam)
Poort: 1883
Gebruikersnaam/Wachtwoord: Je inloggegevens als authenticatie is ingeschakeld
Laat de overige instellingen op standaard
Klik op Submit en Home Assistant test de verbinding. Als het lukt, verschijnt MQTT in je integratielijst.
Afbeelding 11 - Mosquitto-configuratie met Homelab
Je kunt nu MQTT-apparaten toevoegen, automatiseringen maken die berichten publiceren en sensorgegevens via topics monitoren. De MQTT-integratie van Home Assistant verzorgt automatische apparaatherkenning voor compatibele devices.
Veelvoorkomende problemen oplossen
De meeste Docker Mosquitto-problemen draaien om permissies, poorten of configuratiefouten die verbindingen blokkeren.
Permissieproblemen met gemounte volumes
Deze treden op wanneer de container niet naar je hostmappen kan schrijven. In de logs zie je foutmeldingen zoals "Permission denied" of "Cannot create directory".
Los dit op door de juiste eigenaar in te stellen voor je mappen:
Deze zorgen voor aanhoudende permissieproblemen. De container verwacht te draaien als gebruiker 1883, maar je hostsysteem kan andere eigendomsvereisten hebben.
Forceer de container om als jouw gebruiker te draaien:
Of pas de permissies van je hostmappen aan zodat ze overeenkomen met de verwachtingen van de container. De container-aanpak werkt beter voor ontwikkeling, terwijl het fixen van hostpermissies beter werkt voor productie-uitrol.
Controleer de containerlogs als dingen niet werken — die vertellen meestal precies wat er mis is.
Geavanceerd: functies van Mosquitto Pro Edition
De open-source Mosquitto dekt de meeste use-cases, maar enterprise-omgevingen hebben functies nodig die alleen de Pro Edition biedt.
Rolgebaseerd gebruikersbeheer laat je fijne-grained permissies definiëren voor verschillende gebruikersgroepen. In plaats van individuele toegang te beheren, maak je rollen zoals "sensor-readers", "actuator-controllers" of "admin-users" en wijs je permissies toe aan hele rollen. Gebruikers erven de permissies van hun toegewezen rollen, wat beheer gemakkelijker maakt bij honderden of duizenden apparaten.
Je kunt toegang beperken op topic-patronen, IP-reeksen of tijdvensters. Dat is veel beter dan handmatig ACL-bestanden configureren bij complexe IoT-omgevingen met uiteenlopende beveiligingseisen.
Geavanceerde authenticatie-opties gaan verder dan simpele combinaties van gebruikersnaam/wachtwoord. JWT-tokenauthenticatie integreert met bestaande identity providers zoals Auth0, Okta of het SSO-systeem van je bedrijf. LDAP-integratie verbindt rechtstreeks met Active Directory of andere enterprise-directoryservices.
Diepe inspectie en monitoring geven je realtime-inzicht in berichtstromen, verbindingspatronen en brokerprestaties. De Pro Edition bevat ingebouwde dashboards die tonen welke clients het meeste bandbreedte verbruiken, welke topics de hoogste berichtfrequentie hebben en waar knelpunten ontstaan.
Je krijgt gedetailleerde metrics over berichtlatentie, queuedieptes en klantgedragspatronen. Deze data helpt je topics te optimaliseren en problematische clients te identificeren voordat ze het hele systeem beïnvloeden.
Integraties met databases en clouddiensten maken maatwerk bridge-applicaties overbodig. De Pro Edition kan berichten automatisch doorsturen naar PostgreSQL, MongoDB, InfluxDB, AWS IoT Core, Azure IoT Hub of Google Cloud IoT. Je definieert routeringsregels die bepalen welke berichten waarheen gaan op basis van topic-patronen, berichtinhoud of clientmetadata.
Persistente queues voor hoge volumes waarin de standaard Mosquitto-persistentie tekortschiet. De Pro Edition kan miljoenen berichten bufferen voor offline clients en de load verdelen over meerdere brokerinstanties. Het bevat automatische queue-beheer dat geheugenuitputting voorkomt en berichtvolgorde garandeert.
Clustering-ondersteuning laat je meerdere brokerinstanties draaien die de berichtenlast delen en failover-bescherming bieden. Als één broker uitvalt, verbinden clients automatisch opnieuw met gezonde instanties zonder berichten of abonnementen te verliezen.
De Pro Edition is logisch wanneer je enterprise-grade betrouwbaarheid en beheermogelijkheden nodig hebt die je anders maanden zouden kosten om zelf te bouwen.
Voor- en nadelen van Mosquitto in Docker
Docker maakt uitrol eenvoudiger, maar is niet in elke situatie de perfecte oplossing.
Voordelen
Cross-platform consistentie elimineert de hoofdpijn van OS-specifieke installaties. Hetzelfde Docker-commando werkt op Windows, macOS en Linux zonder gezoek naar verschillende pakketbeheerders of afhankelijkheidsconflicten. Je development-setup komt exact overeen met productie, wat minder verrassingen betekent bij het uitrollen.
Eenvoudige versie-upgrades door image-tags te wijzigen. In plaats van de oude versie te verwijderen en te hopen dat de upgrade je config niet breekt, trek je gewoon een nieuwe image en herstart je de container. Terugdraaien kost seconden als er iets misgaat.
Makkelijke back-up en migratie dankzij volumes voor je data. Kopieer de map mosquitto naar een andere machine, draai hetzelfde Docker-commando en je bent weer online. Verhuizen tussen cloudproviders of hardware upgraden wordt een simpele bestandsoverdracht.
Nadelen
Docker is niet alleen maar voordelen.
Problemen met volumerechten teisteren bepaalde besturingssystemen, vooral bij wisselen tussen Windows- en Linux-hosts. Je bent tijd kwijt aan eigendomsproblemen en UID/GID-mismatches die je bij een native installatie niet hebt.
Extra configuratie nodig voor productieklare beveiliging betekent dat Docker soms complexiteit toevoegt in plaats van wegneemt. Je moet netwerkpolicies, containerbeveiligingscontexten en volumecodering beheren bovenop de beveiligingsfuncties van Mosquitto. Native installaties laten je direct de bestaande beveiligingskaders van je OS gebruiken.
Mogelijke prestatie-impact in high-throughput-scenario’s waar elke microseconde telt. De containernetwerklaag en volumemounts voegen overhead toe die native installaties vermijden. Voor de meeste IoT-applicaties is dit verschil verwaarloosbaar, maar realtime industriële systemen kunnen de latentie merken.
Docker wint wanneer je consistente deployments en eenvoudig beheer over verschillende omgevingen nodig hebt.
Conclusie
Mosquitto in Docker draaien geeft je een betrouwbare MQTT-broker die consistent werkt in alle omgevingen. Of je nu IoT-apparaten prototypet, domoticasystemen bouwt of sensoren in development koppelt: Docker haalt de set-upcomplexiteit weg en laat je focussen op je echte project.
Als je Mosquitto naar productie brengt, onthoud dan het volgende:
Beveilig je broker voordat je die op internet blootstelt
Schakel authenticatie in met mosquitto_passwd, configureer TLS-versleuteling met geldige certificaten
Beperk toegang tot alleen de clients die het nodig hebben
Een onbeveiligde MQTT-broker is een open deur voor aanvallers om apparaatcommunicatie te monitoren of kwaadaardige commando’s in te spuiten.
Voor enterprise-deployments die geavanceerde functies nodig hebben zoals rolgebaseerde toegangscontrole, clustering of LDAP-integratie, biedt Mosquitto Pro Edition de beheertools en schaalbaarheid die verder gaan dan de open-sourceversie.
Wat is het verschil tussen Mosquitto native draaien en in Docker?⌄
Docker biedt cross-platform consistentie en elimineert afhankelijkheidsconflicten die native installaties teisteren. Je Mosquitto-setup werkt identiek op Windows, macOS en Linux zonder dat je platformspecifieke pakketten hoeft op te sporen. Docker maakt ook versie-upgrades en rollbacks eenvoudig — pas gewoon de image-tag aan en herstart de container. Native installaties kunnen echter iets betere prestaties leveren in high-throughput-situaties.
Heb ik Docker Compose nodig om Mosquitto te draaien, of kan ik reguliere Docker-commando’s gebruiken?⌄
Je kunt Mosquitto absoluut draaien met reguliere Docker-commando’s via docker run. Docker Compose maakt het beheer gewoon makkelijker, zeker als je meerdere services zoals Home Assistant of Node-RED naast Mosquitto draait. Als je alleen Mosquitto draait, volstaat een eenvoudig docker run-commando prima.
Is Mosquitto in Docker veilig genoeg voor productiegebruik?⌄
Mosquitto in Docker kan productie-klaar zijn met de juiste configuratie. Je moet anonieme toegang uitschakelen, authenticatie instellen met mosquitto_passwd, TLS-versleuteling configureren en netwerktoegang beperken tot alleen vertrouwde clients. De container zelf voegt geen beveiligingslekken toe, maar jij bent verantwoordelijk voor de beveiliging van zowel Mosquitto’s configuratie als de Docker-omgeving.
Waarom start mijn Mosquitto-container wel, maar weigert die externe verbindingen?⌄
Mosquitto 2.0+ staat standaard op local-only-modus, die alleen verbindingen vanaf localhost binnen de container accepteert. Je moet een mosquitto.conf-bestand maken met listener 1883 en allow_anonymous true (voor testen) of de juiste authenticatie-instellingen. Plaats dit configbestand in je gemounte /mosquitto/config-map en herstart de container.
Hoe los ik "Permission denied"-fouten op wanneer Mosquitto naar gemounte volumes probeert te schrijven?⌄
De Mosquitto-container draait als user ID 1883, maar je hostmappen hebben mogelijk andere eigenaars. Voer sudo chown -R 1883:1883 mosquitto/ uit om het eigendom te corrigeren, of maak eerst de mosquitto-gebruiker aan met sudo useradd -u 1883 mosquitto en wijzig daarna het eigendom. Op sommige systemen kun je de container ook draaien met --user $(id -u):$(id -g) om te matchen met je hostgebruiker.
Senior Data Scientist, gevestigd in Kroatië. Top Tech-schrijver met meer dan 700 gepubliceerde artikelen en meer dan 10 miljoen weergaven. Auteur van het boek Machine Learning Automation with TPOT.
Een MQTT-broker vanaf nul opzetten zou geen uren aan configuratie en troubleshooting mogen kosten.
Eclipse Mosquitto is een open-source MQTT-broker die de protocollen MQTT v5, 3.1.1 en 3.1 implementeert, waardoor het perfect is voor IoT-apparaten, domoticasystemen, cloudapplicaties en elke berichtgestuurde architectuur. Maar Mosquitto direct op je systeem installeren en configureren leidt vaak tot afhankelijkheidsconflicten, permissieproblemen en platformspecifieke kwesties die je ontwikkeltijd opslokken. Je bent meer tijd kwijt aan het gevecht met de setup dan aan het bouwen van je eigen applicatie.
Docker neemt deze hoofdpijn weg door een consistente, geïsoleerde omgeving te bieden voor het draaien van Mosquitto op elk platform. Je kunt binnen enkele minuten een volledig functionele MQTT-broker hebben, compleet met aangepaste configuraties, authenticatie en persistentie.
In deze gids laat ik je zien hoe je Eclipse Mosquitto uitrolt met Docker en Docker Compose, hoe je authenticatie en logging configureert, data-persistentie instelt en je broker test met echte MQTT-clients.
Ben je compleet nieuw met Docker? Ik raad je aan te beginnen met onze Introduction to Docker-cursus om de basis onder de knie te krijgen.
Wat is Mosquitto en waarom het in Docker gebruiken
Je hebt geen zwaar berichtensysteem nodig als je alleen snelle, betrouwbare communicatie tussen apparaten wilt.
MQTT is een lichtgewicht publish-subscribe-protocol, ontworpen voor situaties met beperkte bandbreedte en waar betrouwbaarheid telt. Denk aan IoT-sensoren, mobiele apps of elke situatie waarin apparaten snel kleine berichten moeten uitwisselen zonder constant te polleren.
Mosquitto fungeert als de tussenpersoon — de broker — tussen publishers en subscribers.
Publishers sturen berichten naar specifieke topics. Subscribers luisteren naar die topics. Mosquitto regelt de routering en zorgt dat berichten op de juiste plekken terechtkomen, zonder dat publishers en subscribers elkaar hoeven te kennen.
Dit is waarom Docker Mosquitto-setups nóg beter maakt:
Mosquitto is er in twee smaken: de open-sourceversie (die de meeste use-cases dekt) en de commerciële Pro Edition van Cedalo met geavanceerde functies zoals clustering en verbeterde beveiliging. Voor de meeste projecten doet de open-sourceversie alles wat je nodig hebt.
Hierna behandel ik de vereisten en daarna duiken we in de installatie van Mosquitto.
Vereisten
Je hebt Docker op je systeem nodig voordat je Mosquitto kunt uitrollen.
Docker Desktop werkt het beste voor Windows- en macOS-gebruikers omdat het alles in één pakket bevat. Linux-gebruikers kunnen de Docker CLI rechtstreeks installeren via hun pakketbeheerder of uit de officiële repository van Docker.
Docker Compose is niet vereist, maar maakt het beheren van multi-container setups veel eenvoudiger. De meeste Docker Desktop-installaties bevatten Compose standaard. Op Linux moet je het mogelijk apart installeren.
Je hebt ook basisvaardigheden met de command line nodig. Niets ingewikkelds — alleen commando’s kunnen uitvoeren, door mappen navigeren en tekstbestanden bewerken.
Stapsgewijze setup
Mosquitto met Docker aan de praat krijgen kost drie stappen: mappen aanmaken, de container starten en optioneel Docker Compose instellen voor eenvoudiger beheer.
Vereiste mappen aanmaken
Mosquitto heeft een georganiseerde opslag nodig voor configuratie, data en logs.
Maak deze aan om te beginnen:
Dit geeft je overzichtelijke mappen voor de configuratiebestanden van Mosquitto, persistente data en loguitvoer.
Dit doet elke map:
/mosquitto/configslaatmosquitto.confen eventuele extra configuratiebestanden op/mosquitto/databevat persistente berichtdata en abonnementsinformatie/mosquitto/logbevat de logbestanden van Mosquitto voor debugging en monitoringDeze mappen worden als volumes in de Docker-container gemount, zodat je instellingen en data behouden blijven bij container-herstarts.
Mosquitto draaien met Docker
Het basis-Docker-commando start Mosquitto met correcte poortkoppelingen en volumemounts.
Afbeelding 1 - Mosquitto draaien met Docker
Laat me die flags even toelichten:
-ddraait de container op de achtergrond (detached mode)--name mosquittogeeft de container een herkenbare naam-p 1883:1883koppelt poort 1883 op je host aan poort 1883 in de container-vmount lokale mappen als volumes in de containerMosquitto 2.0+ draait standaard in local-only-modus. Dat betekent dat alleen verbindingen vanaf localhost worden geaccepteerd, tenzij je het anders configureert. Je moet een configuratiebestand maken om externe verbindingen toe te staan.
Docker Compose gebruiken
Met Mosquitto Docker Compose wordt het beheer van de installatie veel eenvoudiger, zeker als je meerdere services draait.
Maak een
docker-compose.yml-bestand en plak de volgende inhoud:Start het met:
Afbeelding 2 - Mosquitto draaien met Docker Compose
De volumekoppelingen werken hetzelfde als bij het Docker-commando, maar Compose handelt de complexiteit af. De poortconfiguratie dekt alle gangbare MQTT-protocollen: standaard MQTT (1883), beveiligde MQTTS (8883) en WebSocket-verbindingen (9001).
Compose komt echt tot zijn recht bij multi-service setups. Als je bijvoorbeeld Home Assistant, Node-RED of andere IoT-tools naast Mosquitto draait, kun je alles in één bestand definiëren en alle services samen starten.
Laten we nu dieper ingaan op de configuratie.
Vind je meer geavanceerde Docker-concepten verwarrend? Onze Intermediate Docker-cursus gaat verder dan de basis.
Mosquitto configureren
Mosquitto accepteert out-of-the-box geen externe verbindingen; je hebt een configuratiebestand nodig om dat mogelijk te maken.
Basisconfiguratie (mosquitto.conf)
Maak een
mosquitto.conf-bestand in jemosquitto/config-map en voeg het volgende toe:De instelling
allow_anonymous truelaat clients zonder inloggegevens verbinden. Dat is prima voor ontwikkeling of interne netwerken, maar in productie wil je dit uitschakelen. Wanneer jeallow_anonymous falseinstelt, moet elke client zich authenticeren met een gebruikersnaam en wachtwoord.De WebSocket-listener op poort 9001 maakt browsergebaseerde MQTT-clients mogelijk. Webapplicaties kunnen direct met je broker verbinden via JavaScript-bibliotheken zoals Paho MQTT.
Authenticatie instellen
Authenticatie vereist het aanmaken van een wachtwoordbestand en het bijwerken van je configuratie.
Genereer een wachtwoordbestand in de container:
Afbeelding 3 - Mosquitto-authenticatie
Dit maakt een nieuw wachtwoordbestand aan en vraagt je een wachtwoord in te voeren. Voor extra gebruikers laat je de
-c-vlag weg:Werk nu je
mosquitto.confbij om authenticatie te verplichten:Het wachtwoordbestand wordt opgeslagen in je gemounte config-volume, dus het blijft behouden bij container-herstarts.
TLS/SSL inschakelen
TLS-versleuteling beschermt je MQTT-verkeer tegen afluisteren en manipulatie.
Voeg deze regels toe aan je
mosquitto.conf:Je moet SSL-certificaten voor je domein verkrijgen. Let's Encrypt levert gratis certificaten, of je kunt reverse proxies zoals Caddy Server gebruiken die certificaatgeneratie automatisch afhandelen. Plaats je certificaatbestanden in de map
mosquitto/configzodat ze in de container beschikbaar zijn.Persistentie en logging
Persistentie slaat berichten en abonnementen op schijf op, terwijl goede logging helpt bij het debuggen van verbindingsproblemen.
Je kunt persistentie in
mosquitto.confzo configureren:Voor logging kun je gedetailleerde logging zo instellen:
Met de opties
log_typekun je filteren wat er gelogd wordt:errorenwarningvoor monitoring in productienoticeeninformationvoor algemene operationele inzichtendebugvoor het troubleshooten van verbindingsproblemenJe volumemounts zorgen ervoor dat zowel persistente data als logs container-herstarts overleven. De datamap slaat alle persistente berichten en abonnementsinformatie op, terwijl de logmap je debuginformatie toegankelijk houdt vanaf het hostsysteem.
Configuratiebestanden geven je volledige controle over het gedrag van Mosquitto zonder containers te moeten herbouwen.
De setup testen
Je broker is pas nuttig als je verifieert dat clients kunnen verbinden en berichten kunnen uitwisselen.
Gebruik van mosquitto_pub en mosquitto_sub
De command-line tools
mosquitto_pubenmosquitto_subzijn de snelste manier om je broker te testen.Begin met het installeren van Mosquitto, afhankelijk van je platform:
sudo apt-get install mosquitto-clientsbrew install mosquittoLaten we beginnen met testen zonder authenticatie. Je hebt twee terminalvensters of -tabs nodig. Voer deze commando’s in aparte sessies uit:
In de publicerende tab zie je dit:
Afbeelding 4 - Een bericht publiceren
En in de subscribe-tab zie je het bericht direct verschijnen:
Afbeelding 5 - Abonneren op een Mosquitto-topic
Als authenticatie vereist is, zijn de commando’s vrijwel hetzelfde — je geeft alleen gebruikersnaam en wachtwoord mee:
Wil je de Mosquitto-clients niet lokaal installeren, voer ze dan uit in je Docker-container:
Dit zie je in de publicerende tab:
Afbeelding 6 - Een bericht publiceren zonder auth
En in de subscribe-tab zie je het bericht:
Afbeelding 7 - Abonneren op een Mosquitto-topic zonder auth
Testen met MQTT-clients
GUI-clients maken het makkelijker om complexe scenario’s te testen en lopend berichtenverkeer te monitoren.
MQTT Explorer biedt een overzichtelijke interface om topics te verkennen en berichten te versturen. Verbind met
localhost:1883en je ziet een boomweergave van alle actieve topics. Perfect om berichtstromen te debuggen en je topic-structuur te begrijpen.Afbeelding 8 - MQTT Explorer-app
MQTTX biedt meer geavanceerde functies zoals scripting en bulkverzending. Beide clients ondersteunen authenticatie, TLS-verbindingen en WebSocket-protocollen.
Home Assistant-gebruikers kunnen de MQTT-integratie direct testen via de developer tools. Voeg je brokergegevens toe aan de MQTT-integratie en gebruik de ingebouwde publish/subscribe-interface.
Voor programmatische tests werkt de Paho MQTT Python-client goed:
Voer dit script uit in één terminal en publiceer berichten vanuit een andere terminal of GUI-client. Het script print elk ontvangen bericht, wat bevestigt dat je broker het verkeer correct routeert.
Dit moet je doen om een bericht te publiceren:
Afbeelding 9 - Een bericht publiceren voor het Python-voorbeeld
En dit zie je in de terminalsessie waarin het Python-script draait:
Afbeelding 10 - Een bericht ontvangen voor het Python-voorbeeld
Werkende publish- en subscribe-acties betekenen dat je Mosquitto Docker-setup klaar is voor echte applicaties.
Mosquitto Docker integreren met Home Assistant
Mosquitto naast Home Assistant in Docker draaien creëert een complete IoT-berichtenhub zonder netwerkconfiguratiegedoe.
Docker Compose maakt dit eenvoudig. Beide services kunnen via het interne Docker-netwerk communiceren zonder extra poorten open te zetten of met IP-adressen te werken.
Hier is een complete
docker-compose.ymldie beide services draait:De sectie
networkscreëert een gedeeld netwerk waar beide containers elkaar via naam kunnen bereiken. Home Assistant kan verbinden metmosquitto:1883in plaats van localhost of IP-adressen te gebruiken.Start beide services met:
Configureer vervolgens de MQTT-integratie via de webinterface van Home Assistant. Ga naar Instellingen > Apparaten & Services > Integratie toevoegen en zoek op "MQTT".
Voer deze verbindingsgegevens in:
mosquitto(de containernaam)1883Klik op Submit en Home Assistant test de verbinding. Als het lukt, verschijnt MQTT in je integratielijst.
Afbeelding 11 - Mosquitto-configuratie met Homelab
Je kunt nu MQTT-apparaten toevoegen, automatiseringen maken die berichten publiceren en sensorgegevens via topics monitoren. De MQTT-integratie van Home Assistant verzorgt automatische apparaatherkenning voor compatibele devices.
Veelvoorkomende problemen oplossen
De meeste Docker Mosquitto-problemen draaien om permissies, poorten of configuratiefouten die verbindingen blokkeren.
Permissieproblemen met gemounte volumes
Deze treden op wanneer de container niet naar je hostmappen kan schrijven. In de logs zie je foutmeldingen zoals "Permission denied" of "Cannot create directory".
Los dit op door de juiste eigenaar in te stellen voor je mappen:
De Mosquitto-container draait als user ID 1883, dus je hostmappen moeten overeenkomen. Op sommige systemen moet je eerst de gebruiker aanmaken:
Poortconflicten
Die ontstaan als iets anders poort 1883 gebruikt. Controleer wat er op die poort draait:
Als een andere service de poort gebruikt, stop die dan of koppel Mosquitto aan een andere poort:
Local-only-modus voorkomt externe verbindingen
Dit gebeurt zelfs als je container draait. Mosquitto 2.0+ accepteert standaard alleen verbindingen vanaf localhost, tenzij je het anders instelt.
Maak een eenvoudige
mosquitto.confaan om externe verbindingen toe te staan:Plaats dit bestand in je
mosquitto/config-map en herstart de container.Lege mappen bij opstarten
Dit betekent dat je volumemounts niet goed werken. Controleer of je paden absoluut zijn en of de mappen bestaan:
Maak de mappen aan vóór het starten van de container:
Conflicterende UIDs/GIDs tussen host en container
Deze zorgen voor aanhoudende permissieproblemen. De container verwacht te draaien als gebruiker 1883, maar je hostsysteem kan andere eigendomsvereisten hebben.
Forceer de container om als jouw gebruiker te draaien:
Of pas de permissies van je hostmappen aan zodat ze overeenkomen met de verwachtingen van de container. De container-aanpak werkt beter voor ontwikkeling, terwijl het fixen van hostpermissies beter werkt voor productie-uitrol.
Controleer de containerlogs als dingen niet werken — die vertellen meestal precies wat er mis is.
Geavanceerd: functies van Mosquitto Pro Edition
De open-source Mosquitto dekt de meeste use-cases, maar enterprise-omgevingen hebben functies nodig die alleen de Pro Edition biedt.
Rolgebaseerd gebruikersbeheer laat je fijne-grained permissies definiëren voor verschillende gebruikersgroepen. In plaats van individuele toegang te beheren, maak je rollen zoals "sensor-readers", "actuator-controllers" of "admin-users" en wijs je permissies toe aan hele rollen. Gebruikers erven de permissies van hun toegewezen rollen, wat beheer gemakkelijker maakt bij honderden of duizenden apparaten.
Je kunt toegang beperken op topic-patronen, IP-reeksen of tijdvensters. Dat is veel beter dan handmatig ACL-bestanden configureren bij complexe IoT-omgevingen met uiteenlopende beveiligingseisen.
Geavanceerde authenticatie-opties gaan verder dan simpele combinaties van gebruikersnaam/wachtwoord. JWT-tokenauthenticatie integreert met bestaande identity providers zoals Auth0, Okta of het SSO-systeem van je bedrijf. LDAP-integratie verbindt rechtstreeks met Active Directory of andere enterprise-directoryservices.
Diepe inspectie en monitoring geven je realtime-inzicht in berichtstromen, verbindingspatronen en brokerprestaties. De Pro Edition bevat ingebouwde dashboards die tonen welke clients het meeste bandbreedte verbruiken, welke topics de hoogste berichtfrequentie hebben en waar knelpunten ontstaan.
Je krijgt gedetailleerde metrics over berichtlatentie, queuedieptes en klantgedragspatronen. Deze data helpt je topics te optimaliseren en problematische clients te identificeren voordat ze het hele systeem beïnvloeden.
Integraties met databases en clouddiensten maken maatwerk bridge-applicaties overbodig. De Pro Edition kan berichten automatisch doorsturen naar PostgreSQL, MongoDB, InfluxDB, AWS IoT Core, Azure IoT Hub of Google Cloud IoT. Je definieert routeringsregels die bepalen welke berichten waarheen gaan op basis van topic-patronen, berichtinhoud of clientmetadata.
Persistente queues voor hoge volumes waarin de standaard Mosquitto-persistentie tekortschiet. De Pro Edition kan miljoenen berichten bufferen voor offline clients en de load verdelen over meerdere brokerinstanties. Het bevat automatische queue-beheer dat geheugenuitputting voorkomt en berichtvolgorde garandeert.
Clustering-ondersteuning laat je meerdere brokerinstanties draaien die de berichtenlast delen en failover-bescherming bieden. Als één broker uitvalt, verbinden clients automatisch opnieuw met gezonde instanties zonder berichten of abonnementen te verliezen.
De Pro Edition is logisch wanneer je enterprise-grade betrouwbaarheid en beheermogelijkheden nodig hebt die je anders maanden zouden kosten om zelf te bouwen.
Voor- en nadelen van Mosquitto in Docker
Docker maakt uitrol eenvoudiger, maar is niet in elke situatie de perfecte oplossing.
Voordelen
mosquittonaar een andere machine, draai hetzelfde Docker-commando en je bent weer online. Verhuizen tussen cloudproviders of hardware upgraden wordt een simpele bestandsoverdracht.Nadelen
Docker is niet alleen maar voordelen.
Docker wint wanneer je consistente deployments en eenvoudig beheer over verschillende omgevingen nodig hebt.
Conclusie
Mosquitto in Docker draaien geeft je een betrouwbare MQTT-broker die consistent werkt in alle omgevingen. Of je nu IoT-apparaten prototypet, domoticasystemen bouwt of sensoren in development koppelt: Docker haalt de set-upcomplexiteit weg en laat je focussen op je echte project.
Als je Mosquitto naar productie brengt, onthoud dan het volgende:
mosquitto_passwd, configureer TLS-versleuteling met geldige certificatenEen onbeveiligde MQTT-broker is een open deur voor aanvallers om apparaatcommunicatie te monitoren of kwaadaardige commando’s in te spuiten.
Voor enterprise-deployments die geavanceerde functies nodig hebben zoals rolgebaseerde toegangscontrole, clustering of LDAP-integratie, biedt Mosquitto Pro Edition de beheertools en schaalbaarheid die verder gaan dan de open-sourceversie.
Klaar om je Docker- en Kubernetes-skills te boosten? Schrijf je in voor ons Containerization and Virtualization with Docker and Kubernetes skill track om relevante skills op te bouwen en je kansen op de arbeidsmarkt te vergroten.