Deploying WildDuck

Introduction

WildDuck is a scalable, modern IMAP/POP3 mail server designed for high availability and security. Unlike traditional mail servers that rely on file-based mailbox storage, WildDuck uses MongoDB as its backend, enabling horizontal scaling and eliminating the complexity of distributed file systems.

Built with Node.js, WildDuck implements a complete email stack including IMAP, POP3, and SMTP services, along with a powerful REST API for email management. The server supports modern email features like DKIM signing, SPF validation, and built-in encryption at rest.

Key highlights of WildDuck:

• MongoDB Backend: All emails, attachments, and metadata are stored in MongoDB, enabling easy clustering and replication
• Horizontal Scaling: Deploy multiple WildDuck instances behind a load balancer for high availability
• REST API: Full-featured API for user management, mailbox operations, and email sending
• Built-in Encryption: Emails are encrypted at rest using GPG/PGP with per-user keys
• Attachment Deduplication: Identical attachments are stored only once, saving significant storage space
• DKIM/SPF Support: Native support for email authentication protocols
• Quota Management: Per-user and per-mailbox storage quotas
• Webmail Ready: Compatible with any IMAP-capable webmail client
• Open Source: Licensed under EUPL with an active development community

This guide walks through deploying WildDuck on Klutch.sh using Docker, configuring the required services, and setting up a production-ready mail server.

Why Deploy WildDuck on Klutch.sh

Deploying WildDuck on Klutch.sh provides several advantages for running your own mail infrastructure:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds WildDuck without complex server configuration. Push to GitHub, and your mail server deploys automatically.

Persistent Storage: Attach persistent volumes for MongoDB data and email storage. Your emails and configurations survive container restarts and redeployments.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for the web interface and API endpoints, ensuring secure access to your mail server.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates to your Dockerfile trigger automatic redeployments.

Scalable Resources: Allocate CPU and memory based on your expected email volume. Start small and scale as your user base grows.

Environment Variable Management: Securely store sensitive configuration like database credentials and DKIM keys through Klutch.sh’s environment variable system.

Custom Domains: Assign custom domains for your mail server, essential for proper email deliverability and branding.

Always-On Availability: Your email infrastructure remains accessible 24/7 without managing physical servers.

Prerequisites

Before deploying WildDuck on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your WildDuck configuration
• A domain name with access to DNS settings for MX records and SPF/DKIM configuration
• Basic familiarity with Docker and email protocols (IMAP, SMTP, POP3)
• A MongoDB instance (can be deployed on Klutch.sh or use a managed service)
• A Redis instance for session management and caching

Understanding WildDuck Architecture

WildDuck consists of several interconnected components:

WildDuck IMAP/POP3 Server: The core mail server handling IMAP and POP3 connections from email clients. It reads and writes emails to MongoDB.

Haraka MTA: A high-performance SMTP server that handles incoming and outgoing email. WildDuck includes a Haraka plugin for integration.

Zone-MTA: An outbound SMTP relay with queue management, DKIM signing, and delivery tracking.

MongoDB: The primary database storing all emails, attachments, user accounts, and metadata.

Redis: Used for session management, caching, and inter-process communication.

WildDuck API: RESTful API for user management, sending emails, and administrative tasks.

Preparing Your Repository

To deploy WildDuck on Klutch.sh, create a GitHub repository containing your configuration files.

Repository Structure

wildduck-deploy/
├── Dockerfile
├── config/
│   ├── wildduck.toml
│   ├── dbs.toml
│   └── imap.toml
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM node:20-alpine

# Install dependencies
RUN apk add --no-cache git python3 make g++

# Create app directory
WORKDIR /app

# Clone WildDuck
RUN git clone --depth 1 https://github.com/nodemailer/wildduck.git .

# Install dependencies
RUN npm install --production

# Copy configuration files
COPY config/ /app/config/

# Set environment variables
ENV NODE_ENV=production
ENV WILDDUCK_CONFIG=/app/config/wildduck.toml

# Expose ports
# IMAP: 143 (unencrypted), 993 (TLS)
# POP3: 110 (unencrypted), 995 (TLS)
# API: 8080
EXPOSE 143 993 110 995 8080

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:8080/health || exit 1

# Start WildDuck
CMD ["node", "server.js"]

Configuration Files

Create a config/wildduck.toml file:

# WildDuck Mail Server Configuration

[server]
host = "0.0.0.0"
port = 8080

[imap]
enabled = true
host = "0.0.0.0"
port = 143
secure = false

[imap.tls]
enabled = true
port = 993

[pop3]
enabled = true
host = "0.0.0.0"
port = 110

[pop3.tls]
enabled = true
port = 995

[api]
enabled = true
host = "0.0.0.0"
port = 8080
accessToken = "${API_ACCESS_TOKEN}"

[log]
level = "info"

[attachments]
# Deduplicate attachments to save storage
deduplication = true

Create a config/dbs.toml file for database connections:

# Database Configuration

[mongo]
uri = "${MONGODB_URI}"

[redis]
host = "${REDIS_HOST}"
port = 6379
password = "${REDIS_PASSWORD}"
db = 0

Environment Variables Reference

