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

Kubernetes cluster with storage provisioner
Ingress controller (NGINX)
Cert-manager for TLS certificates
External SMTP relay account (Mailgun, SendGrid, AWS SES)

Deployment Steps

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"

Update secrets:

# Generate secure passwords
echo -n "your-secure-password" | base64
openssl rand -base64 32

# Update mailu-secrets.yaml with real values

Deploy Mailu:

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

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

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

SMTP Relay Authentication Failed:
- Verify RELAY_PASSWORD in secrets matches your external relay API key
- Check network connectivity to external relay
TLS Certificate Issues:
- Ensure cert-manager is working properly
- Check DNS records are correctly pointing to your ingress
Email Delivery Delays:
- Check Mailu queue: kubectl exec -it mailu-smtp-<pod-id> -n bakery-ia -- mailq
- Verify external relay service status
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

Network Policies: Mailu is protected by network policies that restrict access to only the notification service and ingress controller.
TLS Encryption: All external connections use TLS encryption.
Authentication: All services require authentication.
Rate Limiting: Configured to prevent abuse (60/hour per IP, 100/day per user).
Spam Protection: Rspamd provides comprehensive spam filtering with DKIM signing.

Migration from External SMTP

To migrate from external SMTP (Gmail) to Mailu:

Update DNS records as shown above
Deploy Mailu stack
Update notification service configuration
Test email delivery
Monitor deliverability metrics
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:

Check the Mailu documentation
Review Kubernetes events: kubectl get events -n bakery-ia
Check pod logs for specific components
Verify network connectivity and DNS resolution