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

```yaml
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:
```bash
# 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:
```bash
# 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:
   ```bash
   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:
   ```bash
   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:
   ```bash
   kubectl get pods -n bakery-ia | grep mailu
   ```

2. Verify SMTP connectivity from other services:
   ```bash
   # 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:
   ```bash
   kubectl logs -n bakery-ia deployment/notification-service | grep -i smtp
   ```

4. Verify web interface accessibility:
   ```bash
   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](https://github.com/Mailu/helm-charts)
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