MQTT Server Setup mit Mosquitto & Web Dashboard

Komplettes MQTT Setup mit Eclipse Mosquitto Broker und MQTTUI Web Dashboard.

Features

✅ Mosquitto MQTT Broker

• MQTT auf Port 1883
• WebSocket auf Port 9001
• Passwort-Authentifizierung
• ACL (Access Control Lists)
• Öffentliches Topic ohne Anmeldung (public/*)
• Persistenz aktiviert

✅ Web Dashboard (MQTTUI)

• Web-basiertes MQTT Dashboard
• Nachrichtenverlauf mit SQLite Datenbank
• Echtzeit-Updates
• Läuft auf Port 5000

Verzeichnisstruktur

mqtt/
├── config/                     # Konfigurationsdateien
│   ├── mosquitto.conf          # Mosquitto Hauptkonfiguration
│   ├── acl.conf                # Access Control Lists
│   └── passwords.txt           # User/Passwort Datei (wird generiert)
├── data/                       # Mosquitto Persistenz Daten
├── log/                        # Mosquitto Log-Dateien
├── mqttui-data/                # MQTTUI Datenbank
├── docker-compose.yml          # Docker Setup
├── .env                        # Umgebungsvariablen (NICHT committen!)
├── .env.example                # Beispiel für Umgebungsvariablen
├── mqtt-panel-config.json      # Legacy Dashboard Konfiguration
├── n8n-mqtt.json               # n8n Workflow für MQTT-Integration
├── setup.sh                    # Setup-Script für User
├── test-mqtt.sh                # Test-Script für MQTT Nachrichten
├── CLAUDE.md                   # Projekt-Dokumentation für Claude Code
└── README.md                   # Diese Datei

Quick Start

1. Umgebungsvariablen konfigurieren

# .env.example als Vorlage kopieren
cp .env.example .env

# .env editieren und sichere Passwörter setzen
nano .env

⚠️ WICHTIG: Setze sichere Passwörter in der .env Datei!

2. Server starten

# Container starten
docker compose up -d

# Logs anschauen
docker compose logs -f

3. Benutzer erstellen

# Setup-Script ausführbar machen
chmod +x setup.sh

# Alle User aus .env erstellen
./setup.sh

Das Script erstellt folgende User (Credentials aus .env):

• admin - Vollzugriff
• panel - Für Web Dashboard
• testuser - Normaler User
• device1 - IoT Device 1
• device2 - IoT Device 2
• monitor - Read-Only

Einzelnen User über CLI erstellen:

# Syntax: ./setup.sh create <username> <password>
./setup.sh create myuser secret123

⚠️ WICHTIG: Nach dem Erstellen eines neuen Users musst du:

1. Die ACL-Regeln in config/acl.conf für den neuen User anpassen
2. Mosquitto neu starten: docker compose restart mosquitto

Ohne ACL-Eintrag hat der neue User keine Zugriffsrechte!

4. Dashboard öffnen

Web Dashboard: http://localhost:5000

Zugriff

MQTT Endpoints

• MQTT: localhost:1883
• WebSocket: ws://localhost:9001
• Web Dashboard: http://localhost:5000

Öffentliches Topic (ohne Anmeldung)

Topic: public/*

Beispiel mit mosquitto_pub:

# Nachricht an öffentliches Topic senden (KEINE Authentifizierung)
docker exec mosquitto mosquitto_pub -h localhost -t "public/test" -m "Hallo Welt!"

# Öffentliches Topic abhören
docker exec mosquitto mosquitto_sub -h localhost -t "public/#" -v

Mit Authentifizierung

Beispiel mit Admin User:

# Mit Authentifizierung publishen (Credentials aus .env verwenden)
docker exec mosquitto mosquitto_pub -h localhost -t "devices/device1/status" -m "online" -u admin -P <ADMIN_PASSWORD>

# Mit Authentifizierung subscriben (Credentials aus .env verwenden)
docker exec mosquitto mosquitto_sub -h localhost -t "#" -v -u admin -P <ADMIN_PASSWORD>

💡 Hinweis: Ersetze <ADMIN_PASSWORD> mit dem Passwort aus deiner .env Datei.

Benutzerverwaltung

Neuen User hinzufügen

Empfohlen - Via Setup-Script:

# Einzelnen User erstellen
./setup.sh create username password123

⚠️ Danach ACL anpassen: Bearbeite config/acl.conf und füge Regeln für den neuen User hinzu, dann:

docker compose restart mosquitto

Alternativ - Manuell:

# User hinzufügen/ändern
docker exec -it mosquitto mosquitto_passwd -b /mosquitto/config/passwords.txt USERNAME PASSWORD

# ACL in config/acl.conf anpassen und Container neu starten
docker compose restart mosquitto

User löschen

docker exec -it mosquitto mosquitto_passwd -D /mosquitto/config/passwords.txt USERNAME

# Container neu starten
docker compose restart mosquitto

ACL Konfiguration (acl.conf)

Die ACL definiert, wer auf welche Topics zugreifen darf:

Anonymous User (ohne Anmeldung)

user anonymous
topic read public/#
topic write public/#

Admin (alles erlaubt)

user admin
topic readwrite #

Device (nur eigene Topics)

user device1
topic write devices/device1/#
topic read devices/device1/status
topic read public/#

Nach ACL-Änderungen Container neu starten:

docker compose restart mosquitto

Dashboard

Das MQTTUI Dashboard zeigt alle MQTT Nachrichten in Echtzeit an und speichert sie in einer SQLite Datenbank.

Dashboard Konfiguration

Die Dashboard-Einstellungen werden über Umgebungsvariablen in der .env Datei konfiguriert:

• MQTT_PANEL_USERNAME: Benutzername für den Broker-Zugriff
• MQTT_PANEL_PASSWORD: Passwort für den Broker-Zugriff
• SECRET_KEY: Session-Key für die Web-Oberfläche

Nach Änderungen Container neu starten:

docker compose restart mqttui

n8n Integration

Das Repository enthält einen vorgefertigten n8n Workflow (n8n-mqtt.json), der automatisch MQTT-Nachrichten an den Broker sendet.

Was ist n8n?

n8n ist ein Workflow-Automatisierungstool, ähnlich wie Zapier oder Node-RED, mit dem sich verschiedene Dienste und APIs miteinander verbinden lassen.

Workflow-Funktionen

Der bereitgestellte Workflow sendet automatisch das aktuelle Datum und die Uhrzeit an das Topic devices/device1/now:

• Manueller Trigger: Workflow manuell per Button ausführen
• Schedule Trigger: Automatische Ausführung jede Minute
• MQTT Node: Sendet Timestamp im Format "dd.MM.yyyy - HH:mm:ss"

Workflow importieren

1. n8n installieren und starten (siehe n8n Dokumentation)
2. In n8n: Workflows → Import → From File
3. Die Datei n8n-mqtt.json auswählen
4. MQTT Credentials konfigurieren:
   • Host: localhost (oder deine Server-IP)
   • Port: 1883
   • Username: z.B. device1 (aus deiner .env)
   • Password: entsprechendes Passwort aus .env
5. Workflow aktivieren

⚠️ Hinweis: Der User muss Schreibrechte für devices/device1/# haben (siehe ACL in config/acl.conf).

Workflow anpassen

Du kannst den Workflow nach dem Import anpassen:

• Topic ändern: Passe das Topic im MQTT Node an (Zeile 17 in der JSON)
• Schedule anpassen: Ändere den Zeitplan im Schedule Trigger Node
• Nachrichtenformat: Passe die Message-Expression an (Zeile 19)

Test-Nachrichten senden

Via Docker

# Öffentlich (ohne Auth)
docker exec mosquitto mosquitto_pub -h localhost -t "public/message" -m "Test Nachricht"

# Mit Auth (Passwort aus .env verwenden)
docker exec mosquitto mosquitto_pub -h localhost -t "sensors/temperature" -m "22.5" -u admin -P <ADMIN_PASSWORD>
docker exec mosquitto mosquitto_pub -h localhost -t "sensors/humidity" -m "65" -u admin -P <ADMIN_PASSWORD>
docker exec mosquitto mosquitto_pub -h localhost -t "system/cpu" -m "45" -u admin -P <ADMIN_PASSWORD>

Oder verwende das Test-Script:

./test-mqtt.sh

Via Python (paho-mqtt)

pip install paho-mqtt

import paho.mqtt.client as mqtt
import os

# Credentials aus .env laden
admin_user = os.getenv("MQTT_ADMIN_USERNAME", "admin")
admin_pass = os.getenv("MQTT_ADMIN_PASSWORD")

client = mqtt.Client()
client.username_pw_set(admin_user, admin_pass)
client.connect("localhost", 1883)

# Nachrichten senden
client.publish("sensors/temperature", "23.4")
client.publish("sensors/humidity", "68")
client.publish("public/message", "Hallo von Python!")

client.disconnect()

Via JavaScript (Browser/Node.js)

npm install mqtt

const mqtt = require('mqtt');

// Credentials aus Umgebungsvariablen laden
const admin_user = process.env.MQTT_ADMIN_USERNAME || 'admin';
const admin_pass = process.env.MQTT_ADMIN_PASSWORD;

const client = mqtt.connect('ws://localhost:9001', {
    username: admin_user,
    password: admin_pass
});

client.on('connect', () => {
    console.log('Connected!');

    // Nachrichten senden
    client.publish('sensors/temperature', '24.1');
    client.publish('public/message', 'Hallo von Node.js!');
});

Troubleshooting

Container Logs anschauen

# Alle Logs
docker compose logs -f

# Nur Mosquitto
docker compose logs -f mosquitto

# Nur MQTTUI
docker compose logs -f mqttui

In Container einsteigen

# Mosquitto Container
docker exec -it mosquitto sh

# MQTTUI Container
docker exec -it mqttui sh

Mosquitto Konfiguration testen

docker exec mosquitto mosquitto -c /mosquitto/config/mosquitto.conf -v

Permissions Fehler

# Berechtigungen für passwords.txt setzen
chmod 644 passwords.txt

ACL Debug

Aktiviere Debug-Logging in mosquitto.conf:

log_type all

Dann Container neu starten und Logs prüfen.

Sicherheit für Production

⚠️ WICHTIG für Production-Umgebungen:

1. Passwörter ändern: Alle Default-Passwörter ändern!
2. SSL/TLS aktivieren: Verschlüsselte Verbindungen einrichten
3. Firewall konfigurieren: Nur benötigte Ports öffnen
4. ACL restriktiv gestalten: Principle of Least Privilege
5. Anonymous Access prüfen: allow_anonymous false belassen
6. Mosquitto Updates: Regelmäßig Updates einspielen

SSL/TLS einrichten (optional)

1. Zertifikate generieren
2. mosquitto.conf erweitern:

listener 8883
protocol mqtt
cafile /mosquitto/config/ca.crt
certfile /mosquitto/config/server.crt
keyfile /mosquitto/config/server.key

Container verwalten

# Starten
docker compose up -d

# Stoppen
docker compose stop

# Neu starten
docker compose restart

# Stoppen und löschen
docker compose down

# Stoppen, löschen inkl. Volumes
docker compose down -v

# Nur mosquitto neu starten
docker compose restart mosquitto

Support & Dokumentation

• Mosquitto Docs: https://mosquitto.org/documentation/
• MQTTUI: https://github.com/terdia/mqttui
• MQTT.org: https://mqtt.org/

Lizenz

Dieses Setup verwendet:

• Eclipse Mosquitto (EPL/EDL)
• MQTTUI (Open Source)