# 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)