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:

   # 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:

   # Generate secure passwords
   echo -n "your-secure-password" | base64
   openssl rand -base64 32
   
   # Update mailu-secrets.yaml with real values
   

3. Deploy Mailu:

   # For production
   kubectl apply -k infrastructure/environments/prod/k8s-manifests/
   
   # For development
   kubectl apply -k infrastructure/environments/dev/k8s-manifests/
   

4. Verify deployment:

   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:

# 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

# 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

# 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
2. Review Kubernetes events: kubectl get events -n bakery-ia
3. Check pod logs for specific components
4. Verify network connectivity and DNS resolution