How to Self-Host Chasquid with Docker

What Is Chasquid?

Chasquid is a lightweight SMTP server written in Go that prioritizes simplicity and security. Unlike full mail suites like Mailcow or Mailu, Chasquid focuses on doing one thing well: sending and receiving email via SMTP with automatic TLS. It includes built-in Let’s Encrypt support, SPF verification, and MTA-STS compliance. The official Docker image bundles Dovecot for IMAP access, making it a complete (if minimal) self-hosted email solution.

• Official Repository

Prerequisites

• A Linux server (Ubuntu 22.04+ recommended) with a public IP address
• Docker and Docker Compose installed (guide)
• 256 MB of free RAM (minimum)
• 2 GB of free disk space
• A domain name with DNS control
• Port 25, 465, and 587 must be open — many cloud providers block port 25 by default. Check with your hosting provider.

DNS Configuration

Before deploying Chasquid, set up these DNS records for your mail domain (e.g., example.com):

Record Type	Host	Value	Purpose
A	mail.example.com	Your server IP	Points to mail server
MX	example.com	mail.example.com (priority 10)	Routes incoming mail
TXT	example.com	v=spf1 mx -all	SPF — authorizes your server to send
TXT	_dmarc.example.com	v=DMARC1; p=quarantine; rua=mailto:[email protected]	DMARC policy

DKIM records are configured after initial setup — Chasquid does not auto-generate DKIM keys (use an external tool like OpenDKIM if needed).

Docker Compose Configuration

Create a directory for your Chasquid deployment:

mkdir -p ~/chasquid && cd ~/chasquid

Create a docker-compose.yml file:

services:
  chasquid:
    image: registry.gitlab.com/albertito/chasquid:v1.17.0
    container_name: chasquid
    environment:
      # Auto-provision Let's Encrypt certificates for this domain
      AUTO_CERTS: mail.example.com
    ports:
      - "25:25"       # SMTP (incoming mail from other servers)
      - "465:465"     # SMTPS (submission over TLS)
      - "587:587"     # Submission (STARTTLS)
      - "993:993"     # IMAPS (Dovecot — reading mail)
    volumes:
      - chasquid_data:/data
    restart: unless-stopped
    # Network host mode recommended for proper SPF verification
    # Chasquid needs to see the real source IP of connecting servers
    network_mode: host

Note on network_mode: host: Chasquid validates SPF records by checking the connecting server’s IP address. In bridge networking mode, all connections appear to come from Docker’s internal gateway IP, which breaks SPF checks. Host networking ensures Chasquid sees the real remote IP. If you cannot use host networking, SPF verification will not function correctly.

If you prefer bridge networking (e.g., for reverse proxy setups), use this alternative configuration — but be aware SPF checking will be limited:

services:
  chasquid:
    image: registry.gitlab.com/albertito/chasquid:v1.17.0
    container_name: chasquid
    environment:
      AUTO_CERTS: mail.example.com
    ports:
      - "25:25"
      - "465:465"
      - "587:587"
      - "993:993"
    volumes:
      - chasquid_data:/data
    restart: unless-stopped
    networks:
      - mail-net

volumes:
  chasquid_data:

networks:
  mail-net:
    driver: bridge

Start the container:

docker compose up -d

Initial Setup

Add a Mail User

Create your first email account:

docker exec -it chasquid /add-user.sh

The script prompts for an email address (e.g., [email protected]) and password. It stores credentials in Dovecot’s user database inside the /data volume.

Verify TLS Certificates

If you set AUTO_CERTS, Chasquid requests Let’s Encrypt certificates on startup. Check the logs to confirm:

docker logs chasquid | grep -i cert

You should see a message confirming certificate issuance for your domain. Port 80 must be reachable from the internet for the ACME HTTP challenge to succeed.

Test SMTP

Send a test email using swaks or any SMTP client:

swaks --to [email protected] --from [email protected] \
  --server mail.example.com:587 \
  --auth-user [email protected] \
  --auth-password 'your-password' \
  --tls

Configuration

Chasquid Configuration File

For advanced settings, mount a custom configuration file:

volumes:
  - ./chasquid.conf:/etc/chasquid/chasquid.conf:ro
  - chasquid_data:/data

Key configuration options in chasquid.conf:

# Maximum email size (default: 50 MB)
max_data_size_mb: 50

# Address suffixes (user+tag support)
suffix_separators: "+"

# Characters to drop from usernames (e.g., dots)
drop_characters: "."

# Monitoring port (localhost only)
monitoring_address: ":1099"

Port Reference

Port	Protocol	Purpose
25	SMTP	Incoming mail from other servers
465	SMTPS	Client submission (implicit TLS)
587	Submission	Client submission (STARTTLS)
993	IMAPS	Dovecot IMAP (reading mail)
1099	HTTP	Monitoring/debug (localhost only)

Email Aliases

Create aliases by adding a file to the data volume:

docker exec -it chasquid sh -c 'echo "[email protected]" > /data/domains/example.com/aliases/postmaster'

This routes [email protected] to [email protected].

Backup

The /data volume contains everything: user credentials, mail data, TLS certificates, and configuration. Back it up regularly:

docker run --rm -v chasquid_data:/data -v $(pwd):/backup alpine \
  tar czf /backup/chasquid_backup_$(date +%Y%m%d).tar.gz -C /data .

See our Backup Strategy guide for automated approaches.

Troubleshooting

Let’s Encrypt Certificate Not Issued

Symptom: Chasquid starts but TLS connections fail. Fix: Ensure port 80 is open and reachable from the internet. The ACME HTTP-01 challenge requires an inbound HTTP connection. Check docker logs chasquid for certificate errors. Verify your DNS A record points to the correct IP.

Emails Going to Spam

Symptom: Sent emails land in recipients’ spam folders. Fix: Verify your DNS records — SPF, DKIM, and DMARC must all be configured. Check your IP against blacklists at mxtoolbox.com. Set up a PTR (reverse DNS) record matching mail.example.com. See our Email Deliverability guide.

Port 25 Blocked

Symptom: Cannot receive mail from external servers. Fix: Many cloud providers (AWS, GCP, Azure, Oracle Cloud) block port 25 by default. Contact your provider to request unblocking, or use a VPS provider like Hetzner or OVH that allows SMTP traffic.

Authentication Failed

Symptom: SMTP client returns “authentication failed” when sending. Fix: Verify the user was created successfully: docker exec -it chasquid cat /data/dovecot/users. Ensure you’re using the full email address (not just the username) for authentication.

Resource Requirements

• RAM: ~50 MB idle, ~100 MB under load
• CPU: Minimal — Go binary is extremely efficient
• Disk: ~100 MB for application, plus mail storage (varies by usage)

Verdict

Chasquid is the right choice if you want a minimal, secure SMTP server without the overhead of a full mail suite. At ~50 MB RAM, it’s 10-20x lighter than Mailcow or Mailu. The automatic Let’s Encrypt integration and Go-based architecture make it nearly zero-maintenance for small deployments. The trade-off: no web UI for administration, no webmail, no spam filtering beyond SPF. If you need a complete email platform with webmail and anti-spam, use Mailcow. If you want something between Chasquid’s minimalism and Mailcow’s complexity, Stalwart offers a modern middle ground with JMAP support.

Related

• Chasquid vs Maddy: Lightweight Mail Servers Compared
• Best Self-Hosted Email Servers
• Replace Gmail with Self-Hosted Email
• Stalwart vs Mailcow
• Mailu vs Mailcow
• How to Self-Host Mailcow
• How to Self-Host Stalwart
• Email Deliverability Guide
• Docker Compose Basics
• Reverse Proxy Setup