bakery-ia/infrastructure/platform/mail/mailu/README.md

# 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