README.md aktualisiert

README.md

@@ -1,3 +1,182 @@
-# mail-alarm
+# 📬 Mail-Alarm
 
-Eine zuverlässigere und besser funktionierende Lösung um sich bei Alarm-Maileingang in der Rufbereitschaft benachrichtigen zu lassen.
+IMAP-Überwachung mit Pushover Emergency Alerts für Rufbereitschaft.
+
+## Beschreibung
+
+Mail-Alarm überwacht ein E-Mail-Postfach in Echtzeit via IMAP IDLE und löst bei eingehenden Mails einen Pushover Emergency Alert aus. Der Alarm klingelt wiederholt auf allen verbundenen Geräten (Smartphone, Smartwatch, Desktop), bis er bestätigt wird – ideal für Rufbereitschaft.
+
+## Features
+
+- 🚀 **IMAP IDLE** – Reagiert sofort auf neue E-Mails (kein Polling)
+- 📱 **Pushover Emergency Alerts** – Klingelt wiederholt bis zur Bestätigung
+- 📲 **Multi-Plattform** – iPhone, Apple Watch, Android, Desktop (Windows, Mac, Linux)
+- 🔄 **Auto-Reconnect** – Verbindet sich automatisch bei Verbindungsabbruch neu
+- 🛠️ **Einfache Installation** – Interaktives Setup mit systemd-Integration
+- 📋 **Details im Alarm** – Zeigt Absender und Betreff der E-Mail
+
+## Voraussetzungen
+
+- Debian/Ubuntu Server (getestet mit Debian 13)
+- Python 3
+- Pushover Account + App ([pushover.net](https://pushover.net)) – einmalig ~5€ pro Plattform
+- IMAP-fähiges E-Mail-Postfach
+
+## Installation
+
+```bash
+# Repository klonen
+git clone https://git.jtl-hosting.de/thomasciesla/mail-alarm.git
+cd mail-alarm
+
+# Installation starten (als root)
+sudo python3 mail-alarm.py
+```
+
+Im Menü `1) Installieren` wählen und den Anweisungen folgen.
+
+Das Script:
+1. Installiert Abhängigkeiten (`python3-imapclient`, `python3-requests`)
+2. Fragt IMAP- und Pushover-Credentials ab
+3. Erstellt Konfiguration in `/etc/mail-alarm/config.ini`
+4. Richtet systemd-Service ein und startet den Daemon
+
+## Verwendung
+
+### Service-Verwaltung
+
+```bash
+# Status anzeigen
+systemctl status mail-alarm
+
+# Service stoppen
+systemctl stop mail-alarm
+
+# Service starten
+systemctl start mail-alarm
+
+# Service neustarten
+systemctl restart mail-alarm
+
+# Logs anzeigen (live)
+journalctl -u mail-alarm -f
+
+# Oder Log-Datei direkt
+tail -f /var/log/mail-alarm.log
+```
+
+### Setup-Menü erneut aufrufen
+
+```bash
+sudo python3 /usr/local/bin/mail-alarm.py
+```
+
+## Deinstallation
+
+```bash
+sudo python3 /usr/local/bin/mail-alarm.py
+```
+
+Im Menü `2) Deinstallieren` wählen. Optional können Konfiguration und Logs gelöscht werden.
+
+## Konfiguration
+
+Die Konfigurationsdatei liegt unter `/etc/mail-alarm/config.ini`:
+
+```ini
+[IMAP]
+server = imap.example.com
+port = 993
+username = alarm@example.com
+password = geheim
+folder = INBOX
+
+[PUSHOVER]
+token = dein-app-token
+user = dein-user-key
+sound = dein-custom-sound
+
+[ALARM]
+retry = 30
+expire = 3600
+title = Rufbereitschaft
+message = ALARM: Neue E-Mail im Rufbereitschafts-Postfach!
+```
+
+| Parameter | Beschreibung |
+|-----------|--------------|
+| `retry` | Intervall in Sekunden, in dem der Alarm wiederholt wird (min. 30) |
+| `expire` | Maximale Dauer in Sekunden, wie lange der Alarm wiederholt wird |
+| `sound` | Optionaler Custom-Sound (auf pushover.net hochladen) |
+
+## Pushover Setup
+
+1. Account erstellen auf [pushover.net](https://pushover.net)
+2. App erstellen unter [pushover.net/apps](https://pushover.net/apps) → "Create an Application"
+3. **App Token** und **User Key** notieren
+4. Optional: Eigenen Alarm-Sound hochladen (max. 30 Sek. MP3)
+
+### Tipp: Langer Alarm-Sound
+
+Für einen durchgehenden Alarm einen ~30 Sekunden langen Sound erstellen:
+
+```bash
+ffmpeg -stream_loop -1 -i alarm.mp3 -t 30 -c:a libmp3lame alarm_30s.mp3
+```
+
+Dann auf [pushover.net/sounds](https://pushover.net/sounds) hochladen.
+
+## Unterstützte Plattformen
+
+Pushover ist verfügbar für:
+
+| Plattform | App |
+|-----------|-----|
+| **iOS** | [App Store](https://apps.apple.com/app/pushover-notifications/id506088175) |
+| **Android** | [Google Play](https://play.google.com/store/apps/details?id=net.superblock.pushover) |
+| **Desktop** | [pushover.net/clients](https://pushover.net/clients) (Windows, Mac, Linux) |
+| **Apple Watch** | Automatisch mit iOS App |
+| **Android Wear** | Automatisch mit Android App |
+
+Der Emergency Alert (Priority 2) funktioniert auf allen Plattformen und klingelt wiederholt bis zur Bestätigung.
+
+### Hinweis für iPhone + Apple Watch
+
+Standardmäßig leitet iOS Benachrichtigungen nur an die Apple Watch weiter, wenn diese getragen wird. Um beide Geräte gleichzeitig zu alarmieren:
+
+**Apple Watch → Einstellungen → Code → Handgelenkerkennung deaktivieren**
+
+⚠️ Dadurch werden einige Watch-Features deaktiviert (Herzfrequenz, Aktivitätsmessung).
+
+## Manueller Test
+
+Pushover-Alert manuell auslösen:
+
+```bash
+curl -s \
+  --form-string "token=DEIN_APP_TOKEN" \
+  --form-string "user=DEIN_USER_KEY" \
+  --form-string "message=Test-Alarm" \
+  --form-string "title=Rufbereitschaft" \
+  --form-string "priority=2" \
+  --form-string "retry=30" \
+  --form-string "expire=300" \
+  https://api.pushover.net/1/messages.json
+```
+
+## Dateien
+
+| Pfad | Beschreibung |
+|------|--------------|
+| `/usr/local/bin/mail-alarm.py` | Hauptscript |
+| `/etc/mail-alarm/config.ini` | Konfiguration (nur root lesbar) |
+| `/var/log/mail-alarm.log` | Log-Datei |
+| `/etc/systemd/system/mail-alarm.service` | systemd Service |
+
+## Lizenz
+
+MIT
+
+## Autor
+
+Thomas Ciesla