Getting started

This guide takes you from an empty VPS to a working mail server using the prebuilt Docker image, lukeacl/clacks.

Before you start

Email deliverability is mostly about the environment, so get these right first:

• A VPS with a static IPv4 where the provider allows inbound and outbound port 25. Hetzner, OVH, and Vultr generally do; AWS, GCP, and DigitalOcean block outbound 25 by default.
• Reverse DNS (PTR) for that IP set to your mail hostname (e.g. mail.example.com). Your provider's panel has this setting. Receiving servers penalise or reject mail from IPs without a matching PTR.
• A domain on Cloudflare (for automatic TLS via DNS-01, and optionally R2 backups).
• Docker with Compose v2.23.1+ on the server.

Firewall

Allow only what you serve: 25, 587, 465, 143, 993, 443, and SSH.

1. Create a compose file

The minimal single-container setup:

name: clacks

services:
  clacks:
    image: lukeacl/clacks:latest   # pin a version in production, e.g. :1.0.0
    # Host networking gives correct client IPs (for SPF and rate limiting)
    # and access to all mail ports.
    network_mode: host
    restart: unless-stopped
    volumes:
      - clacks-data:/data
    environment:
      CLACKS_HOSTNAME: mail.example.com        # the FQDN your PTR points at
      CLACKS_TLS_MODE: acme
      CLACKS_TLS_ACME_EMAIL: [email protected]
      CLACKS_CLOUDFLARE_TOKEN: "${CLOUDFLARE_TOKEN}"   # Zone → DNS → Edit token

volumes:
  clacks-data:

Every setting has a sensible default — see Configuration for the full list, and Spam filtering & antivirus for the optional sidecars.

2. Start it

docker compose up -d
docker compose logs -f clacks

On first boot clacks obtains a TLS certificate for your hostname via Cloudflare DNS-01, then starts all listeners. Look for clacks starting and HTTP API listening in the log.

3. Run the setup wizard

Open https://mail.example.com in a browser. A fresh server shows a one-time setup form: enter your domain, an admin email at that domain, and a password. Clacks creates the domain (generating DKIM keys), creates your account as an admin, and signs you in.

The setup form permanently disables itself the moment the first account exists.

4. Publish your DNS records

Your domain can't receive or send trusted mail until DNS says so:

docker compose exec clacks clacks dns example.com

prints the exact records — MX, SPF, DKIM, and DMARC. Publish them, then verify with mail-tester.com. Details in DNS setup.

5. Connect a mail client

Any standard client works:

	Host	Port	Security
IMAP	mail.example.com	993	SSL/TLS
SMTP	mail.example.com	587	STARTTLS

Username is your full email address. Or just use the webmail at https://mail.example.com.

Managing the server

Admin tasks live in the web UI (Admin → Domains / Users / Aliases), or via the CLI inside the container — changes apply live:

docker compose exec clacks clacks domain add example.org
docker compose exec clacks clacks user add [email protected]
docker compose exec clacks clacks alias add [email protected] [email protected]
docker compose exec clacks clacks stats

Full list in the CLI reference.