Manage Secrets¶

How to create and manage Kubernetes secrets required by Mailu.

Problem¶

Mailu requires several secrets for secure operation: application secret keys, database credentials, Redis passwords, and initial admin passwords. You need to create these secrets before deploying Mailu.

Solution¶

Create Kubernetes Secret resources containing sensitive data, then reference them in the MailuChart configuration. Never commit secrets to git or include them in CDK8S code.

Understanding Secret Requirements¶

Mailu requires these secrets (minimum):

Secret Purpose	Required?	Secret Name (configurable)	Keys
Mailu secret key	Yes	`mailu-secrets`	`secret-key`
Database credentials	Yes (if PostgreSQL)	`postgres-app`	`username`, `password`
Initial admin password	Yes (recommended)	`mailu-secrets`	`password`
Redis password	No (if Redis auth disabled)	`redis-password`	`password`
API token	No (if API disabled)	`mailu-api-token`	`api-token`

Create Mailu Secret Key¶

The Mailu secret key is used for session encryption and must be a random 16-character string.

Generate Random Secret Key¶

# Generate 16-character random key
SECRET_KEY=$(head -c 16 /dev/urandom | base64 | tr -d '=' | cut -c1-16)
echo $SECRET_KEY

Create Secret¶

kubectl create secret generic mailu-secrets \
  --namespace=mailu \
  --from-literal=secret-key="$SECRET_KEY"

Verify:

kubectl get secret -n mailu mailu-secrets
kubectl describe secret -n mailu mailu-secrets

Create Initial Admin Password¶

Generate a secure password for the initial admin account:

# Generate strong random password
ADMIN_PASSWORD=$(head -c 24 /dev/urandom | base64 | tr -d '=' | cut -c1-24)
echo "Admin password: $ADMIN_PASSWORD"

# Add password to existing mailu-secrets
kubectl create secret generic mailu-secrets \
  --namespace=mailu \
  --from-literal=secret-key="$SECRET_KEY" \
  --from-literal=password="$ADMIN_PASSWORD" \
  --dry-run=client -o yaml | kubectl apply -f -

Important: Save this password securely (password manager). You’ll need it to login to the admin UI after deployment.

Create Database Credentials Secret¶

For PostgreSQL (Recommended)¶

If using CloudNativePG (CNPG) or another PostgreSQL operator, the secret is usually auto-generated. Reference the existing secret:

database: {
  type: 'postgresql',
  postgresql: {
    host: 'postgres-pooler',  // CNPG pooler service
    port: 5432,
    database: 'mailu',
    secretName: 'postgres-app',  // CNPG auto-generated secret
    secretKeys: {
      username: 'username',
      password: 'password',
    },
  },
}

Manual PostgreSQL: Create the secret yourself:

kubectl create secret generic postgres-credentials \
  --namespace=mailu \
  --from-literal=username="mailu" \
  --from-literal=password="$(head -c 32 /dev/urandom | base64 | tr -d '=')"

Reference in CDK8S:

database: {
  type: 'postgresql',
  postgresql: {
    host: 'postgres-service',
    secretName: 'postgres-credentials',
    secretKeys: {
      username: 'username',
      password: 'password',
    },
  },
}

For SQLite (Not Recommended for Production)¶

No database secret needed (SQLite file stored in admin PVC):

database: {
  type: 'sqlite',
}

Create Redis Password Secret (Optional)¶

If your Redis instance requires authentication:

kubectl create secret generic redis-password \
  --namespace=mailu \
  --from-literal=password="$(head -c 32 /dev/urandom | base64 | tr -d '=')"

Reference in CDK8S:

redis: {
  host: 'redis',
  port: 6379,
  secretName: 'redis-password',
  secretKey: 'password',
}

If Redis has no authentication (cluster-internal only):

redis: {
  host: 'redis',
  port: 6379,
  // No secretName needed
}

Example: Complete Secret Setup¶

Script to create all required secrets at once:

#!/bin/bash
set -e

NAMESPACE="mailu"

echo "Creating Mailu secrets..."

# Generate random values
SECRET_KEY=$(head -c 16 /dev/urandom | base64 | tr -d '=' | cut -c1-16)
ADMIN_PASSWORD=$(head -c 24 /dev/urandom | base64 | tr -d '=' | cut -c1-24)
DB_PASSWORD=$(head -c 32 /dev/urandom | base64 | tr -d '=')

echo "Generated credentials:"
echo "  SECRET_KEY: $SECRET_KEY"
echo "  ADMIN_PASSWORD: $ADMIN_PASSWORD"
echo "  (Save these securely!)"
echo ""

# Create namespace
kubectl create namespace $NAMESPACE --dry-run=client -o yaml | kubectl apply -f -

# Mailu application secrets
kubectl create secret generic mailu-secrets \
  --namespace=$NAMESPACE \
  --from-literal=secret-key="$SECRET_KEY" \
  --from-literal=password="$ADMIN_PASSWORD" \
  --dry-run=client -o yaml | kubectl apply -f -

# Database credentials (if not using CNPG auto-generated)
kubectl create secret generic postgres-credentials \
  --namespace=$NAMESPACE \
  --from-literal=username="mailu" \
  --from-literal=password="$DB_PASSWORD" \
  --dry-run=client -o yaml | kubectl apply -f -

echo "Secrets created successfully!"
kubectl get secrets -n $NAMESPACE

Save as create-mailu-secrets.sh, make executable, and run:

chmod +x create-mailu-secrets.sh
./create-mailu-secrets.sh

Configure Secrets in CDK8S¶

After creating secrets, reference them in your MailuChart:

import { App } from 'cdk8s';
import { MailuChart } from 'cdk8s-mailu';

const app = new App();

new MailuChart(app, 'mailu', {
  namespace: 'mailu',
  domain: 'example.com',
  hostnames: ['mail.example.com'],
  subnet: '10.42.0.0/16',
  timezone: 'UTC',

  // Reference secrets (not values!)
  secrets: {
    mailuSecretKey: 'mailu-secrets',           // Secret with 'secret-key' field
    initialAdminPassword: 'mailu-secrets',     // Secret with 'password' field
    apiToken: 'mailu-api-token',               // Optional, if API enabled
  },

  database: {
    type: 'postgresql',
    postgresql: {
      host: 'postgres-pooler',
      port: 5432,
      database: 'mailu',
      secretName: 'postgres-app',              // Database credentials
      secretKeys: {
        username: 'username',
        password: 'password',
      },
    },
  },

  redis: {
    host: 'redis',
    port: 6379,
    // secretName: 'redis-password',           // Uncomment if Redis requires auth
    // secretKey: 'password',
  },
});

app.synth();

Rotate Secrets¶

Rotate Mailu Secret Key¶

Warning: Rotating the secret key invalidates all user sessions. Users must re-login.

# Generate new key
NEW_SECRET_KEY=$(head -c 16 /dev/urandom | base64 | tr -d '=' | cut -c1-16)

# Update secret
kubectl create secret generic mailu-secrets \
  --namespace=mailu \
  --from-literal=secret-key="$NEW_SECRET_KEY" \
  --from-literal=password="<existing-admin-password>" \
  --dry-run=client -o yaml | kubectl apply -f -

# Restart admin pods to pick up new secret
kubectl rollout restart deployment -n mailu mailu-admin

Rotate Database Password¶

Caution: Requires updating both database and Mailu secret simultaneously.

# Step 1: Update password in PostgreSQL
kubectl exec -n postgres postgres-1 -- psql -U postgres -c "ALTER USER mailu PASSWORD 'new-password';"

# Step 2: Update Kubernetes secret
kubectl create secret generic postgres-credentials \
  --namespace=mailu \
  --from-literal=username="mailu" \
  --from-literal=password="new-password" \
  --dry-run=client -o yaml | kubectl apply -f -

# Step 3: Restart Mailu admin pod
kubectl rollout restart deployment -n mailu mailu-admin

Use External Secret Management¶

For production, consider using external secret management with External Secrets Operator:

Example: Sync from HashiCorp Vault¶

apiVersion: external-secrets.io/v1beta1
kind: SecretStore
metadata:
  name: vault-backend
  namespace: mailu
spec:
  provider:
    vault:
      server: "https://vault.example.com"
      path: "secret"
      version: "v2"
      auth:
        kubernetes:
          mountPath: "kubernetes"
          role: "mailu"
---
apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: mailu-secrets-external
  namespace: mailu
spec:
  refreshInterval: 1h
  secretStoreRef:
    name: vault-backend
    kind: SecretStore
  target:
    name: mailu-secrets
    creationPolicy: Owner
  data:
    - secretKey: secret-key
      remoteRef:
        key: mailu/secret-key
    - secretKey: password
      remoteRef:
        key: mailu/admin-password

Verify Secret Usage¶

Check if secrets are correctly mounted to pods:

# Check admin pod environment
kubectl exec -n mailu <admin-pod-name> -- env | grep SECRET_KEY

# Should show: SECRET_KEY=<your-secret-key>

# Check database connection
kubectl logs -n mailu <admin-pod-name> | grep -i database

# Should show successful database connection

Troubleshooting¶

Secret not found error¶

Symptom: Pod shows CreateContainerConfigError with message about missing secret.

# Check secret exists
kubectl get secret -n mailu <secret-name>

# Check secret has correct keys
kubectl get secret -n mailu <secret-name> -o jsonpath='{.data}' | jq

Solution: Create the missing secret or fix the secret name in your CDK8S configuration.

Database authentication failed¶

Symptom: Admin pod logs show “authentication failed” or “password authentication failed for user”.

# Check database secret
kubectl get secret -n mailu <db-secret-name> -o jsonpath='{.data.password}' | base64 -d

# Test database connection manually
kubectl exec -n mailu <admin-pod> -- psql -h <db-host> -U <username> -d mailu

Solution: Verify database password matches between Kubernetes secret and PostgreSQL database.

Admin login fails after deployment¶

Symptom: Cannot login to admin UI with generated password.

Common causes:

Initial admin account not created (check mailu.initialAccount config)
Password secret not mounted correctly
Wrong username (should be configured username @ domain)

Solution: Check admin pod logs for initial account creation:

kubectl logs -n mailu <admin-pod> | grep -i "initial admin"

Security Best Practices¶

Never commit secrets to git - Use .gitignore for secret files
Use strong random passwords - At least 24 characters for admin passwords
Rotate secrets regularly - Especially after employee turnover
Limit secret access - Use Kubernetes RBAC to restrict secret read permissions
Use external secret management - Vault, AWS Secrets Manager, etc. for production
Encrypt etcd - Enable etcd encryption at rest in your Kubernetes cluster
Audit secret access - Enable audit logging for secret operations