Storage Architecture

Understanding persistent storage requirements and configuration in cdk8s-mailu deployments.

Introduction

cdk8s-mailu components require persistent storage for:

  • Mail data: User mailboxes (largest storage requirement)

  • Configuration state: DKIM keys, learned spam patterns, virus signatures

  • Operational queues: Mail queues, temporary files

  • Application data: Database, Roundcube attachments, calendars/contacts

This document explains what each component stores, sizing recommendations, and storage class considerations.

Storage Components Overview

Component

Storage Type

Purpose

Typical Size

Growth Rate

Admin

PVC

DKIM keys, admin data

1-5Gi

Low (static)

Postfix

PVC

Mail queue, spool files

5-20Gi

Medium (transient)

Dovecot

PVC

User mailboxes (emails)

50-500Gi

High (user dependent)

Rspamd

PVC

Learned spam patterns

1-5Gi

Low (limited by bayes expiry)

ClamAV

PVC

Virus signature database

2-5Gi

Low (signatures rotate)

Webmail

PVC

Roundcube session data

1-5Gi

Low (session expiry)

WebDAV

PVC

Calendars and contacts

5-50Gi

Medium (user dependent)

External Storage (not in cdk8s-mailu scope):

  • PostgreSQL: Admin database, user accounts, domains, aliases (managed separately)

  • Redis: Caching, rate limiting state (ephemeral, can use emptyDir)

Component Storage Details

Admin Storage

What is stored:

  • DKIM private keys: One key per domain (RSA 2048-bit, ~1.6KB each)

  • Admin instance data: Configuration state, logs

  • SQLite database (if not using PostgreSQL): User accounts, domains, aliases

Size calculation:

  • 100 domains × 2KB DKIM keys = 200MB

  • SQLite database (if used): 100-500MB for thousands of users

  • Logs and state: 100-500MB

  • Recommended minimum: 1Gi

  • Typical deployment: 2-5Gi

Growth pattern:

  • Mostly static after initial setup

  • DKIM keys only added when new domains are created

  • SQLite grows slowly with user/domain additions

Access pattern:

  • Low I/O (read DKIM keys on message signing)

  • Not performance-critical

StorageClass considerations:

  • Standard HDD storage acceptable

  • No need for high-IOPS SSD

  • Backup recommended (losing DKIM keys breaks DKIM signatures)

Postfix Storage

What is stored:

  • Mail queue: Outgoing and deferred messages awaiting delivery

  • Spool directory: Temporary files during message processing

  • Postfix state: Queue manager state, TLS session cache

Size calculation:

  • Active queue: Typically <100MB (messages deliver quickly)

  • Deferred queue: Can grow to 1-10GB if remote servers are down

  • Recommended minimum: 5Gi

  • High-volume sites: 20Gi

Growth pattern:

  • Highly variable (depends on delivery success rate)

  • Grows when remote mail servers are unreachable

  • Shrinks as deferred messages are retried and delivered

  • Queue should drain to near-zero in healthy operation

Access pattern:

  • High I/O during message processing

  • Many small files (one per queued message)

  • Random read/write access

StorageClass considerations:

  • SSD recommended for high-volume sites (>10k messages/day)

  • Low-latency storage improves queue processing speed

  • HDD acceptable for low-volume (<1k messages/day)

  • Backup not critical (queued messages are transient)

Dovecot Storage

What is stored:

  • User mailboxes: All received emails for all users

  • Mail indexes: Dovecot index files for fast IMAP access

  • Mailbox metadata: Folder subscriptions, flags, seen state

Size calculation (most critical sizing decision):

  • Per-user estimate: 1-10GB (varies widely by usage)

  • Example: 100 users × 5GB average = 500GB

  • Growth: 100-500MB per user per year (typical)

  • Overhead: Indexes add ~5-10% to mail size

  • Recommended: Start with 2-3× current mail size for growth

Growth pattern:

  • Continuous linear growth (users receive mail daily)

  • Rate depends on user behavior and retention policies

  • Can implement quota limits to control growth

Access pattern:

  • High I/O (IMAP clients sync frequently)

  • Mix of sequential (reading messages) and random (searching)

  • Index files heavily accessed

StorageClass considerations:

  • SSD strongly recommended (IMAP performance critical)

  • High IOPS needed for responsive webmail/IMAP

  • Consider tiered storage: Hot (SSD) + Cold (HDD archive)

  • Backup essential (user mail is irreplaceable)

  • Snapshots recommended for quick recovery

Special considerations:

  • Largest storage consumer in Mailu deployment

  • Plan for 3-5 year growth horizon

  • Monitor closely and expand proactively

  • Consider retention policies to limit growth

Rspamd Storage

What is stored:

  • Bayes spam classifier: Learned tokens from spam/ham training

  • Fuzzy hashes: Spam signatures for fuzzy matching

  • Statistics: Spam detection statistics and metadata

Size calculation:

  • Bayes database: 500MB - 2GB (depends on training corpus)

  • Fuzzy storage: 100-500MB

  • Statistics and logs: 100-500MB

  • Recommended minimum: 2Gi

  • Typical deployment: 5Gi

