cdk8s-mailu

CDK8S construct library for deploying Mailu mail server to Kubernetes

📚 Full Documentation | Quick Start | Architecture

Overview

cdk8s-mailu is a CDK8S construct library that provides a type-safe, production-grade way to deploy Mailu mail server to Kubernetes. Generate complete Kubernetes manifests from TypeScript code with compile-time validation and IDE autocomplete.

Why cdk8s-mailu?

• Type-Safe Configuration - Catch errors at compile time, not deploy time
• Production-Grade Defaults - Resource limits and storage sizes based on real deployments
• Modular Architecture - Enable/disable components with simple flags
• Dedicated Dovecot Submission Service - Solves webmail email sending with clean architecture
• Well-Documented - Comprehensive documentation following Diátaxis framework
• Battle-Tested - Production deployment at kup6s.com with AMD64/ARM64 mixed nodes

See Complete Architecture →

Installation

npm install cdk8s-mailu
# or
yarn add cdk8s-mailu

Prerequisites: Kubernetes 1.28+, PostgreSQL, Redis, Node.js 18+

Full Prerequisites →

Quick Start

Create mailu.ts:

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',  // Your Kubernetes pod CIDR
  timezone: 'UTC',

  database: {
    type: 'postgresql',
    postgresql: {
      host: 'postgres-rw',
      port: 5432,
      database: 'mailu',
      secretName: 'postgres-app',
      secretKeys: {
        username: 'username',
        password: 'password',
      },
    },
  },

  redis: {
    host: 'redis',
    port: 6379,
  },

  secrets: {
    mailuSecretKey: 'mailu-secrets',
    initialAdminPassword: 'mailu-secrets',
  },

  components: {
    webmail: true,   // Roundcube webmail
    clamav: false,   // Antivirus (requires ~1GB RAM)
  },

  storage: {
    storageClass: 'longhorn',
    dovecot: { size: '50Gi' },  // Mailbox storage
  },

  // Optional: Traefik ingress (requires Traefik installed)
  ingress: {
    enabled: true,
    type: 'traefik',
    traefik: {
      hostname: 'mail.example.com',
      certIssuer: 'letsencrypt-cluster-issuer',
      enableTcp: true,  // SMTP/IMAP/POP3 routes
    },
  },
});

app.synth();

Generate and deploy:

npx ts-node mailu.ts
kubectl apply -f dist/mailu.k8s.yaml

Complete Tutorial with Secrets & DNS →

Documentation

Comprehensive documentation following the Diátaxis framework:

📘 Tutorials - Learn by doing

• Quick Start: Deploy Your First Instance

🔧 How-To Guides - Practical solutions

• Configure components
• Customize resources
• Set up TLS termination

💡 Explanation - Understanding the design

• Architecture Overview - Component relationships and CDK8S patterns
• Dovecot Submission Service - How webmail email sending works
• CDK8S Patterns - Construct design patterns

📚 Reference - Technical specifications

• Configuration API reference
• Component options
• Resource defaults

Development

npm run build      # Compile + test + synth
npm run test       # Run tests (>96% coverage)
npm run synth      # Generate manifests only

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

Apache License 2.0 - see LICENSE file for details.

Acknowledgments

• Mailu - The mail server software
• CDK8S - Cloud Development Kit for Kubernetes

---

📚 Full Documentation | 🚀 Quick Start | 🏗️ Architecture