Variable	Required	Default	Description
MONGODB_URI	Yes	-	MongoDB connection string
REDIS_HOST	Yes	-	Redis server hostname
REDIS_PASSWORD	No	-	Redis authentication password
API_ACCESS_TOKEN	Yes	-	Secret token for API authentication
DKIM_PRIVATE_KEY	No	-	DKIM private key for email signing
NODE_ENV	No	production	Node.js environment

Deploying WildDuck on Klutch.sh

Once your repository is prepared, follow these steps to deploy WildDuck:

Set Up Required Services

Before deploying WildDuck, ensure you have MongoDB and Redis available. You can deploy these on Klutch.sh or use managed services:

• MongoDB Atlas for managed MongoDB
• Redis Cloud or deploy Redis on Klutch.sh

Note your connection strings and credentials for the next steps.

Generate Security Credentials

Generate secure tokens for your deployment:

• API Access Token: A random string for API authentication
• DKIM Keys: Generate a 2048-bit RSA key pair for email signing

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add .
git commit -m "Initial WildDuck deployment configuration"
git remote add origin https://github.com/yourusername/wildduck-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Name it something descriptive like “wildduck-mail” or “email-server”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your WildDuck configuration.

Configure HTTP Traffic

For the API and web interface:

• Select HTTP as the traffic type
• Set the internal port to 8080

Note: IMAP, POP3, and SMTP require TCP ports that may need additional configuration depending on your Klutch.sh plan.

Set Environment Variables

Configure the following environment variables:

Variable	Value
MONGODB_URI	Your MongoDB connection string
REDIS_HOST	Your Redis hostname
REDIS_PASSWORD	Your Redis password (if applicable)
API_ACCESS_TOKEN	Your generated API token

Attach Persistent Volumes

Add persistent storage for your mail server:

Mount Path	Recommended Size	Purpose
/app/logs	5 GB	Application logs
/app/data	10 GB	Local data and temporary files

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Detect your Dockerfile automatically
• Build the container image
• Attach the persistent volumes
• Start the WildDuck container
• Provision an HTTPS certificate

Configure DNS Records

After deployment, configure your domain’s DNS:

• MX Record: Point to your mail server hostname
• SPF Record: Add v=spf1 include:your-server.klutch.sh ~all
• DKIM Record: Add your DKIM public key as a TXT record
• DMARC Record: Configure your DMARC policy

Initial Setup and Configuration

Creating Your First User

Use the WildDuck API to create user accounts:

1. Access the API at https://your-app.klutch.sh/users
2. Use your API access token for authentication
3. Create users with email addresses for your domain

Configuring Email Clients

Configure email clients to connect to your WildDuck server:

Setting	Value
IMAP Server	your-app.klutch.sh
IMAP Port	993 (TLS) or 143 (STARTTLS)
POP3 Server	your-app.klutch.sh
POP3 Port	995 (TLS) or 110 (STARTTLS)
Username	Full email address
Password	User’s password

Setting Up DKIM Signing

DKIM signing improves email deliverability:

1. Generate a 2048-bit RSA key pair
2. Add the private key to your WildDuck configuration
3. Publish the public key as a DNS TXT record
4. Test signing with email authentication tools

Production Best Practices

Security Recommendations

• Strong Passwords: Enforce complex passwords for all email accounts
• TLS Only: Disable unencrypted IMAP/POP3 ports in production
• API Security: Use strong, unique API access tokens
• Regular Updates: Keep WildDuck and dependencies updated
• Firewall Rules: Restrict access to management ports

Email Deliverability

• SPF Records: Properly configure SPF to authorize your server
• DKIM Signing: Always sign outgoing emails with DKIM
• DMARC Policy: Implement DMARC for email authentication
• Reverse DNS: Ensure PTR records match your server hostname
• IP Reputation: Monitor your sending IP reputation

Backup Strategy

• MongoDB Backups: Regular backups of your MongoDB database
• Configuration Backups: Version control all configuration files
• DKIM Keys: Securely store copies of your DKIM private keys

Troubleshooting Common Issues

Cannot Connect to IMAP/POP3

Symptoms: Email clients fail to connect.

Solutions:

• Verify the server is running and ports are accessible
• Check TLS certificate configuration
• Confirm user credentials are correct
• Review firewall rules and port mappings

Emails Not Sending

Symptoms: Outgoing emails fail or bounce.

Solutions:

• Verify SMTP configuration and Zone-MTA setup
• Check SPF, DKIM, and DMARC records
• Monitor bounce and delivery logs
• Test IP reputation with email tools

MongoDB Connection Issues

Symptoms: Server fails to start or loses connection.

Solutions:

• Verify MongoDB connection string format
• Check MongoDB server availability
• Ensure proper authentication credentials
• Review MongoDB logs for errors

Additional Resources

• WildDuck Official Website
• WildDuck GitHub Repository
• WildDuck Documentation
• WildDuck Wiki
• Haraka SMTP Server
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying WildDuck on Klutch.sh gives you a modern, scalable email infrastructure with MongoDB-backed storage and comprehensive API access. The combination of WildDuck’s innovative architecture and Klutch.sh’s deployment simplicity means you can run your own mail server without traditional complexity.

With features like attachment deduplication, built-in encryption, and horizontal scaling capabilities, WildDuck handles everything from personal email to growing organizations. Take control of your email infrastructure while maintaining the reliability and security your communications require.