Growth pattern:

  • Grows initially as spam/ham is learned

  • Stabilizes after training (bayes token expiry limits size)

  • Old tokens are expired automatically (typically 30-90 days)

Access pattern:

  • High read I/O during spam scanning

  • Low write I/O (only on learning/updates)

  • Sequential reads (token lookups)

StorageClass considerations:

  • SSD beneficial but not critical

  • Fast reads improve spam scanning speed

  • HDD acceptable for low-volume sites

  • Backup recommended (losing training means relearning)

ClamAV Storage (Optional Component)

What is stored:

  • Virus signature database: ClamAV definitions (updated daily)

  • Temporary scan files: Extracted attachments during scanning

Size calculation:

  • Signature database: 1-3GB (compressed)

  • Temporary files: 100-500MB (transient)

  • Recommended minimum: 3Gi

  • Typical deployment: 5Gi

Growth pattern:

  • Signature database grows slowly (~100MB/year)

  • Daily updates replace old signatures

  • Size relatively stable

Access pattern:

  • High read I/O during virus scanning

  • Sequential reads (scanning attachments)

  • Daily write for signature updates

StorageClass considerations:

  • SSD improves scan speed (reduces mail delay)

  • HDD acceptable for small deployments

  • Backup not critical (signatures can be re-downloaded)

Webmail Storage (Optional Component)

What is stored:

  • Roundcube database (if not using PostgreSQL): Sessions, preferences, cache

  • Temporary files: Attachment uploads during composition

  • Session data: Active user sessions

Size calculation:

  • SQLite database: 100-500MB

  • Session data: 100MB per 1000 concurrent users

  • Temporary files: 100-500MB

  • Recommended minimum: 2Gi

  • Typical deployment: 5Gi

Growth pattern:

  • Grows with number of active sessions

  • Session data expires (typically 24-72 hours)

  • Size relatively stable after initial growth

Access pattern:

  • Medium I/O (session reads/writes)

  • Random access (session lookups)

StorageClass considerations:

  • SSD improves webmail responsiveness

  • HDD acceptable for low-concurrency (<100 users)

  • Backup not critical (sessions are transient)

WebDAV Storage (Optional Component)

What is stored:

  • CalDAV data: User calendars, events, todos

  • CardDAV data: Contact books, vcards

  • Radicale database: Collection metadata, sync tokens

Size calculation:

  • Per-user estimate: 10-100MB (calendars + contacts)

  • Example: 100 users × 50MB = 5GB

  • Recommended minimum: 5Gi

  • Typical deployment: 10-50Gi

Growth pattern:

  • Grows with user calendar/contact data

  • Slower than email growth (calendars are smaller)

  • Historical events accumulate over time

Access pattern:

  • Low-medium I/O (sync on schedule changes)

  • Random access (event lookups)

StorageClass considerations:

  • HDD acceptable (CalDAV/CardDAV not latency-sensitive)

  • SSD beneficial for large deployments (>500 users)

  • Backup recommended (user data is valuable)

Configuration in cdk8s-mailu

Storage Configuration Interface

Storage is configured in the MailuChartConfig.storage section:

import { MailuChart } from '@example/cdk8s-mailu';

new MailuChart(app, 'mailu', {
  // ... other config
  storage: {
    // Global default storage class
    storageClass: 'longhorn',

    // Per-component overrides
    admin: {
      size: '2Gi',
      storageClass: 'longhorn',  // Optional override
    },
    postfix: {
      size: '10Gi',
    },
    dovecot: {
      size: '200Gi',  // Largest allocation
      storageClass: 'longhorn-ssd',  // Use faster storage
    },
    rspamd: {
      size: '5Gi',
    },

    // Optional components (only used if enabled)
    clamav: {
      size: '5Gi',
    },
    webmail: {
      size: '3Gi',
    },
    webdav: {
      size: '20Gi',
    },
  },
});

Storage Class Selection

Global default (storage.storageClass):

  • Applied to all components unless overridden

  • Example: 'longhorn', 'standard', 'gp2'

Per-component override (storage.dovecot.storageClass):

  • Useful for tiered storage (SSD for Dovecot, HDD for others)

  • Example: High-performance SSD for Dovecot, standard HDD for Admin

Example tiered storage:

storage: {
  storageClass: 'longhorn',  // Default: Standard HDD

  dovecot: {
    size: '500Gi',
    storageClass: 'longhorn-ssd',  // Override: Fast SSD
  },
  postfix: {
    size: '20Gi',
    storageClass: 'longhorn-ssd',  // Override: Fast SSD
  },

  // Other components use default 'longhorn' HDD
  admin: { size: '2Gi' },
  rspamd: { size: '5Gi' },
}

Default Sizes (if not specified)

cdk8s-mailu uses these defaults when storage size is not configured:

  • Admin: 1Gi

  • Postfix: 10Gi

  • Dovecot: 50Gi (⚠️ likely too small for production)

  • Rspamd: 2Gi

  • ClamAV: 3Gi

  • Webmail: 2Gi

  • WebDAV: 5Gi

