Deploying chasquid

Introduction

chasquid is a simple, fast, and secure SMTP server written in Go that prioritizes ease of configuration and modern security practices. Unlike complex mail transfer agents that require extensive setup, chasquid is designed to be straightforward while still providing enterprise-grade features for email delivery.

The name “chasquid” comes from the Incan messengers who carried messages across the Andes, reflecting the server’s purpose as a reliable mail carrier. Built with security as a first-class concern, chasquid enforces TLS encryption, supports modern authentication mechanisms, and integrates with popular spam filtering solutions.

Key highlights of chasquid:

• Simple Configuration: Easy-to-understand configuration format with sensible defaults
• TLS by Default: Automatic TLS certificate management with Let’s Encrypt integration
• Modern Security: Supports STARTTLS, SPF, DKIM, and DMARC verification
• Multiple Domains: Host email for multiple domains from a single instance
• Dovecot Integration: Seamlessly integrates with Dovecot for user authentication
• Hooks System: Extensible hook system for custom mail processing
• Lightweight: Minimal resource footprint written in efficient Go
• Monitoring Ready: Built-in Prometheus metrics for observability
• 100% Open Source: Apache 2.0 licensed with active development

This guide walks through deploying chasquid on Klutch.sh, configuring domains and users, and setting up a production-ready mail server.

Why Deploy chasquid on Klutch.sh

Deploying chasquid on Klutch.sh provides several advantages for your email infrastructure:

Simplified Deployment: Klutch.sh handles container orchestration, allowing you to focus on mail server configuration rather than infrastructure management.

Persistent Storage: Attach volumes for mail queues, configuration, and logs that persist across container restarts.

Environment Variable Management: Securely store sensitive configuration like authentication secrets without exposing them in your repository.

Custom Domains: Configure custom domains with proper DNS records for professional email addresses.

Scalable Resources: Allocate CPU and memory based on your email volume and adjust as your needs grow.

Always-On Availability: Your mail server remains operational 24/7 without managing physical infrastructure.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• A domain name with DNS access for MX, SPF, DKIM, and DMARC records
• Basic understanding of email protocols and DNS
• TLS certificates for your mail domain (or use Let’s Encrypt)

Understanding chasquid Architecture

chasquid is designed with simplicity and security at its core:

Go-Based Server: Written in Go for efficiency, memory safety, and easy deployment as a single binary.

File-Based Configuration: Simple text files define domains, users, and server settings without complex databases.

Hook System: Pre and post-processing hooks allow custom scripts for spam filtering, logging, and mail manipulation.

Queue Management: Persistent mail queue with automatic retries and bounce handling.

Authentication Backends: Support for Dovecot authentication, making it easy to integrate with existing user databases.

Preparing Your Repository

Create a GitHub repository with your chasquid configuration.

Repository Structure

chasquid-deploy/
├── Dockerfile
├── config/
│   ├── chasquid.conf
│   └── domains/
│       └── example.com/
│           ├── users
│           └── aliases
├── certs/
│   └── .gitkeep
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile for your chasquid deployment:

FROM golang:1.21-alpine AS builder

RUN apk add --no-cache git

# Build chasquid from source
RUN go install blitiri.com.ar/go/chasquid/cmd/chasquid@latest
RUN go install blitiri.com.ar/go/chasquid/cmd/chasquid-util@latest

FROM alpine:latest

# Install runtime dependencies
RUN apk add --no-cache ca-certificates tzdata

# Copy binaries from builder
COPY --from=builder /go/bin/chasquid /usr/local/bin/
COPY --from=builder /go/bin/chasquid-util /usr/local/bin/

# Create directories
RUN mkdir -p /etc/chasquid /var/lib/chasquid /var/log/chasquid

# Copy configuration
COPY config/ /etc/chasquid/

# Set permissions
RUN chmod -R 755 /etc/chasquid

# Expose SMTP ports
EXPOSE 25 465 587

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

# Run chasquid
CMD ["chasquid", "-config_dir=/etc/chasquid", "-log_dir=/var/log/chasquid"]

Creating the Configuration File

Create config/chasquid.conf:

# chasquid configuration

# Hostname for this mail server
hostname: mail.example.com

# Maximum size of incoming messages (in bytes)
max_data_size_mb: 50

# Addresses to listen on for SMTP
smtp_address: ":25"

# Addresses to listen on for submission (authenticated sending)
submission_address: ":587"

# Addresses to listen on for submission over TLS
submission_over_tls_address: ":465"

# Path to mail delivery agent (for local delivery)
mail_delivery_agent_bin: "/usr/bin/maildrop"
mail_delivery_agent_args: "-f"

# Monitoring address for Prometheus metrics
monitoring_address: ":9099"

# Data directory for queue and state
data_dir: "/var/lib/chasquid"

# Certificate directory
# Chasquid will look for cert.pem and key.pem in subdirectories
# named after each domain
certs_dir: "/etc/chasquid/certs"

# Enable Dovecot authentication
dovecot_auth: false

Creating Domain Configuration

Create config/domains/example.com/users for user accounts:

# Format: username:password_hash
# Generate hash with: chasquid-util user-add username
admin:$2a$10$...

Create config/domains/example.com/aliases for email aliases:

# Format: alias: destination
postmaster: admin
abuse: admin
webmaster: admin
info: admin

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
.DS_Store
*.log

Deploying chasquid on Klutch.sh

Follow these steps to deploy your chasquid mail server:

Generate Password Hashes

Before deployment, generate password hashes for your users. You can do this locally if you have chasquid-util installed:

chasquid-util user-add admin

Alternatively, use a bcrypt generator to create password hashes.

Configure Your Domain

