Self-Hosting iRedMail with Docker Compose

What Is iRedMail?

iRedMail is a full-featured, open-source email server solution that bundles Postfix, Dovecot, SpamAssassin, ClamAV, Roundcube, and iRedAdmin into a single deployable package. It replaces Gmail, Outlook, and other commercial email services with a self-hosted stack you fully control. The Docker edition packages everything into one container with MariaDB, making deployment straightforward compared to assembling individual mail components.

Prerequisites

• A Linux server (Ubuntu 22.04+ recommended) with at least 4 GB of RAM
• Docker and Docker Compose installed (guide)
• 20 GB of free disk space (ClamAV signatures + mailbox storage)
• A domain name with DNS access (MX, SPF, DKIM, DMARC records required)
• Port 25 open outbound (many ISPs and cloud providers block this — check first)
• A reverse proxy or direct port access for HTTPS (Reverse Proxy Setup)

Docker Compose Configuration

Create a docker-compose.yml file:

services:
  iredmail:
    image: iredmail/mariadb:stable
    container_name: iredmail
    hostname: mail.example.com
    restart: unless-stopped
    ports:
      - "25:25"       # SMTP
      - "465:465"     # SMTPS
      - "587:587"     # Submission (STARTTLS)
      - "143:143"     # IMAP (STARTTLS)
      - "993:993"     # IMAPS
      - "110:110"     # POP3 (STARTTLS)
      - "995:995"     # POP3S
      - "80:80"       # HTTP (redirects to HTTPS)
      - "443:443"     # HTTPS (Roundcube + iRedAdmin)
      - "4190:4190"   # ManageSieve
    environment:
      - HOSTNAME=mail.example.com
      - FIRST_MAIL_DOMAIN=example.com
      - FIRST_MAIL_DOMAIN_ADMIN_PASSWORD=ChangeThisStrongPassword123
      - MLMMJADMIN_API_TOKEN=GenerateWithOpenSSLRand
      - ROUNDCUBE_DES_KEY=GenerateWith24CharBase64
      - MYSQL_USE_RANDOM_PASSWORDS=NO
      - MYSQL_ROOT_PASSWORD=ChangeThisRootPassword
      - USE_IREDAPD=YES
      - USE_ANTISPAM=YES
      - USE_FAIL2BAN=YES
      - USE_ROUNDCUBE=YES
      - USE_IREDADMIN=YES
    volumes:
      - iredmail_backup:/var/vmail/backup/mysql
      - iredmail_mailboxes:/var/vmail/vmail1
      - iredmail_mlmmj:/var/vmail/mlmmj
      - iredmail_mlmmj_archive:/var/vmail/mlmmj-archive
      - iredmail_imapsieve:/var/vmail/imapsieve_copy
      - iredmail_custom:/opt/iredmail/custom
      - iredmail_ssl:/opt/iredmail/ssl
      - iredmail_mysql:/var/lib/mysql
      - iredmail_clamav:/var/lib/clamav
      - iredmail_spamassassin:/var/lib/spamassassin
      - iredmail_postfix:/var/spool/postfix

volumes:
  iredmail_backup:
  iredmail_mailboxes:
  iredmail_mlmmj:
  iredmail_mlmmj_archive:
  iredmail_imapsieve:
  iredmail_custom:
  iredmail_ssl:
  iredmail_mysql:
  iredmail_clamav:
  iredmail_spamassassin:
  iredmail_postfix:

Generate the required tokens before starting:

# Generate MLMMJADMIN_API_TOKEN
openssl rand -base64 32

# Generate ROUNDCUBE_DES_KEY (must be exactly 24 characters)
openssl rand -base64 24

Replace HOSTNAME, FIRST_MAIL_DOMAIN, all passwords, and the generated tokens in the environment variables. Then start the stack:

docker compose up -d

The first startup takes several minutes — ClamAV downloads virus signatures and SpamAssassin updates rules.

Initial Setup

1. Wait for startup to complete. Monitor logs with docker compose logs -f iredmail. Look for All services are started before proceeding.

2. Access the admin panel at https://mail.example.com/iredadmin/. Log in with:

   • Username: [email protected]
   • Password: the value you set in FIRST_MAIL_DOMAIN_ADMIN_PASSWORD

3. Access webmail at https://mail.example.com/mail/ (Roundcube). Log in with the same postmaster credentials.

4. Create user mailboxes through iRedAdmin. Navigate to Add → User and create accounts for your domain.

5. Configure DNS records for your domain. Without these, your emails will be rejected by receiving servers:

Record	Type	Value
MX	MX	mail.example.com (priority 10)
mail	A	Your server’s IP address
SPF	TXT	v=spf1 mx -all
DKIM	TXT	Copy from /opt/iredmail/custom/amavisd/
DMARC	TXT	v=DMARC1; p=quarantine; rua=mailto:[email protected]

Extract your DKIM public key:

docker exec iredmail amavisd-new showkeys

Configuration

Disable Unnecessary Services

If you don’t need antivirus scanning (saves ~1 GB RAM):