Recommendation: Always explicitly set storage sizes (don’t rely on defaults).

Sizing Recommendations by Deployment Size

Small Deployment (1-50 users)

storage: {
  storageClass: 'standard',
  admin: { size: '2Gi' },
  postfix: { size: '5Gi' },
  dovecot: { size: '50Gi' },      // 1GB per user
  rspamd: { size: '2Gi' },
  webmail: { size: '2Gi' },
  webdav: { size: '5Gi' },
}

Total: ~66Gi

Medium Deployment (50-500 users)

storage: {
  storageClass: 'longhorn',
  admin: { size: '5Gi' },
  postfix: { size: '10Gi' },
  dovecot: { size: '250Gi', storageClass: 'longhorn-ssd' },  // 500MB per user
  rspamd: { size: '5Gi' },
  clamav: { size: '5Gi' },
  webmail: { size: '5Gi' },
  webdav: { size: '25Gi' },
}

Total: ~305Gi (250Gi SSD, 55Gi HDD)

Large Deployment (500-5000 users)

storage: {
  storageClass: 'longhorn',
  admin: { size: '10Gi' },
  postfix: { size: '50Gi', storageClass: 'longhorn-ssd' },
  dovecot: { size: '2000Gi', storageClass: 'longhorn-ssd' },  // 400MB per user
  rspamd: { size: '10Gi' },
  clamav: { size: '5Gi' },
  webmail: { size: '10Gi' },
  webdav: { size: '100Gi' },
}

Total: ~2185Gi (2050Gi SSD, 135Gi HDD)

Storage Best Practices

1. Plan for Growth

  • Dovecot: Allocate 2-3× current mail size

  • Postfix: Size for 3-7 days of deferred queue

  • Monitor usage: Set alerts at 70% capacity

  • Expand proactively: Before hitting 85% full

2. Use Appropriate Storage Classes

  • Critical performance: Dovecot, Postfix → SSD

  • Moderate performance: Rspamd, ClamAV → SSD or fast HDD

  • Low performance: Admin, Webmail, WebDAV → HDD

3. Implement Backup Strategy

Essential backups:

  • Dovecot mailboxes (user mail data)

  • Admin DKIM keys

  • WebDAV calendars/contacts

Nice-to-have backups:

  • Rspamd learned patterns

  • PostgreSQL database

Not needed:

  • Postfix queue (transient)

  • ClamAV signatures (can re-download)

  • Webmail sessions (ephemeral)

4. Retention Policies

Implement policies to control growth:

  • User quotas: Limit per-user mailbox size

  • Auto-expunge: Delete trash/spam after 30 days

  • Archive policies: Move old mail to cheaper storage tiers

5. Monitoring and Alerts

Monitor these metrics:

  • PVC usage percentage (alert at 70%)

  • Growth rate (predict when expansion needed)

  • IOPS saturation (indicates need for faster storage)

# Check PVC usage
kubectl get pvc -n mailu
kubectl exec -n mailu <dovecot-pod> -- df -h /mail

# Monitor IOPS (if storage supports metrics)
kubectl top pod -n mailu --containers

Troubleshooting

PVC Full (Out of Space)

Symptoms:

  • Mail delivery failures

  • Dovecot errors: “Not enough disk space”

  • Postfix queue buildup

Immediate fix:

  1. Identify full PVC:

    kubectl exec -n mailu <pod> -- df -h

  2. Clean temporary files:

    # Postfix queue
kubectl exec -n mailu <postfix-pod> -- postqueue -p | grep -c "^[A-F0-9]"

# Dovecot indexes (can regenerate)
kubectl exec -n mailu <dovecot-pod> -- rm -rf /mail/*/dovecot.index*

  3. Expand PVC (if storage class supports it):

    kubectl patch pvc dovecot-pvc -n mailu -p '{"spec":{"resources":{"requests":{"storage":"300Gi"}}}}'

Long-term fix:

  • Implement user quotas

  • Enable auto-expunge policies

  • Plan capacity expansion

Slow Mail Access (Performance Issues)

Symptoms:

  • Slow IMAP sync

  • Webmail timeouts

  • Message delivery delays

Check:

  1. Verify storage class performance:

    kubectl get pvc -n mailu -o jsonpath='{.items[*].spec.storageClassName}'

  2. Check IOPS limits (cloud providers):

    • AWS EBS: Throughput based on volume size

    • Azure Disk: IOPS tier selection

  3. Monitor pod I/O wait:

    kubectl exec -n mailu <dovecot-pod> -- iostat -x 1 10

Fix:

  • Migrate to faster storage class (SSD)

  • Increase PVC size (some classes scale IOPS with size)

  • Optimize Dovecot indexes (rebuild corrupted indexes)

PVC Not Binding

Symptoms: Pod stuck in Pending, PVC shows “Pending”

Check:

  1. Verify storage class exists:

    kubectl get storageclass

  2. Check provisioner logs:

    kubectl logs -n kube-system -l app=<provisioner-name>

  3. Verify node resources (some storage requires specific node features)

Fix:

  • Correct storage class name typo

  • Install storage provisioner if missing

  • Check node selectors/taints

See Also