How to Deploy Mailu on a VPS

copyufw allow proto tcp from any to any port 80,443,25,465,587,110,995,143,993,4190

copymkdir -p ~/mailu && cd ~/mailu

#Install Mailu

Mailu needs to know its own public hostname before it can request a TLS certificate or generate correct mail headers. Detect the server's public IP and build a hostname from it — this guide uses sslip.io, a DNS service that resolves <anything>.<ip>.sslip.io to <ip> for free, so you get a real, publicly resolvable hostname without owning a domain yet:

copySERVER_IP=$(curl -fsS https://ipv4.icanhazip.com | tr -d '[:space:]')
MAIL_DOMAIN="mail.${SERVER_IP}.sslip.io"
echo "SERVER_IP=${SERVER_IP}" > ~/mailu/.mailu-vars
echo "MAIL_DOMAIN=${MAIL_DOMAIN}" >> ~/mailu/.mailu-vars
cat ~/mailu/.mailu-vars

For a real deployment, replace this with your actual domain — set MAIL_DOMAIN to something like mail.yourcompany.com instead, and see the DNS section below. sslip.io is a fine stand-in for standing the stack up and confirming it boots; it cannot receive real mail for a domain you don't control.

Generate a secret key and write mailu.env — the single env file every Mailu container reads:

copySECRET_KEY=$(openssl rand -hex 16)
cat > mailu.env <<EOF
SECRET_KEY=${SECRET_KEY}
SUBNET=192.168.203.0/24
DOMAIN=${MAIL_DOMAIN}
HOSTNAMES=${MAIL_DOMAIN}
POSTMASTER=admin
TLS_FLAVOR=letsencrypt
DISABLE_STATISTICS=True
ADMIN=true
WEBMAIL=roundcube
API=false
WEBDAV=none
ANTIVIRUS=none
SCAN_MACROS=false
MESSAGE_SIZE_LIMIT=50000000
RECIPIENT_DELIMITER=+
FULL_TEXT_SEARCH=en
WEBROOT_REDIRECT=/webmail
WEB_ADMIN=/admin
WEB_WEBMAIL=/webmail
WEB_API=/api
SITENAME=Mailu
WEBSITE=https://${MAIL_DOMAIN}
COMPOSE_PROJECT_NAME=mailu
CREDENTIAL_ROUNDS=12
REAL_IP_HEADER=
REAL_IP_FROM=
REJECT_UNLISTED_RECIPIENT=no
LOG_LEVEL=INFO
TZ=Etc/UTC
DEFAULT_SPAM_THRESHOLD=80
EOF
chmod 600 mailu.env

A few of these matter more than they look:

• DOMAIN vs HOSTNAMES are different concepts that happen to share a value here. DOMAIN is the mail domain your addresses live at (user@DOMAIN); HOSTNAMES is the server's own name, used for its TLS certificate and SMTP banner. In a real deployment with your own domain, these often do differ (DOMAIN=yourcompany.com, HOSTNAMES=mail.yourcompany.com) — they're only the same value here because sslip.io gives us one throwaway hostname to work with.
• SECRET_KEY encrypts session data and signs internal tokens. Treat it like any other credential — back up mailu.env, never regenerate it on a running instance.
• TLS_FLAVOR=letsencrypt means the front container requests and renews its own certificate directly — no separate reverse proxy needed, which is why this guide doesn't use the Caddy guide.

Now write the compose file, pinned to a specific Mailu release rather than latest or master:

copycat > docker-compose.yml <<'EOF'
services:
  redis:
    image: redis:alpine
    restart: unless-stopped
    volumes:
      - redis_data:/data

  front:
    image: ghcr.io/mailu/nginx:2024.06.56
    restart: unless-stopped
    env_file: mailu.env
    ports:
      - "80:80"
      - "443:443"
      - "25:25"
      - "465:465"
      - "587:587"
      - "110:110"
      - "995:995"
      - "143:143"
      - "993:993"
      - "4190:4190"
    volumes:
      - certs:/certs
      - ./overrides/nginx:/overrides:ro
    depends_on:
      - admin
    networks:
      - default
      - webmail

  admin:
    image: ghcr.io/mailu/admin:2024.06.56
    restart: unless-stopped
    env_file: mailu.env
    volumes:
      - data:/data
      - dkim:/dkim
    depends_on:
      - redis
    networks:
      - default

  imap:
    image: ghcr.io/mailu/dovecot:2024.06.56
    restart: unless-stopped
    env_file: mailu.env
    volumes:
      - mail:/mail
      - ./overrides/dovecot:/overrides:ro
    depends_on:
      - front
    networks:
      - default

  smtp:
    image: ghcr.io/mailu/postfix:2024.06.56
    restart: unless-stopped
    env_file: mailu.env
    volumes:
      - mailqueue:/queue
      - ./overrides/postfix:/overrides:ro
    depends_on:
      - front
    networks:
      - default

  antispam:
    image: ghcr.io/mailu/rspamd:2024.06.56
    hostname: antispam
    restart: unless-stopped
    env_file: mailu.env
    volumes:
      - filter:/var/lib/rspamd
      - ./overrides/rspamd:/overrides:ro
    depends_on:
      - front
      - redis
    networks:
      - default

  webmail:
    image: ghcr.io/mailu/webmail:2024.06.56
    restart: unless-stopped
    env_file: mailu.env
    volumes:
      - webmail_data:/data
      - ./overrides/roundcube:/overrides:ro
    depends_on:
      - front
    networks:
      - webmail

networks:
  default:
    driver: bridge
    ipam:
      driver: default
      config:
        - subnet: 192.168.203.0/24
  webmail:
    driver: bridge

volumes:
  redis_data:
  certs:
  data:
  dkim:
  mail:
  mailqueue:
  filter:
  webmail_data:
EOF

This is a deliberately trimmed version of what the setup wizard generates: seven services instead of the full set (no resolver, antivirus, webdav, fetchmail, oletools, or tika containers), which keeps the stack inside the 1 GB RAM floor from the sizing section above. Each of those is a real, supported Mailu feature you can add later — just not required to get a working mail server.

Create the override directories Docker expects (empty is fine — they let you drop in custom config later without touching the images) and bring the stack up:

copymkdir -p overrides/nginx overrides/dovecot overrides/postfix overrides/rspamd overrides/roundcube
docker compose pull
docker compose up -d

Give it a moment to initialize — the admin container bootstraps its database and the front container starts its Let's Encrypt handshake — then check status:

copysleep 20
docker compose ps
docker compose logs --tail 50

All seven containers should show as running. front is the one to watch: it needs MAIL_DOMAIN to resolve publicly (sslip.io does this instantly) before its ACME challenge can succeed.

#First-run setup

Mailu has no web-based first-run wizard for the owner account — you create it from the CLI. This is actually safer than the open-registration screen other tools use: there's no window where an unauthenticated visitor can claim ownership.

copyADMIN_PASSWORD=$(openssl rand -base64 18)
echo "${ADMIN_PASSWORD}" > admin-password.txt
chmod 600 admin-password.txt
docker compose exec -T admin flask mailu admin admin "${MAIL_DOMAIN}" "${ADMIN_PASSWORD}"
echo "Admin login: admin@${MAIL_DOMAIN}"

flask mailu admin <localpart> <domain> <password> creates a user and grants it admin rights over that domain in one step. admin-password.txt now holds the password — move it somewhere safe and delete it from the server once you've logged in and saved it in a password manager.

Confirm the admin panel and webmail are actually reachable over HTTPS. The certificate can take a few seconds to finish issuing on first boot, so this polls briefly rather than checking once:

copyfor i in $(seq 1 24); do
  CODE=$(curl -s -o /dev/null -w '%{http_code}' -k "https://${MAIL_DOMAIN}/admin/ui/login")
  if [ "${CODE}" = "200" ]; then
    echo "admin UI responded HTTP ${CODE} after $((i * 5))s"
    break
  fi
  sleep 5
done
curl -sI -k "https://${MAIL_DOMAIN}/webmail/" | head -1

If both return 200, load https:// + your MAIL_DOMAIN in a browser, log into /webmail with admin@<your domain> and the password from admin-password.txt, and confirm the Roundcube inbox loads (empty, since no mail has arrived yet — that's expected). Then check /admin and confirm you can see the domain and the admin user under Mail domains.

#DNS + deliverability — read this before you send real mail

This is the section that separates a booted mail server from one that actually delivers mail, and it is not something a guide or a throwaway VPS can verify for you. Everything above gets Mailu installed, listening, and reachable over HTTPS on mail.<your-ip>.sslip.io. None of it proves a single email will arrive in someone's inbox — that depends on DNS records and sending reputation tied to a real domain, which sslip.io deliberately doesn't give you.

Before sending anything real, on your actual domain:

• MX record — points your domain at your mail server's hostname (yourcompany.com. MX 10 mail.yourcompany.com.), so other servers know where to deliver.
• SPF record (TXT) — authorizes your server's IP to send for your domain (v=spf1 mx ~all). Without it, receiving servers have no way to tell your mail from a spoofer's.
• DKIM record (TXT) — Mailu generates a DKIM keypair per domain automatically; the public key and the exact record to publish are shown in the admin panel under Mail domains → your domain → DKIM. Publish it before sending your first message.
• DMARC record (TXT) — tells receivers what to do with mail that fails SPF/DKIM (v=DMARC1; p=quarantine; rua=mailto:postmaster@yourcompany.com), and gets you reports when someone spoofs your domain.
• PTR (reverse DNS) — your VPS provider sets this, usually in their control panel, not your DNS host. It should resolve your server's IP back to mail.yourcompany.com. Most receiving servers (Gmail especially) treat mail from an IP with no matching PTR as spam by default.
• Port 25 outbound — some VPS providers block it by default on new accounts to fight spam operations; you may need to open a support ticket to unblock it before you can send mail to the world.

copydig +short MX yourcompany.com
dig +short TXT yourcompany.com | grep spf
dig -x YOUR.SERVER.IP +short

In short: install-verified and delivery-verified are two different claims. This guide (and its verification stamp, if this page shows one) covers the former — Mailu boots correctly on Ubuntu 26.04 and serves its admin panel and webmail over HTTPS. Getting real mail delivered to Gmail/Outlook inboxes is DNS, reputation, and IP-warming work that's genuinely yours to do, and can take days to settle even once every record above is correct.

#Backups

Three things matter: the mail volume (every mailbox, the actual content you can't regenerate), the dkim volume (your signing keys — losing these means re-publishing DNS and a reputation hit), and mailu.env (holds SECRET_KEY). Stop the stack briefly for a consistent cold backup, tar the volumes, then bring it back up:

copydocker compose stop
tar czf ~/mailu-backup-$(date +%F).tar.gz -C /var/lib/docker/volumes \
  mailu_mail mailu_dkim mailu_data mailu_certs
cp mailu.env ~/mailu-env-backup-$(date +%F).env
docker compose start

Copy both files off the box — an S3-compatible bucket or another machine — and periodically restore them into a throwaway stack to confirm the backup actually works. A backup you haven't restored is a guess, and for a mail server that guess includes your DKIM identity.

#Upgrades

New Mailu releases land roughly monthly. Pull the pinned tag's replacement and recreate:

copydocker compose pull
docker compose up -d
docker compose logs --tail 30

Read the release notes before bumping the version, especially across year-boundary releases (2024.06 → the next series) — Mailu occasionally changes mailu.env variable names or defaults, and the notes tell you what to add or rename. Bump the 2024.06.56 tag in docker-compose.yml deliberately rather than riding latest, back up first, then upgrade.

#Troubleshooting

front never gets a certificate / admin panel loads with a browser TLS warning. Almost always DNS: Let's Encrypt's HTTP-01 challenge needs MAIL_DOMAIN to resolve to this server's IP before the container starts. sslip.io resolves instantly, so on the demo domain this usually means ports 80/443 aren't actually open — recheck ufw and your provider's firewall/security-group rules.

copydocker compose logs -f front

Mail from your domain lands in spam, or bounces with a reputation error. This is a DNS/reputation issue, not a container issue — revisit the DNS section above. The most common single cause is a missing or mismatched DKIM record; the admin panel shows the exact record Mailu expects.

docker compose exec -T admin flask mailu admin ... fails with "already exists." You're re-running user creation against an account that's already there. Reset a password instead:

copydocker compose exec -T admin flask mailu password admin@yourcompany.com 'NewPassword'

A container restarts in a loop after docker compose up -d. Check that container's own logs (docker compose logs <service> --tail 100) rather than the aggregate — admin failing usually means a mailu.env typo, front failing usually means a port conflict (something else already bound to 25 or 443) or a DNS/TLS issue as above.

#Verification + next steps

You're done when: all seven containers show running, the admin panel and webmail both respond 200 over HTTPS on your MAIL_DOMAIN, you've logged into webmail as the admin user, and a backup plus mailu.env are sitting in off-box storage. That's the install-verified bar this guide targets.

From there, the real work starts: point a real domain at the server, publish MX/SPF/DKIM/DMARC/PTR, confirm port 25 is open outbound, and send yourself a test message from an external account — Gmail's own mail tester tools are a good sanity check before you migrate a whole team's inbox over. A Hetzner CX22 or a 2 GB DigitalOcean droplet handles this stack comfortably; see Best VPS for self-hosting for the ranked picks.