Enable Optional Components#

How to enable or disable optional Mailu components based on your requirements.

Problem#

You need to add optional features like webmail, antivirus scanning, CalDAV/CardDAV, or external email fetching to your Mailu deployment.

Solution#

The MailuChart accepts a components configuration object that controls which optional components are deployed. Core components (front, admin, postfix, dovecot, rspamd) are always enabled.

Component Overview#

Core Components (Always Enabled)#

Component

Purpose

Can Disable?

Front

Nginx reverse proxy

No (required)

Admin

Web admin interface

No (required)

Postfix

SMTP server

No (required)

Dovecot

IMAP/POP3 server

No (required)

Rspamd

Spam filter

No (required)

Optional Components (Disabled by Default)#

Component

Purpose

Resource Cost

Use Case

Webmail

Roundcube web interface

Low (100m/256Mi)

Web-based email access

ClamAV

Antivirus scanner

High (1000m/2Gi)

Virus scanning

Fetchmail

External account fetching

Low (50m/128Mi)

Consolidate external emails

Webdav

CalDAV/CardDAV server

Low (50m/128Mi)

Calendar/contact sync

Enable Webmail (Roundcube)#

Add browser-based email access for users:

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',

  // ... other config ...

  components: {
    webmail: true,  // Enable Roundcube webmail
  },
});

app.synth();

Access webmail: Navigate to https://mail.example.com/webmail (or your configured ingress hostname).

Features:

  • Modern web interface for email

  • Contact management

  • Message filters and folders

  • Mobile-responsive design

Resources: ~100m CPU, 256Mi memory (lightweight)

Enable ClamAV (Antivirus)#

⚠️ Warning: ClamAV is very resource-intensive. Only enable if virus scanning is a hard requirement.

components: {
  clamav: true,
},

// ClamAV requires additional storage for virus signatures
storage: {
  storageClass: 'longhorn',
  clamav: { size: '10Gi' },  // Virus signature database
},

// Recommend higher resources for ClamAV
resources: {
  clamav: {
    requests: { cpu: '1000m', memory: '2Gi' },
    limits: { cpu: '4000m', memory: '4Gi' },
  },
},

Startup time: 5-10 minutes (downloads virus signatures on first start)

Resources: ~1000m CPU, 2Gi memory (very high)

Consider alternatives:

  • Server-side scanning may not be necessary if users have endpoint antivirus

  • Cloud-based scanning services (external)

  • SPF/DKIM/DMARC for spam prevention (already included in Rspamd)

Enable Fetchmail (External Account Fetching)#

Pull emails from external POP3/IMAP accounts into Mailu:

components: {
  fetchmail: true,
},

Use case: Consolidate multiple external email accounts (Gmail, Yahoo, etc.) into your Mailu server.

Configuration: After enabling, configure fetch rules via Mailu admin UI:

  1. Login to Mailu admin: https://mail.example.com/admin

  2. Navigate to Fetch section

  3. Add external account credentials and fetch rules

Resources: ~50m CPU, 128Mi memory (minimal)

Enable Webdav (CalDAV/CardDAV)#

Add calendar and contact synchronization:

components: {
  webdav: true,
},

// Webdav requires storage for calendar/contact data
storage: {
  storageClass: 'longhorn',
  webdav: { size: '20Gi' },  // Adjust based on user count
},

Access:

  • CalDAV: https://mail.example.com/webdav/<username>/calendar

  • CardDAV: https://mail.example.com/webdav/<username>/contacts

Compatible clients:

  • Thunderbird (Lightning plugin)

  • Apple Calendar and Contacts

  • Android (DAVx⁵ app)

  • iOS native calendar/contacts

Resources: ~50m CPU, 128Mi memory (minimal)

Enable Multiple Optional Components#

Combine multiple optional features:

components: {
  webmail: true,    // Web-based email access
  fetchmail: true,  // External account consolidation
  webdav: true,     // Calendar and contacts
  clamav: false,    // Explicitly disabled (high resources)
},

storage: {
  storageClass: 'longhorn',
  webdav: { size: '20Gi' },
  // ClamAV storage not needed (disabled)
},

Disable Optional Components#

Optional components are disabled by default. Explicitly set to false if needed:

components: {
  webmail: false,   // Disable webmail
  clamav: false,    // Disable antivirus
  fetchmail: false, // Disable external fetching
  webdav: false,    // Disable CalDAV/CardDAV
},

Note: Core components (front, admin, postfix, dovecot, rspamd) cannot be disabled.

Apply Component Changes#

After modifying component configuration:

# Regenerate manifests
npm run synth

# Apply changes
kubectl apply -f dist/mailu.k8s.yaml

# Watch new pods starting
kubectl get pods -n mailu -w

Adding components: New deployments and services will be created.

Removing components: Existing deployments and services will be deleted. PVCs are retained (manual cleanup required if desired).

Verify Component Status#

Check which components are running:

# List all Mailu pods
kubectl get pods -n mailu

# Expected pods with all optional components enabled:
# - mailu-front-*
# - mailu-admin-*
# - mailu-postfix-*
# - mailu-dovecot-*
# - mailu-rspamd-*
# - mailu-webmail-*        (if webmail enabled)
# - mailu-clamav-*         (if clamav enabled)
# - mailu-fetchmail-*      (if fetchmail enabled)
# - mailu-webdav-*         (if webdav enabled)

# Check services
kubectl get svc -n mailu

Component-Specific Configuration#

Webmail Type (Roundcube vs SnappyMail)#

Choose webmail client (Roundcube is default):

components: {
  webmail: true,
},

mailu: {
  webmailType: 'roundcube',  // or 'snappymail'
},

Roundcube: Traditional, mature, full-featured PHP webmail (recommended).

SnappyMail: Modern, lightweight alternative.

Resource Planning#

Estimate total resource requirements with optional components:

Minimal Deployment (Core Only)#

Total resources:

  • CPU requests: ~650m

  • Memory requests: ~2.5Gi

components: {
  // All optional components disabled (default)
},

Troubleshooting#

ClamAV pod stuck in CrashLoopBackOff#

Symptom: ClamAV pod fails to start with OOMKilled or initialization timeout.

Solution: Increase memory limits:

resources: {
  clamav: {
    requests: { cpu: '1000m', memory: '2Gi' },
    limits: { cpu: '4000m', memory: '4Gi' },  // Increased
  },
},

Also ensure storage is adequate for virus signature database:

# Check PVC size
kubectl get pvc -n mailu | grep clamav

Webmail not accessible#

Symptom: 404 Not Found when accessing /webmail URL.

Solution: Verify webmail component is enabled and pod is running:

# Check webmail pod status
kubectl get pods -n mailu | grep webmail

# Check webmail pod logs
kubectl logs -n mailu -l app.kubernetes.io/component=webmail

# Check service discovery
kubectl get configmap -n mailu mailu-config -o yaml | grep WEBMAIL

Fetchmail not pulling emails#

Symptom: External emails not appearing in Mailu mailboxes.

Solution: Check fetchmail configuration in admin UI and pod logs:

# Check fetchmail pod logs
kubectl logs -n mailu -l app.kubernetes.io/component=fetchmail

# Verify fetch rules configured in admin UI
# Navigate to https://mail.example.com/admin → Fetch

See Also#