email-amazon/email-worker/docs/QUICKSTART.md

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

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

# 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

# Image bauen
docker-compose build

# Starten
docker-compose up -d

# Logs anschauen
docker-compose logs -f

4. Verifizierung

# 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

# 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

# Live Logs
docker-compose logs -f

# Nur Worker Logs
docker logs -f unified-email-worker

# Logs im Volume
tail -f logs/*.log

Neustart

# Neustart nach Code-Änderungen
docker-compose restart

# Kompletter Rebuild
docker-compose down
docker-compose build
docker-compose up -d

Update

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

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

# Status
curl http://localhost:8080/health | jq

# Domains
curl http://localhost:8080/domains | jq

🔐 DynamoDB Tabellen Setup

Email Rules (OOO, Forwarding)

# 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

# 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

# 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

# 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

# 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

# SMTP Verbindung testen
docker-compose exec unified-worker nc -zv localhost 25

# Worker Logs
docker-compose logs | grep "SMTP"

📈 Performance Tuning

Mehr Worker Threads

# In .env
WORKER_THREADS=20  # Default: 10

Längeres Polling

# In .env
POLL_INTERVAL=30  # Default: 20 (Sekunden)

Größerer Connection Pool

# In .env
SMTP_POOL_SIZE=10  # Default: 5

LMTP für bessere Performance

# In .env
LMTP_ENABLED=true
LMTP_PORT=24

🔄 Migration vom Monolithen

Side-by-Side Deployment

# 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

# 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