Add new infra architecture

2026-01-19 11:55:17 +01:00
parent 21d35ea92b
commit 35f164f0cd
311 changed files with 13241 additions and 3700 deletions
--- a/infrastructure/platform/mail/mailu/README.md
+++ b/infrastructure/platform/mail/mailu/README.md
@@ -0,0 +1,289 @@
+# Mailu Email Infrastructure for Bakery-IA
+
+This directory contains the Kubernetes deployment configuration for Mailu, a self-hosted email solution that integrates with external SMTP relays for optimal deliverability.
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           Kubernetes Cluster (bakery-ia)                     │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                              │
+│  ┌──────────────────┐      ┌──────────────────┐      ┌──────────────────┐  │
+│  │  notification-   │      │   mail-service   │      │     frontend     │  │
+│  │     service      │─────▶│   (new/optional) │      │                  │  │
+│  │                  │      │  Queue & Routing │      │                  │  │
+│  └────────┬─────────┘      └────────┬─────────┘      └──────────────────┘  │
+│           │                         │                                        │
+│           │ SMTP (port 587)         │ SMTP (port 587)                       │
+│           ▼                         ▼                                        │
+│  ┌──────────────────────────────────────────────────────────────────────┐   │
+│  │                         MAILU STACK                                   │   │
+│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  │   │
+│  │  │   front     │  │   admin     │  │    smtp     │  │    imap     │  │   │
+│  │  │  (nginx)    │  │  (webmail)  │  │  (postfix)  │  │  (dovecot)  │  │   │
+│  │  │  :80/:443   │  │   :8080     │  │ :25/:587    │  │  :993/:143  │  │   │
+│  │  └─────────────┘  └─────────────┘  └──────┬──────┘  └─────────────┘  │   │
+│  │                                           │                           │   │
+│  │  ┌─────────────┐  ┌─────────────┐         │ Relay                    │   │
+│  │  │  antispam   │  │  antivirus  │         │                          │   │
+│  │  │ (rspamd)    │  │ (clamav)    │         │                          │   │
+│  │  └─────────────┘  └─────────────┘         │                          │   │
+│  │                                           │                          │   │
+│  │  ┌─────────────────────────────────┐      │                          │   │
+│  │  │       mailu-db (redis)          │      │                          │   │
+│  │  └─────────────────────────────────┘      │                          │   │
+│  └───────────────────────────────────────────┼──────────────────────────┘   │
+│                                              │                               │
+└──────────────────────────────────────────────┼───────────────────────────────┘
+                                               │
+                                               ▼
+                          ┌──────────────────────────────────────┐
+                          │     EXTERNAL SMTP RELAY              │
+                          │  (SendGrid / Mailgun / AWS SES)      │
+                          │                                      │
+                          │  • Handles IP reputation             │
+                          │  • Manages deliverability            │
+                          │  • Provides bounce/complaint hooks   │
+                          └──────────────────────────────────────┘
+                                               │
+                                               ▼
+                          ┌──────────────────────────────────────┐
+                          │          INTERNET / RECIPIENTS       │
+                          └──────────────────────────────────────┘
+```
+
+## Components
+
+### Core Services
+
+- **mailu-front**: Nginx reverse proxy for web access (ports 80/443)
+- **mailu-admin**: Web administration interface (port 80)
+- **mailu-smtp**: Postfix SMTP server (ports 25/587)
+- **mailu-imap**: Dovecot IMAP server (ports 143/993)
+- **mailu-antispam**: Rspamd spam filtering (ports 11333/11334)
+- **mailu-redis**: Redis for session management (port 6379)
+
+### Storage
+
+- **mailu-data**: 10Gi PVC for mail storage
+- **mailu-db**: 5Gi PVC for database
+- **mailu-redis**: 1Gi PVC for Redis persistence
+
+## Configuration
+
+### Environment Variables
+
+The Mailu stack is configured via the `mailu-configmap.yaml` file:
+
+- **DOMAIN**: `bakewise.ai`
+- **HOSTNAMES**: `mail.bakewise.ai`
+- **RELAYHOST**: `smtp.mailgun.org:587`
+- **RELAY_LOGIN**: `apikey`
+- **TLS_FLAVOR**: `cert` (uses Let's Encrypt)
+- **WEBMAIL**: `roundcube`
+- **ANTIVIRUS**: `clamav`
+- **ANTISPAM**: `rspamd`
+
+### Secrets
+
+Secrets are managed in `mailu-secrets.yaml`:
+
+- **ADMIN_PASSWORD**: Base64 encoded admin password
+- **SECRET_KEY**: Mailu internal encryption key
+- **RELAY_PASSWORD**: External SMTP relay API key
+- **DB_PASSWORD**: Database password
+- **REDIS_PASSWORD**: Redis password
+
+## Deployment
+
+### Prerequisites
+
+1. Kubernetes cluster with storage provisioner
+2. Ingress controller (NGINX)
+3. Cert-manager for TLS certificates
+4. External SMTP relay account (Mailgun, SendGrid, AWS SES)
+
+### Deployment Steps
+
+1. **Configure DNS**:
+   ```bash
+   # MX record for inbound email
+   bakewise.ai.    IN MX    10 mail.bakewise.ai.
+   
+   # A record for mail server
+   mail.bakewise.ai.    IN A    <your-ingress-ip>
+   
+   # SPF record (authorize external relay)
+   bakewise.ai.    IN TXT   "v=spf1 include:mailgun.org ~all"
+   
+   # DKIM record (Mailu generates this)
+   mailu._domainkey.bakewise.ai.    IN TXT   "v=DKIM1; k=rsa; p=<public-key>"
+   
+   # DMARC record
+   _dmarc.bakewise.ai.    IN TXT   "v=DMARC1; p=quarantine; rua=mailto:dmarc@bakewise.ai"
+   ```
+
+2. **Update secrets**:
+   ```bash
+   # Generate secure passwords
+   echo -n "your-secure-password" | base64
+   openssl rand -base64 32
+   
+   # Update mailu-secrets.yaml with real values
+   ```
+
+3. **Deploy Mailu**:
+   ```bash
+   # For production
+   kubectl apply -k infrastructure/environments/prod/k8s-manifests/
+   
+   # For development
+   kubectl apply -k infrastructure/environments/dev/k8s-manifests/
+   ```
+
+4. **Verify deployment**:
+   ```bash
+   kubectl get pods -n bakery-ia | grep mailu
+   kubectl logs -f mailu-smtp-<pod-id> -n bakery-ia
+   ```
+
+## Integration with Notification Service
+
+The notification service has been updated to use Mailu as the SMTP server:
+
+```yaml
+# infrastructure/environments/common/configs/configmap.yaml
+SMTP_HOST: "mailu-smtp.bakery-ia.svc.cluster.local"
+SMTP_PORT: "587"
+SMTP_TLS: "true"
+SMTP_SSL: "false"
+```
+
+## Accessing Mailu
+
+### Web Interface
+
+- **Admin Panel**: `https://mail.bakewise.ai/admin`
+- **Webmail**: `https://mail.bakewise.ai/webmail`
+
+### SMTP Configuration
+
+For external clients to send email through Mailu:
+
+- **Server**: `mail.bakewise.ai`
+- **Port**: 587 (Submission)
+- **Security**: STARTTLS
+- **Authentication**: Required
+
+### IMAP Configuration
+
+For email clients to access mailboxes:
+
+- **Server**: `mail.bakewise.ai`
+- **Port**: 993 (IMAPS)
+- **Security**: SSL/TLS
+- **Authentication**: Required
+
+## Monitoring and Maintenance
+
+### Health Checks
+
+```bash
+# Check Mailu services
+kubectl get pods -n bakery-ia -l app=mailu
+
+# Check Mailu logs
+kubectl logs -f mailu-smtp-<pod-id> -n bakery-ia
+kubectl logs -f mailu-antispam-<pod-id> -n bakery-ia
+
+# Check queue status
+kubectl exec -it mailu-smtp-<pod-id> -n bakery-ia -- mailq
+```
+
+### Backup and Restore
+
+```bash
+# Backup mail data
+kubectl exec -it mailu-smtp-<pod-id> -n bakery-ia -- tar czf /backup/mailu-backup-$(date +%Y%m%d).tar.gz /data
+
+# Restore mail data
+kubectl cp mailu-backup-<date>.tar.gz mailu-smtp-<pod-id>:/backup/ -n bakery-ia
+kubectl exec -it mailu-smtp-<pod-id> -n bakery-ia -- tar xzf /backup/mailu-backup-<date>.tar.gz -C /
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **SMTP Relay Authentication Failed**:
+   - Verify `RELAY_PASSWORD` in secrets matches your external relay API key
+   - Check network connectivity to external relay
+
+2. **TLS Certificate Issues**:
+   - Ensure cert-manager is working properly
+   - Check DNS records are correctly pointing to your ingress
+
+3. **Email Delivery Delays**:
+   - Check Mailu queue: `kubectl exec -it mailu-smtp-<pod-id> -n bakery-ia -- mailq`
+   - Verify external relay service status
+
+4. **Spam Filtering Issues**:
+   - Check rspamd logs: `kubectl logs -f mailu-antispam-<pod-id> -n bakery-ia`
+   - Adjust spam scoring in rspamd configuration
+
+## Resource Requirements
+
+| Component | CPU Request | CPU Limit | Memory Request | Memory Limit | Storage |
+|-----------|-------------|-----------|----------------|--------------|----------|
+| mailu-front | 100m | 200m | 128Mi | 256Mi | - |
+| mailu-admin | 100m | 300m | 256Mi | 512Mi | - |
+| mailu-smtp | 100m | 500m | 256Mi | 512Mi | 10Gi |
+| mailu-imap | 100m | 500m | 256Mi | 512Mi | - |
+| mailu-antispam | 200m | 1000m | 512Mi | 1Gi | - |
+| mailu-redis | 100m | 200m | 128Mi | 256Mi | 1Gi |
+
+**Total**: ~600m CPU, ~1.7Gi Memory, 16Gi Storage
+
+## Security Considerations
+
+1. **Network Policies**: Mailu is protected by network policies that restrict access to only the notification service and ingress controller.
+
+2. **TLS Encryption**: All external connections use TLS encryption.
+
+3. **Authentication**: All services require authentication.
+
+4. **Rate Limiting**: Configured to prevent abuse (60/hour per IP, 100/day per user).
+
+5. **Spam Protection**: Rspamd provides comprehensive spam filtering with DKIM signing.
+
+## Migration from External SMTP
+
+To migrate from external SMTP (Gmail) to Mailu:
+
+1. Update DNS records as shown above
+2. Deploy Mailu stack
+3. Update notification service configuration
+4. Test email delivery
+5. Monitor deliverability metrics
+6. Gradually increase email volume
+
+## External Relay Provider Comparison
+
+| Provider | Pros | Cons | Free Tier |
+|----------|------|------|-----------|
+| SendGrid | Best deliverability, robust API | Expensive at scale | 100/day |
+| Mailgun | Developer-friendly, good logs | EU data residency costs extra | 5,000/month (3 months) |
+| AWS SES | Cheapest at scale ($0.10/1000) | Requires warm-up period | 62,000/month (from EC2) |
+| Postmark | Transactional focus, fast | No marketing emails | 100/month |
+
+**Recommendation**: AWS SES for cost-effectiveness and Kubernetes integration.
+
+## Support
+
+For issues with Mailu deployment:
+
+1. Check the [Mailu documentation](https://mailu.io/)
+2. Review Kubernetes events: `kubectl get events -n bakery-ia`
+3. Check pod logs for specific components
+4. Verify network connectivity and DNS resolution