aknuth
/
email-amazon
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
email-amazon/unified-worker/email-worker/docs/COMPATIBILITY.md

7.5 KiB
Raw Blame History

Kompatibilität mit bestehendem Setup

✅ 100% Kompatibel

Die modulare Version ist vollständig kompatibel mit deinem bestehenden Setup:

1. Dockerfile

  • ✅ Gleicher Base Image: python:3.11-slim
  • ✅ Gleicher User: worker (UID 1000)
  • ✅ Gleiche Verzeichnisse: /app, /var/log/email-worker, /etc/email-worker
  • ✅ Gleicher Health Check: curl http://localhost:8080/health
  • ✅ Gleiche Labels: maintainer, description
  • Änderung: Kopiert nun mehrere Module statt einer Datei

2. docker-compose.yml

  • ✅ Gleicher Container Name: unified-email-worker
  • ✅ Gleicher Network Mode: host
  • ✅ Gleiche Volumes: domains.txt, logs/
  • ✅ Gleiche Ports: 8000, 8080
  • ✅ Gleiche Environment Variables
  • ✅ Gleiche Resource Limits: 512M / 256M
  • ✅ Gleiche Logging Config: 50M / 10 files
  • Neu: Zusätzliche optionale Env Vars (abwärtskompatibel)

3. requirements.txt

  • ✅ Gleiche Dependencies: boto3, prometheus-client
  • ✅ Aktualisierte Versionen (>=1.34.0 statt >=1.26.0)
  • Kompatibel: Alte Version funktioniert auch, neue ist empfohlen

4. domains.txt

  • ✅ Gleiches Format: Eine Domain pro Zeile
  • ✅ Kommentare mit # funktionieren
  • ✅ Gleiche Location: /etc/email-worker/domains.txt
  • Keine Änderung nötig

🔄 Was ist neu/anders?

Dateistruktur

Alt:

/
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
├── domains.txt
└── unified_worker.py  (800+ Zeilen)

Neu:

/
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
├── domains.txt
├── main.py                    # Entry Point
├── config.py                  # Konfiguration
├── logger.py                  # Logging
├── worker.py                  # Message Processing
├── unified_worker.py          # Worker Coordinator
├── domain_poller.py          # Queue Polling
├── health_server.py          # Health Check Server
├── aws/
│   ├── s3_handler.py
│   ├── sqs_handler.py
│   ├── ses_handler.py
│   └── dynamodb_handler.py
├── email/
│   ├── parser.py
│   ├── bounce_handler.py
│   ├── blocklist.py
│   └── rules_processor.py
├── smtp/
│   ├── pool.py
│   └── delivery.py
└── metrics/
    └── prometheus.py

Neue optionale Umgebungsvariablen

Diese sind optional und haben sinnvolle Defaults:

# Internal SMTP Port (neu)
INTERNAL_SMTP_PORT=2525         # Default: 2525

# LMTP Support (neu)
LMTP_ENABLED=false              # Default: false
LMTP_HOST=localhost             # Default: localhost
LMTP_PORT=24                    # Default: 24

# Blocklist Table (neu)
DYNAMODB_BLOCKED_TABLE=email-blocked-senders  # Default: email-blocked-senders

Wichtig: Wenn du diese nicht setzt, funktioniert alles wie vorher!

🚀 Deployment

Option 1: Drop-In Replacement

# Alte Dateien sichern
cp unified_worker.py unified_worker.py.backup
cp Dockerfile Dockerfile.backup
cp docker-compose.yml docker-compose.yml.backup

# Neue Dateien entpacken
tar -xzf email-worker-modular.tar.gz
cd email-worker/

# domains.txt und .env anpassen (falls nötig)
# Dann normal deployen:
docker-compose build
docker-compose up -d

Option 2: Side-by-Side (Empfohlen)

# Altes Setup bleibt in /opt/email-worker-old
# Neues Setup in /opt/email-worker

# Neue Version entpacken
cd /opt
tar -xzf email-worker-modular.tar.gz
mv email-worker email-worker-new

# Container Namen unterscheiden:
# In docker-compose.yml:
container_name: unified-email-worker-new

# Starten
cd email-worker-new
docker-compose up -d

# Parallel laufen lassen (24h Test)
# Dann alte Version stoppen, neue umbenennen

🔍 Verifikation der Kompatibilität

1. Environment Variables

Alle deine bestehenden Env Vars funktionieren:

# Deine bisherigen Vars (alle kompatibel)
AWS_ACCESS_KEY_ID          ✅
AWS_SECRET_ACCESS_KEY      ✅
AWS_REGION                 ✅
WORKER_THREADS             ✅
POLL_INTERVAL              ✅
MAX_MESSAGES               ✅
VISIBILITY_TIMEOUT         ✅
SMTP_HOST                  ✅
SMTP_PORT                  ✅
SMTP_POOL_SIZE             ✅
METRICS_PORT               ✅
HEALTH_PORT                ✅

2. DynamoDB Tables

Bestehende Tables funktionieren ohne Änderung:

# Bounce Tracking (bereits vorhanden)
ses-outbound-messages      ✅

# Email Rules (bereits vorhanden?)
email-rules                ✅

# Blocklist (neu, optional)
email-blocked-senders      🆕 Optional

3. API Endpoints

Gleiche Endpoints wie vorher:

# Health Check
GET http://localhost:8080/health       ✅ Gleiche Response

# Domains List
GET http://localhost:8080/domains      ✅ Gleiche Response

# Prometheus Metrics
GET http://localhost:8000/metrics      ✅ Kompatibel + neue Metrics

4. Logging

Gleiches Format, gleiche Location:

# Logs in Container
/var/log/email-worker/     ✅ Gleich

# Log Format
[timestamp] [LEVEL] [worker-name] [thread] message    ✅ Gleich

5. S3 Metadata

Gleiches Schema, volle Kompatibilität:

{
  "processed": "true",
  "processed_at": "1706000000",
  "processed_by": "worker-andreasknuth-de",
  "status": "delivered",
  "invalid_inboxes": "..."
}

Neu: Zusätzliche Metadata bei blockierten Emails:

{
  "status": "blocked",
  "blocked_sender": "spam@bad.com",
  "blocked_recipients": "user@andreasknuth.de"
}

⚠️ Breaking Changes

KEINE! Die modulare Version ist 100% abwärtskompatibel.

Die einzigen Unterschiede sind:

  1. ✅ Mehr Dateien statt einer (aber gleiches Verhalten)
  2. ✅ Neue optionale Features (müssen nicht genutzt werden)
  3. ✅ Bessere Performance (durch Batch-Calls)
  4. ✅ Mehr Metrics (zusätzliche, alte bleiben)

🧪 Testing Checklist

Nach Deployment prüfen:

# 1. Container läuft
docker ps | grep unified-email-worker
✅ Status: Up

# 2. Health Check
curl http://localhost:8080/health | jq
✅ "status": "healthy"

# 3. Domains geladen
curl http://localhost:8080/domains
✅ ["andreasknuth.de"]

# 4. Logs ohne Fehler
docker-compose logs | grep ERROR
✅ Keine kritischen Fehler

# 5. Test Email senden
# Email via SES senden
✅ Wird zugestellt

# 6. Metrics verfügbar
curl http://localhost:8000/metrics | grep emails_processed
✅ Metrics werden erfasst

💡 Empfohlener Rollout-Plan

Phase 1: Testing (1-2 Tage)

  • Neuen Container parallel zum alten starten
  • Nur 1 Test-Domain zuweisen
  • Logs monitoren
  • Performance vergleichen

Phase 2: Staged Rollout (3-7 Tage)

  • 50% der Domains auf neue Version
  • Metrics vergleichen (alte vs neue)
  • Bei Problemen: Rollback auf alte Version

Phase 3: Full Rollout

  • Alle Domains auf neue Version
  • Alte Version als Backup behalten (1 Woche)
  • Dann alte Version dekommissionieren

🔙 Rollback-Plan

Falls Probleme auftreten:

# 1. Neue Version stoppen
docker-compose -f docker-compose.yml down

# 2. Backup wiederherstellen
cp unified_worker.py.backup unified_worker.py
cp Dockerfile.backup Dockerfile
cp docker-compose.yml.backup docker-compose.yml

# 3. Alte Version starten
docker-compose build
docker-compose up -d

# 4. Verifizieren
curl http://localhost:8080/health

Downtime: < 30 Sekunden (Zeit für Container Restart)

✅ Fazit

Die modulare Version ist ein Drop-In Replacement:

  • Gleiche Konfiguration
  • Gleiche API
  • Gleiche Infrastruktur
  • Bonus: Bessere Performance, mehr Features, weniger Bugs

Einziger Unterschied: Mehr Dateien, aber alle in einem tarball verpackt.