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

# Mailu Helm Chart for Bakery-IA

This directory contains the Helm chart configuration for Mailu, replacing the previous Kustomize-based setup.

## Overview

The Mailu email server is now deployed using the official Mailu Helm chart instead of Kustomize manifests. This provides better maintainability, easier upgrades, and standardized configuration. The setup is configured to work behind your existing Ingress controller (NGINX), with the internal Mailu NGINX acting as a proxy for services like webmail while your existing Ingress handles traffic routing, TLS termination, and forwarding to Mailu's internal NGINX on HTTP (port 80).

## Directory Structure

```
mailu-helm/
├── values.yaml          # Base configuration values
├── dev/
│   └── values.yaml      # Development-specific overrides
├── prod/
│   └── values.yaml      # Production-specific overrides
└── mailu-ingress.yaml   # Sample ingress configuration for use with existing ingress
```

## Critical Configuration Preservation

The following critical configurations from the original Kustomize setup have been preserved:

- **Domain settings**: Domain and hostnames for both dev and prod
- **External relay**: Mailgun SMTP relay configuration
- **Redis integration**: Connection to shared Redis cluster (database 15)
- **Database settings**: PostgreSQL connection details
- **Resource limits**: CPU and memory requests/limits matching original setup
- **Network policies**: Security policies restricting access to authorized services
- **Storage**: 10Gi persistent volume for mail data
- **Ingress configuration**: Built-in ingress disabled to work with existing ingress

## Deployment

### Prerequisites

1. Helm 3.x installed
2. Kubernetes cluster with storage provisioner
3. Ingress controller (NGINX) - already deployed in your cluster
4. Cert-manager for TLS certificates (optional, depends on your ingress setup)
5. External SMTP relay account (Mailgun)

### Deployment Commands

#### For Development:
```bash
helm repo add mailu https://mailu.github.io/helm-charts/
helm repo update
helm install mailu-dev mailu/mailu \
  --namespace bakery-ia \
  --create-namespace \
  --values mailu-helm/values.yaml \
  --values mailu-helm/dev/values.yaml
```

#### For Production:
```bash
helm repo add mailu https://mailu.github.io/helm-charts/
helm repo update
helm install mailu-prod mailu/mailu \
  --namespace bakery-ia \
  --create-namespace \
  --values mailu-helm/values.yaml \
  --values mailu-helm/prod/values.yaml
```

### Upgrading

To upgrade to a newer version of the Mailu Helm chart:
```bash
helm repo update
helm upgrade mailu-dev mailu/mailu \
  --namespace bakery-ia \
  --values mailu-helm/values.yaml \
  --values mailu-helm/dev/values.yaml
```

## Ingress Configuration

The Mailu Helm chart is 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.dev  # or mail.bakewise.ai for prod
    secretName: mail-tls-secret  # Your TLS Secret
  rules:
  - host: mail.bakery-ia.dev  # 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.

## Configuration Details

### Environment-Specific Values

- **Development** (`dev/values.yaml`):
  - Domain: `bakery-ia.local`
  - No TLS enforcement internally (handled by ingress)
  - Disabled antivirus to save resources
  - Debug logging level

- **Production** (`prod/values.yaml`):
  - Domain: `bakewise.ai`
  - No TLS enforcement internally (handled by ingress)
  - Enabled antivirus
  - Warning logging level

### Secrets Management

Sensitive values like passwords and API keys should be managed through Kubernetes secrets rather than being stored in the values files. The Helm chart supports referencing existing secrets for:

- Database passwords
- Redis passwords
- External relay credentials
- Mailu secret key

## Integration with Notification Service

The notification service continues to connect to Mailu via the internal service name `mailu-postfix.bakery-ia.svc.cluster.local` on port 587 with STARTTLS.

## Access Information

- **Admin Panel**: `https://mail.[domain]/admin`
- **Webmail**: `https://mail.[domain]/webmail`
- **SMTP**: `mail.[domain]:587` (STARTTLS) - handled via separate TCP services if needed
- **IMAP**: `mail.[domain]:993` (SSL/TLS) - handled via separate TCP services if needed

## Migration Notes

When migrating from the Kustomize setup to Helm:

1. Ensure all existing PVCs are preserved during migration
2. Export any existing mail data before migration if needed
3. Update any hardcoded service references in other deployments
4. Verify that network policies still allow necessary communications
5. Configure your existing ingress to route traffic to the Mailu services