Mosquitto in Docker betreiben (docker run & docker-compose)

Docker ist der schnellste Weg zu einem wegwerfbaren, reproduzierbaren MQTT-Broker. Das offizielle Image eclipse-mosquitto ist klein und gut gepflegt, aber seine Standardeinstellungen überraschen beim ersten Mal fast jeden: Ohne Konfigurationsdatei kannst du dich von außerhalb des Containers nicht verbinden. Diese Anleitung richtet Mosquitto in Docker richtig ein – mit persistenten Volumes, TCP- und WebSocket-Ports und Passwort-Authentifizierung.

1. Die Ordnerstruktur anlegen

Das Image erwartet drei Verzeichnisse unter /mosquitto. Spiegle sie auf dem Host:

mkdir -p mosquitto/config mosquitto/data mosquitto/log
touch mosquitto/config/mosquitto.conf

2. Eine minimale mosquitto.conf schreiben

Mosquitto 2.x lauscht nur auf localhost, wenn kein Listener konfiguriert ist – in einem Container heißt das, dass niemand ihn erreicht. Diese Konfiguration öffnet MQTT auf 1883 und WebSockets auf 9001:

# MQTT over TCP
listener 1883
# MQTT over WebSockets
listener 9001
protocol websockets

persistence true
persistence_location /mosquitto/data/

log_dest file /mosquitto/log/mosquitto.log
log_dest stdout

# For a first test only — switched to a password file in step 5
allow_anonymous true

Du willst TLS, ACLs oder Bridge-Einstellungen? Der mosquitto.conf-Generator baut dir aus einem Formular eine gültige Datei, und die Installationsanleitung erklärt den Local-only-Modus ausführlicher.

3. Mit docker run starten

docker run -d --name mosquitto \
  --restart unless-stopped \
  -p 1883:1883 -p 9001:9001 \
  -v "$PWD/mosquitto/config:/mosquitto/config" \
  -v "$PWD/mosquitto/data:/mosquitto/data" \
  -v "$PWD/mosquitto/log:/mosquitto/log" \
  eclipse-mosquitto:2

Wenn du das Major-Version-Tag festlegst (eclipse-mosquitto:2), vermeidest du überraschende Upgrades. Prüfe die Logs mit docker logs -f mosquitto; du solltest Opening ipv4 listen socket on port 1883 und eine WebSockets-Zeile für 9001 sehen.

4. Oder Docker Compose nutzen

Für alles über einen schnellen Test hinaus lässt sich eine Compose-Datei leichter versionieren:

services:
  mosquitto:
    image: eclipse-mosquitto:2
    container_name: mosquitto
    restart: unless-stopped
    ports:
      - "1883:1883"   # MQTT
      - "9001:9001"   # MQTT over WebSockets
    volumes:
      - ./mosquitto/config:/mosquitto/config
      - ./mosquitto/data:/mosquitto/data
      - ./mosquitto/log:/mosquitto/log

docker compose up -d
docker compose logs -f mosquitto

Andere Services im selben Compose-Projekt (Node-RED, Home Assistant, deine App) erreichen den Broker über den Servicenamen: mqtt://mosquitto:1883. Veröffentliche nur die Ports auf dem Host, die etwas außerhalb von Docker wirklich braucht.

5. Eine Passwortdatei per docker exec hinzufügen

Anonymer Zugriff ist für eine Minute Testen okay, aber nie für länger. Lege mit mosquitto_passwd, das im Image enthalten ist, einen Benutzer an:

# -c creates the file (overwrites it if it exists!) — use only for the first user
docker exec -it mosquitto mosquitto_passwd -c /mosquitto/config/passwd alice

# add more users without -c
docker exec -it mosquitto mosquitto_passwd /mosquitto/config/passwd bob

Stelle dann die Konfiguration von anonymem Zugriff auf Passwort-Authentifizierung um:

allow_anonymous false
password_file /mosquitto/config/passwd

docker restart mosquitto

ACLs und TLS funktionieren genauso – die Dateien kommen ins Config-Volume. Siehe Mosquitto mit Passwörtern, ACLs und TLS absichern.

6. Den Container testen

Vom Host aus (mit installierten Mosquitto-Clients):

mosquitto_sub -h localhost -p 1883 -u alice -P 'secret' -t 'demo/#' -v &
mosquitto_pub -h localhost -p 1883 -u alice -P 'secret' -t 'demo/hello' -m 'hi from docker'

Keine Clients auf dem Host? Nutze die im Container:

docker exec -it mosquitto mosquitto_sub -h localhost -u alice -P 'secret' -t 'demo/#' -v

Den WebSocket-Listener auf 9001 nutzen Browser-Clients (ws://<host>:9001). Denk daran, dass eine per HTTPS geladene Seite nur wss://-Verbindungen öffnen darf – um einen lokalen Broker aus einem gehosteten Web-Client zu testen, brauchst du also meist TLS vor Port 9001. Mehr dazu unter MQTT über WebSockets. Wie ein funktionierender Round Trip im Browser aussieht, siehst du zuerst mit einem öffentlichen Broker:

Im Online-MQTT-Client ausprobieren

Fehlerbehebung am Container

Für weitere CONNACK-Codes erklären die Referenz der MQTT-Reason-Codes und der Leitfaden zu Verbindungsfehlern, was dir der Broker mitteilen will.

Das Image aktualisieren

Weil Konfiguration, Daten und Logs auf dem Host liegen, besteht ein Upgrade nur darin, ein neueres Image zu ziehen und den Container neu zu erstellen. Retained Messages und persistente Sessions bleiben erhalten, solange das data-Volume bestehen bleibt:

docker compose pull mosquitto
docker compose up -d mosquitto
docker compose logs --tail 20 mosquitto

Mit reinem docker run ziehst du das Image, führst dann docker rm -f mosquitto aus und startest denselben docker run-Befehl erneut. Legst du diesen Befehl in ein kleines Shell-Skript (oder wechselst zu Compose), musst du die Volume-Flags nicht jedes Mal neu tippen.

Tipps für die Produktion

• Lege ein exaktes Image-Tag fest und aktualisiere bewusst; lies vor Major-Upgrades das Mosquitto-Changelog.
• Halte data auf einem Volume, sonst verschwinden Retained Messages und persistente Sessions, wenn der Container neu erstellt wird.
• Richte TLS auf 8883 (und auf dem WebSocket-Listener) ein, bevor du irgendetwas ins Internet stellst – die Konventionen findest du unter MQTT-Ports.
• Lies zum Debuggen docker logs mosquitto, statt mosquitto -v per docker exec zu starten – das startet einen zweiten Broker im Container und scheitert mit „address already in use“.

Häufig gestellte Fragen