# 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
├── 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

# 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

### 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-mqtt mosquitto_pub -h localhost -t "public/test" -m "Hallo Welt!"

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

### Mit Authentifizierung

**Beispiel mit Admin User:**
```bash
# Mit Authentifizierung publishen (Credentials aus .env verwenden)
docker exec mosquitto-mqtt 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-mqtt 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

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

### User löschen

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

### Mosquitto neu laden (nach User-Änderungen)

```bash
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
```

## Test-Nachrichten senden

### Via Docker

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

# Mit Auth (Passwort aus .env verwenden)
docker exec mosquitto-mqtt mosquitto_pub -h localhost -t "sensors/temperature" -m "22.5" -u admin -P <ADMIN_PASSWORD>
docker exec mosquitto-mqtt mosquitto_pub -h localhost -t "sensors/humidity" -m "65" -u admin -P <ADMIN_PASSWORD>
docker exec mosquitto-mqtt 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-mqtt sh

# MQTTUI Container
docker exec -it mqttui sh
```

### Mosquitto Konfiguration testen

```bash
docker exec mosquitto-mqtt 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)