Getting Started

Installation

Cleanmails runs as a Docker Compose stack on any Linux VPS. This page covers the full manual installation process. For the fastest path, see Quick Deploy.

System Requirements

Component	Minimum	Recommended
OS	Ubuntu 22.04 / Debian 12	Ubuntu 22.04 LTS
CPU	1 vCPU	4 vCPU
RAM	2 GB	8 GB
Disk	20 GB SSD	50 GB SSD
Network	Outbound port 25 must be unblocked

Manual Installation

1. Install Docker

bash

curl -fsSL https://get.docker.com | sh
systemctl enable docker
systemctl start docker

2. Create the application directory

bash

mkdir -p /opt/cleanmails/data
cd /opt/cleanmails

3. Create the environment file

/opt/cleanmails/.env

APP_ENV=production
MASTER_KEY=$(openssl rand -hex 16)
SITE_URL=https://yourdomain.com
HTTP_PORT=80

MAIL_HOSTNAME=mail.yourdomain.com
SMTP_FROM_EMAIL=verify@yourdomain.com
SMTP_HELO_NAME=yourdomain.com

MAILCOW_URL=docker-exec
MAILCOW_KEY=docker-exec
MAILCOW_SMTP_HOST=mailserver
MAILCOW_IMAP_HOST=mailserver

OUTREACH_WORKERS=50
OUTREACH_BUFFER=5000
TRUST_PROXY=true

Generate a unique MASTER_KEY

Run openssl rand -hex 16 to generate a 32-character key. Never reuse keys across instances. This key encrypts all sender passwords and integration tokens.

4. Create docker-compose.yml

Copy the docker-compose.yml from your purchase download or the repository. It includes three services: Cleanmails, Caddy (reverse proxy + SSL), and docker-mailserver.

5. Configure firewall

bash

ufw allow 22/tcp
ufw allow 80/tcp
ufw allow 443/tcp
ufw allow 25/tcp
ufw allow 587/tcp
ufw allow 465/tcp
ufw allow 993/tcp
echo "y" | ufw enable

6. Start the stack

bash

docker compose up -d --build

7. Verify

bash

# Check all containers are running
docker compose ps

# Check health endpoint
curl http://localhost:8080/health

# Check logs
docker compose logs -f cleanmails

SSL Configuration

The included Caddy container handles SSL automatically. Just point your domain's A record to your server IP and update the Caddyfile:

Caddyfile

yourdomain.com {
    reverse_proxy cleanmails:8080
}

Caddy will auto-provision a Let's Encrypt certificate on first request.

Updating

bash

cd /opt/cleanmails
docker compose pull
docker compose up -d --build

Cleanmails also supports self-update from the dashboard (Settings → System → Check for Updates) if Ed25519 signing is configured.