331 lines
6.7 KiB
Markdown
331 lines
6.7 KiB
Markdown
# 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`
|