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)
},

Full-Featured Deployment (All Optional)

Total resources:

• CPU requests: ~1.9Gi (including ClamAV)

• Memory requests: ~5.1Gi (including ClamAV)

components: {
  webmail: true,
  clamav: true,
  fetchmail: true,
  webdav: true,
},

Recommended Deployment (Webmail + Webdav)

Total resources:

• CPU requests: ~800m (no ClamAV)

• Memory requests: ~2.9Gi (no ClamAV)

components: {
  webmail: true,
  fetchmail: false,  // Add if needed
  webdav: true,
  clamav: false,     // Skip unless required
},

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

• Component Specifications - Resource requirements per component

• Scale Resources - Adjust resource allocations

• Customize Storage - Configure PVC sizes

• Configure TLS - Set up ingress for webmail access