moved

email-worker/docs/QUICKSTART.md

@@ -0,0 +1,330 @@
+# Quick Start Guide
+
+## 🚀 Deployment auf deinem System
+
+### Voraussetzungen
+- Docker & Docker Compose installiert
+- AWS Credentials mit Zugriff auf SQS, S3, SES, DynamoDB
+- Docker Mailserver (DMS) läuft lokal
+
+### 1. Vorbereitung
+
+```bash
+# Ins Verzeichnis wechseln
+cd /pfad/zu/email-worker
+
+# domains.txt anpassen (falls weitere Domains)
+nano domains.txt
+
+# Logs-Verzeichnis erstellen
+mkdir -p logs
+```
+
+### 2. Umgebungsvariablen
+
+Erstelle `.env` Datei:
+
+```bash
+# AWS Credentials
+AWS_ACCESS_KEY_ID=dein_access_key
+AWS_SECRET_ACCESS_KEY=dein_secret_key
+
+# Optional: Worker Settings überschreiben
+WORKER_THREADS=10
+POLL_INTERVAL=20
+MAX_MESSAGES=10
+
+# Optional: SMTP Settings
+SMTP_HOST=localhost
+SMTP_PORT=25
+
+# Optional: LMTP für direktes Dovecot Delivery
+# LMTP_ENABLED=true
+# LMTP_PORT=24
+```
+
+### 3. Build & Start
+
+```bash
+# Image bauen
+docker-compose build
+
+# Starten
+docker-compose up -d
+
+# Logs anschauen
+docker-compose logs -f
+```
+
+### 4. Verifizierung
+
+```bash
+# Health Check
+curl http://localhost:8080/health | jq
+
+# Domains prüfen
+curl http://localhost:8080/domains
+
+# Metrics (Prometheus)
+curl http://localhost:8000/metrics | grep emails_processed
+
+# Container Status
+docker ps | grep unified-email-worker
+```
+
+### 5. Test Email senden
+
+```bash
+# Via AWS SES Console oder CLI eine Test-Email senden
+aws ses send-email \
+  --from sender@andreasknuth.de \
+  --destination ToAddresses=test@andreasknuth.de \
+  --message Subject={Data="Test"},Body={Text={Data="Test message"}}
+
+# Worker Logs beobachten
+docker-compose logs -f | grep "Processing:"
+```
+
+## 🔧 Wartung
+
+### Logs anschauen
+```bash
+# Live Logs
+docker-compose logs -f
+
+# Nur Worker Logs
+docker logs -f unified-email-worker
+
+# Logs im Volume
+tail -f logs/*.log
+```
+
+### Neustart
+```bash
+# Neustart nach Code-Änderungen
+docker-compose restart
+
+# Kompletter Rebuild
+docker-compose down
+docker-compose build
+docker-compose up -d
+```
+
+### Update
+```bash
+# Neue Version pullen/kopieren
+git pull  # oder manuell Dateien ersetzen
+
+# Rebuild & Restart
+docker-compose down
+docker-compose build
+docker-compose up -d
+```
+
+## 📊 Monitoring
+
+### Prometheus Metrics (Port 8000)
+```bash
+# Alle Metrics
+curl http://localhost:8000/metrics
+
+# Verarbeitete Emails
+curl -s http://localhost:8000/metrics | grep emails_processed_total
+
+# Queue Größe
+curl -s http://localhost:8000/metrics | grep queue_messages_available
+
+# Blocked Senders
+curl -s http://localhost:8000/metrics | grep blocked_senders_total
+```
+
+### Health Check (Port 8080)
+```bash
+# Status
+curl http://localhost:8080/health | jq
+
+# Domains
+curl http://localhost:8080/domains | jq
+```
+
+## 🔐 DynamoDB Tabellen Setup
+
+### Email Rules (OOO, Forwarding)
+```bash
+# Tabelle erstellen (falls nicht vorhanden)
+aws dynamodb create-table \
+  --table-name email-rules \
+  --attribute-definitions AttributeName=email_address,AttributeType=S \
+  --key-schema AttributeName=email_address,KeyType=HASH \
+  --billing-mode PAY_PER_REQUEST \
+  --region us-east-2
+
+# OOO Regel hinzufügen
+aws dynamodb put-item \
+  --table-name email-rules \
+  --item '{
+    "email_address": {"S": "andreas@andreasknuth.de"},
+    "ooo_active": {"BOOL": true},
+    "ooo_message": {"S": "Ich bin derzeit nicht erreichbar."},
+    "ooo_content_type": {"S": "text"}
+  }' \
+  --region us-east-2
+
+# Forward Regel hinzufügen
+aws dynamodb put-item \
+  --table-name email-rules \
+  --item '{
+    "email_address": {"S": "info@andreasknuth.de"},
+    "forwards": {"L": [
+      {"S": "andreas@andreasknuth.de"}
+    ]}
+  }' \
+  --region us-east-2
+```
+
+### Blocked Senders
+```bash
+# Tabelle erstellen (falls nicht vorhanden)
+aws dynamodb create-table \
+  --table-name email-blocked-senders \
+  --attribute-definitions AttributeName=email_address,AttributeType=S \
+  --key-schema AttributeName=email_address,KeyType=HASH \
+  --billing-mode PAY_PER_REQUEST \
+  --region us-east-2
+
+# Blocklist hinzufügen
+aws dynamodb put-item \
+  --table-name email-blocked-senders \
+  --item '{
+    "email_address": {"S": "andreas@andreasknuth.de"},
+    "blocked_patterns": {"L": [
+      {"S": "*@spam.com"},
+      {"S": "noreply@*.marketing.com"}
+    ]}
+  }' \
+  --region us-east-2
+```
+
+## 🐛 Troubleshooting
+
+### Worker startet nicht
+```bash
+# Logs prüfen
+docker-compose logs unified-worker
+
+# Container Status
+docker ps -a | grep unified
+
+# Manuell starten (Debug)
+docker-compose run --rm unified-worker python3 main.py
+```
+
+### Keine Emails werden verarbeitet
+```bash
+# Queue URLs prüfen
+curl http://localhost:8080/domains
+
+# AWS Permissions prüfen
+aws sqs list-queues --region us-east-2
+
+# DynamoDB Verbindung prüfen (in Logs)
+docker-compose logs | grep "DynamoDB"
+```
+
+### Bounces werden nicht umgeschrieben
+```bash
+# DynamoDB Bounce Records prüfen
+aws dynamodb scan \
+  --table-name ses-outbound-messages \
+  --limit 5 \
+  --region us-east-2
+
+# Worker Logs nach "Bounce detected" durchsuchen
+docker-compose logs | grep "Bounce detected"
+```
+
+### SMTP Delivery Fehler
+```bash
+# SMTP Verbindung testen
+docker-compose exec unified-worker nc -zv localhost 25
+
+# Worker Logs
+docker-compose logs | grep "SMTP"
+```
+
+## 📈 Performance Tuning
+
+### Mehr Worker Threads
+```bash
+# In .env
+WORKER_THREADS=20  # Default: 10
+```
+
+### Längeres Polling
+```bash
+# In .env
+POLL_INTERVAL=30  # Default: 20 (Sekunden)
+```
+
+### Größerer Connection Pool
+```bash
+# In .env
+SMTP_POOL_SIZE=10  # Default: 5
+```
+
+### LMTP für bessere Performance
+```bash
+# In .env
+LMTP_ENABLED=true
+LMTP_PORT=24
+```
+
+## 🔄 Migration vom Monolithen
+
+### Side-by-Side Deployment
+```bash
+# Alte Version läuft als "unified-email-worker-old"
+# Neue Version als "unified-email-worker"
+
+# domains.txt aufteilen:
+# old: andreasknuth.de
+# new: andere-domain.de
+
+# Nach Verifizierung alle Domains auf new migrieren
+```
+
+### Zero-Downtime Switch
+```bash
+# 1. Neue Version starten (andere Domains)
+docker-compose up -d
+
+# 2. Beide parallel laufen lassen (24h)
+# 3. Monitoring: Metrics vergleichen
+curl http://localhost:8000/metrics
+
+# 4. Alte Version stoppen
+docker stop unified-email-worker-old
+
+# 5. domains.txt updaten (alle Domains)
+# 6. Neue Version neustarten
+docker-compose restart
+```
+
+## ✅ Checkliste nach Deployment
+
+- [ ] Container läuft: `docker ps | grep unified`
+- [ ] Health Check OK: `curl http://localhost:8080/health`
+- [ ] Domains geladen: `curl http://localhost:8080/domains`
+- [ ] Logs ohne Fehler: `docker-compose logs | grep ERROR`
+- [ ] Test-Email erfolgreich: Email an Test-Adresse senden
+- [ ] Bounce Rewriting funktioniert: Bounce-Email testen
+- [ ] Metrics erreichbar: `curl http://localhost:8000/metrics`
+- [ ] DynamoDB Tables vorhanden: AWS Console prüfen
+
+## 📞 Support
+
+Bei Problemen:
+1. Logs prüfen: `docker-compose logs -f`
+2. Health Check: `curl http://localhost:8080/health`
+3. AWS Console: Queues, S3 Buckets, DynamoDB prüfen
+4. Container neu starten: `docker-compose restart`