Update the chasquid.conf with your actual hostname and domain settings. Ensure the domain directory structure matches your domain name.

Push Your Repository to GitHub

Initialize and push your repository:

git init
git add .
git commit -m "Initial chasquid configuration"
git remote add origin https://github.com/yourusername/chasquid-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 for your mail infrastructure.

Create a New App

Within your project, create a new app and connect your GitHub repository containing the chasquid configuration.

Configure Traffic Settings

chasquid requires multiple ports for SMTP traffic:

• Port 25: Standard SMTP for receiving mail
• Port 587: Submission port for authenticated sending
• Port 465: SMTP over TLS

Configure your app to expose these ports as needed for your use case.

Attach Persistent Volumes

Add persistent volumes for mail server data:

Mount Path	Recommended Size	Purpose
/var/lib/chasquid	10 GB	Mail queue and server state
/var/log/chasquid	1 GB	Server logs
/etc/chasquid/certs	100 MB	TLS certificates

Deploy Your Application

Click Deploy to build and start your chasquid server. Klutch.sh will build the container and start the mail server.

Configure DNS Records

Set up the required DNS records for your domain:

Record Type	Name	Value
MX	@	mail.example.com (priority 10)
A	mail	Your server IP
TXT	@	v=spf1 ip4:YOUR_IP -all
TXT	_dmarc	v=DMARC1; p=reject; rua=mailto:admin@example.com

Initial Setup and Configuration

Adding Users

Add new email users by updating the users file for your domain:

# Generate password hash
chasquid-util user-add newuser

# Add the output line to domains/example.com/users

Configuring Aliases

Set up email aliases in domains/example.com/aliases:

# Standard aliases
postmaster: admin
abuse: admin
security: admin

# Distribution lists
team: user1, user2, user3

# External forwarding
external: external@gmail.com

Multiple Domains

Host multiple domains by creating additional domain directories:

config/domains/
├── example.com/
│   ├── users
│   └── aliases
├── example.org/
│   ├── users
│   └── aliases
└── company.net/
    ├── users
    └── aliases

TLS Certificate Configuration

Using Let’s Encrypt

chasquid can automatically manage Let’s Encrypt certificates. Configure the certificate directory structure:

certs/
└── mail.example.com/
    ├── fullchain.pem
    └── privkey.pem

Manual Certificate Setup

For manually obtained certificates, place them in the domain-specific directory:

mkdir -p /etc/chasquid/certs/mail.example.com
cp fullchain.pem /etc/chasquid/certs/mail.example.com/
cp privkey.pem /etc/chasquid/certs/mail.example.com/

Email Authentication Setup

SPF Records

Create an SPF record to authorize your server to send email:

v=spf1 ip4:YOUR_SERVER_IP -all

DKIM Signing

Set up DKIM signing for outgoing mail:

1. Generate a DKIM key pair
2. Configure chasquid hooks for DKIM signing
3. Publish the public key in DNS

DMARC Policy

Implement DMARC for email authentication:

v=DMARC1; p=reject; rua=mailto:dmarc@example.com; pct=100

Monitoring and Observability

Prometheus Metrics

chasquid exposes Prometheus metrics on the configured monitoring port:

# Access metrics
curl http://localhost:9099/metrics

Key metrics include:

• chasquid_smtp_responses_total: SMTP response counts
• chasquid_queue_size: Current queue size
• chasquid_delivery_attempts_total: Delivery attempt counts

Log Analysis

Access chasquid logs for troubleshooting:

# View recent logs
tail -f /var/log/chasquid/chasquid.log

Production Best Practices

Security Recommendations

• Enforce TLS: Require TLS for all connections where possible
• Strong Passwords: Use strong, unique passwords for all email accounts
• Rate Limiting: Configure rate limits to prevent abuse
• Regular Updates: Keep chasquid updated to the latest version

Anti-Spam Measures

• SPF/DKIM/DMARC: Implement all three for maximum email authentication
• Hook Scripts: Use pre-data hooks for spam filtering
• Blacklist Integration: Integrate with DNS blacklists for incoming mail

Backup Strategy

Regular backups should include:

1. Configuration files in /etc/chasquid
2. User databases and aliases
3. Mail queue in /var/lib/chasquid
4. TLS certificates

Troubleshooting Common Issues

Connection Refused

Symptoms: Cannot connect to SMTP ports.

Solutions:

• Verify the container is running and ports are exposed
• Check firewall rules allow SMTP traffic
• Confirm chasquid is listening on the correct addresses

Authentication Failures

Symptoms: Users cannot authenticate to send mail.

Solutions:

• Verify password hashes are correctly formatted
• Check the users file for the correct domain
• Ensure Dovecot integration is properly configured if used

Certificate Errors

Symptoms: TLS handshake failures or certificate warnings.

Solutions:

• Verify certificate files are in the correct directory
• Check certificate file permissions
• Ensure the certificate matches the server hostname

Mail Not Delivering

Symptoms: Emails stuck in queue or not arriving.

Solutions:

• Check queue status with chasquid-util
• Review logs for delivery errors
• Verify DNS records are correctly configured
• Test with email deliverability tools

Additional Resources

• Official chasquid Website
• chasquid Documentation
• chasquid GitHub Repository
• Email Authentication Guide
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying chasquid on Klutch.sh provides a lightweight, secure, and easy-to-manage email server that prioritizes modern security practices. The combination of chasquid’s simple configuration approach and Klutch.sh’s container management means you can run a production-ready mail server without the complexity typically associated with email infrastructure.

With built-in TLS support, Prometheus metrics, and a straightforward domain configuration model, chasquid offers everything needed for reliable email delivery while maintaining the simplicity that makes it accessible to administrators of all experience levels.