Joachim Hummel
8e8924254b
Dashboard-Screenshot und n8n-Flow-Diagramm in die entsprechenden Abschnitte der README eingefügt. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
430 lines
10 KiB
Markdown
430 lines
10 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# .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
|
|
|
|
```bash
|
|
# Container starten
|
|
docker compose up -d
|
|
|
|
# Logs anschauen
|
|
docker compose logs -f
|
|
```
|
|
|
|
### 3. Benutzer erstellen
|
|
|
|
```bash
|
|
# 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:**
|
|
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
docker compose restart mosquitto
|
|
```
|
|
|
|
**Alternativ - Manuell:**
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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:
|
|
```bash
|
|
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:
|
|
```bash
|
|
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](https://n8n.io/) 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](https://docs.n8n.io/))
|
|
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
|
|
|
|
```bash
|
|
# Ö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:
|
|
```bash
|
|
./test-mqtt.sh
|
|
```
|
|
|
|
### Via Python (paho-mqtt)
|
|
|
|
```bash
|
|
pip install paho-mqtt
|
|
```
|
|
|
|
```python
|
|
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)
|
|
|
|
```bash
|
|
npm install mqtt
|
|
```
|
|
|
|
```javascript
|
|
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
|
|
|
|
```bash
|
|
# Alle Logs
|
|
docker compose logs -f
|
|
|
|
# Nur Mosquitto
|
|
docker compose logs -f mosquitto
|
|
|
|
# Nur MQTTUI
|
|
docker compose logs -f mqttui
|
|
```
|
|
|
|
### In Container einsteigen
|
|
|
|
```bash
|
|
# Mosquitto Container
|
|
docker exec -it mosquitto sh
|
|
|
|
# MQTTUI Container
|
|
docker exec -it mqttui sh
|
|
```
|
|
|
|
### Mosquitto Konfiguration testen
|
|
|
|
```bash
|
|
docker exec mosquitto mosquitto -c /mosquitto/config/mosquitto.conf -v
|
|
```
|
|
|
|
### Permissions Fehler
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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)
|