bakery-ia/infrastructure/platform/mail/mailu-helm/MIGRATION_GUIDE.md

Mailu Migration Guide: From Kustomize to Helm

This document outlines the migration process from the Kustomize-based Mailu deployment to the Helm-based deployment.

Overview

The Mailu email server has been migrated from a Kustomize-based deployment to a Helm chart-based deployment. This change provides better maintainability, easier upgrades, and standardized configuration management.

Key Changes

1. Service Names

• Old: mailu-smtp, email-smtp, mailu-front, mailu-admin, mailu-imap, mailu-antispam
• New: mailu-postfix, mailu-front, mailu-admin, mailu-dovecot, mailu-rspamd

2. Configuration Method

• Old: Individual YAML manifests with Kustomize overlays
• New: Helm chart with values files for environment-specific configuration

3. Directory Structure

• Old: infrastructure/platform/mail/mailu/{base,overlays/{dev,prod}}
• New: infrastructure/platform/mail/mailu-helm/{dev,prod}

4. Ingress Configuration

• Old: Ingress resources created as part of the Kustomize setup
• New: Built-in ingress disabled in Helm chart to work with existing ingress controller

Updated Service References

The following configurations have been updated to use the new Helm service names:

Ingress Configuration

The Mailu Helm chart has been configured to work with your existing ingress setup:

• ingress.enabled: false: Disables the chart's built-in Ingress creation
• tlsFlavorOverride: notls: Tells Mailu's internal NGINX not to enforce TLS, as your Ingress handles TLS termination
• realIpHeader: X-Forwarded-For: Ensures Mailu's NGINX logs and processes the correct client IPs from behind your Ingress
• realIpFrom: 0.0.0.0/0: Trusts all proxies (restrict to your Ingress pod CIDR for security)

Required Ingress Resource

You need to create an Ingress resource to route traffic to Mailu. Here's an example:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: mailu-ingress
  namespace: bakery-ia  # Same as Mailu's namespace
  annotations:
    kubernetes.io/ingress.class: nginx  # Or your Ingress class
    nginx.ingress.kubernetes.io/proxy-body-size: "100m"  # Allow larger email attachments
    nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"  # For long connections
    nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
    nginx.ingress.kubernetes.io/force-ssl-redirect: "true"  # Redirect HTTP to HTTPS
    # If using Cert-Manager: cert-manager.io/cluster-issuer: "letsencrypt-prod"
spec:
  tls:
  - hosts:
    - mail.bakery-ia.local  # or mail.bakewise.ai for prod
    secretName: mail-tls-secret  # Your TLS Secret
  rules:
  - host: mail.bakery-ia.local  # or mail.bakewise.ai for prod
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: mailu-front-http  # Mailu's front service (check with kubectl get svc -n bakery-ia)
            port:
              number: 80

Apply it: kubectl apply -f ingress.yaml.

This routes all traffic from https://mail.[domain]/ to Mailu's internal NGINX, which proxies to webmail (/webmail), admin (/admin), etc.

Updated Service References

The following configurations have been updated to use the new Helm service names:

Common ConfigMap

• SMTP_HOST changed from email-smtp.bakery-ia.svc.cluster.local to mailu-postfix.bakery-ia.svc.cluster.local

SigNoz Configuration

• signoz_smtp_host changed from email-smtp.bakery-ia.svc.cluster.local to mailu-postfix.bakery-ia.svc.cluster.local
• smtp_smarthost changed from email-smtp.bakery-ia.svc.cluster.local:587 to mailu-postfix.bakery-ia.svc.cluster.local:587

Deployment Process

Prerequisites

1. Helm 3.x installed
2. Access to Kubernetes cluster
3. Namespace bakery-ia exists

Deployment Commands

For Development:

# Add Mailu Helm repository
helm repo add mailu https://mailu.github.io/helm-charts/
helm repo update

# Install Mailu for development
helm upgrade --install mailu-dev mailu/mailu \
  --namespace bakery-ia \
  --create-namespace \
  --values infrastructure/platform/mail/mailu-helm/values.yaml \
  --values infrastructure/platform/mail/mailu-helm/dev/values.yaml

For Production:

# Add Mailu Helm repository
helm repo add mailu https://mailu.github.io/helm-charts/
helm repo update

# Install Mailu for production
helm upgrade --install mailu-prod mailu/mailu \
  --namespace bakery-ia \
  --create-namespace \
  --values infrastructure/platform/mail/mailu-helm/values.yaml \
  --values infrastructure/platform/mail/mailu-helm/prod/values.yaml

Critical Configuration Preservation

All critical configurations from the original Kustomize setup have been preserved:

• Domain and hostname settings
• External SMTP relay configuration (Mailgun)
• Redis integration with shared cluster
• Database connection settings
• TLS certificate management
• Resource limits and requests
• Network policies
• Storage configuration (10Gi PVC)

Rollback Procedure

If rollback to the Kustomize setup is needed:

1. Uninstall the Helm release:

   helm uninstall mailu-dev -n bakery-ia  # or mailu-prod
   

2. Revert the configuration changes in infrastructure/environments/common/configs/configmap.yaml and infrastructure/monitoring/signoz/signoz-values-prod.yaml

3. Deploy the old Kustomize manifests:

   kubectl apply -k infrastructure/platform/mail/mailu/overlays/dev
   # or
   kubectl apply -k infrastructure/platform/mail/mailu/overlays/prod
   

Verification Steps

After deployment, verify the following:

1. Check that all Mailu pods are running:

   kubectl get pods -n bakery-ia | grep mailu
   

2. Verify SMTP connectivity from other services:

   # Test from a pod in the same namespace
   kubectl run test-smtp --image=curlimages/curl -n bakery-ia --rm -it -- \
     nc -zv mailu-postfix.bakery-ia.svc.cluster.local 587
   

3. Check that notification service can send emails:

   kubectl logs -n bakery-ia deployment/notification-service | grep -i smtp
   

4. Verify web interface accessibility:

   kubectl port-forward -n bakery-ia svc/mailu-front 8080:80
   # Then visit http://localhost:8080/admin
   

Known Issues

1. During migration, existing email data should be backed up before uninstalling the old deployment
2. DNS records may need to be updated to point to the new service endpoints
3. Some custom configurations may need to be reapplied after Helm installation

Support

For issues with the new Helm-based deployment:

1. Check the official Mailu Helm chart documentation
2. Review Helm release status: helm status mailu-[dev|prod] -n bakery-ia
3. Check pod logs: kubectl logs -n bakery-ia deployment/[mailu-postfix|mailu-front|etc.]
4. Verify network connectivity between services