Skip to content
Klutch.sh Docs

Deploying Haraka

Introduction

Haraka is a high-performance SMTP mail transfer agent (MTA) written in Node.js. Designed for modern email handling, Haraka provides a plugin-based architecture that allows extensive customization of email processing, filtering, and delivery. It excels at handling high volumes of email with low resource usage while maintaining compatibility with standard email protocols.

Built for developers and system administrators who need fine-grained control over email processing, Haraka supports features like DKIM signing, SPF validation, anti-spam filtering, and authentication. The plugin system makes it easy to add custom logic for email routing, content filtering, and integration with other services.

Key highlights of Haraka:

  • High Performance: Handle thousands of concurrent connections with minimal memory usage
  • Plugin Architecture: Extend functionality with over 100 available plugins
  • Modern Stack: Built on Node.js for easy customization and rapid development
  • DKIM Support: Sign outgoing emails and verify incoming signatures
  • SPF/DMARC: Validate sender policies for spam prevention
  • Authentication: Support for SMTP AUTH with multiple backends
  • TLS/STARTTLS: Secure email transmission with encryption
  • Queue Management: Built-in queue with retry logic and delivery tracking

This guide walks through deploying Haraka on Klutch.sh using Docker, configuring email handling plugins, and setting up the server for production mail delivery.

Prerequisites

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

  • A Klutch.sh account
  • A GitHub account with a repository for your Haraka configuration
  • A domain name with DNS control for MX records
  • Understanding of SMTP and email delivery concepts
  • DNS records configured for SPF, DKIM, and DMARC

Preparing Your Repository

Create a GitHub repository with the following structure:

haraka-deploy/
├── Dockerfile
├── config/
│   ├── smtp.ini
│   ├── plugins
│   ├── host_list
│   └── tls.ini
├── .dockerignore
└── README.md

Creating the Dockerfile

Create a Dockerfile using the instrumentisto Haraka image:

FROM instrumentisto/haraka:latest


# Copy configuration files
COPY config/ /haraka/config/


# Set environment variables
ENV HARAKA_HOME=/haraka


# Expose SMTP port
EXPOSE 25


# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=10s --retries=3 \
  CMD nc -z localhost 25 || exit 1

Basic Configuration Files

Create config/smtp.ini:

; SMTP server configuration
listen=[::]:25


; Limits
max_received_count=100
max_mime_depth=20

Create config/plugins:

# Logging
log.syslog


# TLS
tls


# Authentication (if needed)
# auth/flat_file


# DNS checks
dnsbl


# SPF
spf


# Message size limit
max_message_size


# Queue for delivery
queue/smtp_forward

Create config/host_list:

# List of domains to accept mail for
yourdomain.com

Environment Variables Reference

VariableRequiredDescription
HARAKA_HOMENoHaraka installation directory
SMTP_PORTNoSMTP listening port (default: 25)
TLS_CERTNoPath to TLS certificate
TLS_KEYNoPath to TLS private key

Deploying Haraka on Klutch.sh

    Prepare Configuration Files

    Create the configuration files in your repository’s config/ directory based on your email requirements.

    Push Your Repository to GitHub

    Terminal window
    git init
    git add Dockerfile config/ .dockerignore README.md
    git commit -m "Initial Haraka deployment configuration"
    git remote add origin https://github.com/yourusername/haraka-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 named “haraka-mail” or similar.

    Create a New App

    Within your project, create a new app. Connect your GitHub account and select your Haraka repository.

    Configure TCP Traffic

    Haraka uses SMTP protocol over TCP:

    • Select TCP as the traffic type
    • Set the internal port to 25
    • Note the external port (8000) for DNS configuration

    Attach Persistent Volumes

    Mount PathRecommended SizePurpose
    /haraka/config1 GBHaraka configuration files
    /haraka/queue10 GBEmail queue storage
    /haraka/logs5 GBServer logs

    Deploy Your Application

    Click Deploy to start the build process. Klutch.sh will build the container, attach volumes, and start Haraka.

    Configure DNS Records

    Update your domain’s DNS with the following records:

    • MX Record: Point to your Klutch.sh app URL
    • SPF Record: v=spf1 include:klutch.sh ~all
    • DKIM: Configure based on your generated keys

Configuring Haraka Plugins

Enabling DKIM Signing

Create config/dkim_sign.ini:

disabled = false
selector = mail
domain = yourdomain.com

Add to config/plugins:

dkim_sign

Configuring Spam Filtering

Add spam-related plugins to config/plugins:

dnsbl
spamassassin
karma

Setting Up TLS

Create config/tls.ini:

key=/haraka/config/tls/server.key
cert=/haraka/config/tls/server.crt

Mail Submission Agent (MSA)

For authenticated email submission on port 587:

; In smtp.ini
listen=[::]:587


; Enable authentication
[auth]
enabled=true

Troubleshooting

Connection Refused

  • Verify TCP port configuration
  • Check firewall rules allow SMTP traffic
  • Ensure DNS MX records are correct

Email Delivery Issues

  • Check queue directory for stuck messages
  • Review logs for delivery errors
  • Verify recipient domain DNS

TLS Errors

  • Ensure certificate files are valid
  • Check certificate chain completeness
  • Verify key permissions

Additional Resources

Conclusion

Deploying Haraka on Klutch.sh provides a high-performance, customizable mail server with modern features and extensible architecture. The plugin system allows precise control over email handling, from spam filtering to custom routing logic. With persistent storage for queues and configuration, your mail server maintains reliability across deployments while benefiting from Klutch.sh’s infrastructure.