289 lines
12 KiB
Markdown
289 lines
12 KiB
Markdown
|
# 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
|