environment:
  - USE_ANTISPAM=NO

If you prefer a different webmail client:

environment:
  - USE_ROUNDCUBE=NO

Message Size Limits

environment:
  - MESSAGE_SIZE_LIMIT_IN_MB=50
  - WEB_UPLOAD_SIZE_LIMIT_IN_MB=30

Custom Configuration Overrides

Place custom Postfix, Dovecot, or other config files in the iredmail_custom volume:

/opt/iredmail/custom/postfix/main.cf    # Postfix overrides
/opt/iredmail/custom/dovecot/dovecot.conf  # Dovecot overrides
/opt/iredmail/custom/roundcube/custom.inc.php  # Roundcube overrides

Changes take effect after restarting the container.

SSL Certificates

iRedMail generates a self-signed certificate on first run. For production, replace it with a real certificate:

# Copy your certificates into the SSL volume
docker cp /path/to/fullchain.pem iredmail:/opt/iredmail/ssl/cert.pem
docker cp /path/to/privkey.pem iredmail:/opt/iredmail/ssl/key.pem

# Restart to apply
docker compose restart

Or mount your Let’s Encrypt certificates directly:

volumes:
  - /etc/letsencrypt/live/mail.example.com/fullchain.pem:/opt/iredmail/ssl/cert.pem:ro
  - /etc/letsencrypt/live/mail.example.com/privkey.pem:/opt/iredmail/ssl/key.pem:ro

Reverse Proxy

iRedMail includes its own Nginx for the web interface. If you run a separate reverse proxy, proxy to port 443 with SSL passthrough, or stop the internal Nginx and proxy to the backend services directly.

For Nginx Proxy Manager or Caddy, use TCP stream proxying for mail ports (25, 465, 587, 143, 993) — these cannot go through HTTP reverse proxies.

See Reverse Proxy Setup for detailed configuration.

Backup

Back up the following volumes regularly:

Volume	Contents	Priority
iredmail_mailboxes	All user emails	Critical
iredmail_mysql	User accounts, domains, settings	Critical
iredmail_ssl	SSL certificates	Important
iredmail_custom	Custom configurations	Important
iredmail_backup	Automated MySQL dumps	Useful (redundant backup)

iRedMail includes automated MySQL backups to /var/vmail/backup/mysql. For full disaster recovery, also back up the named volumes.

See Backup Strategy for a comprehensive approach.

Troubleshooting

Emails Going to Spam

Symptom: Outgoing emails land in recipients’ spam folders. Fix: Verify DNS records (SPF, DKIM, DMARC) are correctly configured. Use mail-tester.com to check your score. Ensure your server IP isn’t on blacklists. See Email Deliverability Guide.

Container Won’t Start

Symptom: Container exits immediately or loops. Fix: Check for special characters in environment variables — iRedMail doesn’t tolerate quotes, whitespace, or tabs in config values. Verify all required variables are set.

ClamAV Using Too Much Memory

Symptom: Container uses 2+ GB RAM. Fix: ClamAV loads virus signatures into memory. If RAM is tight, disable antivirus: USE_ANTISPAM=NO. This saves ~1 GB.

Admin Password Reset

Symptom: Forgot the postmaster password. Fix: FIRST_MAIL_DOMAIN_ADMIN_PASSWORD only works on first run. To reset, access the MariaDB database inside the container:

docker exec -it iredmail mysql -u root -p
UPDATE vmail.mailbox SET password=ENCRYPT('NewPassword') WHERE username='[email protected]';

Port 25 Blocked

Symptom: Can send emails but outgoing delivery fails. Fix: Many cloud providers (AWS, GCP, Azure, some Hetzner plans) block outbound port 25. Request port 25 unblock from your provider, or configure a relay host in Postfix.

Resource Requirements

Resource	Minimum	Recommended
RAM	4 GB	6 GB
CPU	2 cores	4 cores
Disk	20 GB	50 GB+ (depends on mailbox sizes)

ClamAV and SpamAssassin are the biggest resource consumers. Disabling antivirus drops RAM usage by ~1 GB.

Verdict

iRedMail is the fastest way to deploy a complete, production-capable email server. Everything — Postfix, Dovecot, spam filtering, webmail, admin panel — runs in a single container. The trade-off is flexibility: you can’t easily swap components or scale individual services independently. The Docker edition is officially in beta (repository archived December 2024), so while it works, updates may be infrequent.

For most self-hosters who want a turnkey email solution, Mailcow is the better choice — it’s actively maintained, uses a proper multi-container architecture, and has a polished web UI. Choose iRedMail if you prefer its all-in-one approach or are already familiar with iRedMail from bare-metal installations.

Related

• Mailu vs iRedMail: Which Mail Server?
• Best Self-Hosted Email Servers
• How to Self-Host Mailcow
• How to Self-Host Mailu
• Mailcow vs iRedMail
• Self-Hosted Alternatives to Gmail
• Email Deliverability Guide
• Docker Compose Basics
• Reverse Proxy Setup
• Backup Strategy