Back to table of contents :arrow_up_small:

\n\n### Prerequisites\n\n#### Cleaning\n\nPlease remove any web server and mail services running on your server. I recommend using a clean installation of your preferred distribution. If you are using Debian, remember to remove the default MTA **Exim4**:\n\n```\n# apt-get purge exim4*\n```\n\nAlso make sure that no other application is interfering with mail server configuration:\n\n```\n# netstat -tulpn | grep -E -w '25|80|110|143|443|465|587|993|995|4190'\n```\n\nIf this command returns any results please remove or stop the application running on that port.\n\n#### Ports\n\nIf you have a firewall, unblock the following ports, according to your needs:\n\n| Service | Software | Protocol | Port |\n| ----------- | -------- | -------- | ---- |\n| SMTP | Postfix | TCP | 25 |\n| HTTP | Nginx | TCP | 80 |\n| POP3 | Dovecot | TCP | 110 |\n| IMAP | Dovecot | TCP | 143 |\n| HTTPS | Nginx | TCP | 443 |\n| SMTPS | Postfix | TCP | 465 |\n| Submission | Postfix | TCP | 587 |\n| IMAPS | Dovecot | TCP | 993 |\n| POP3S | Dovecot | TCP | 995 |\n| ManageSieve | Dovecot | TCP | 4190 |\n\n#### DNS setup\n\nI recommend you to use [hardware/nsd-dnssec](https://github.com/hardware/nsd-dnssec) as an authoritative name server with DNSSEC capabilities. NSD is an authoritative only, high performance, simple and open source name server.\n\n#### DNS records and reverse PTR\n\nA correct DNS setup is required, this step is very important.\n\n| HOSTNAME | CLASS | TYPE | PRIORITY | VALUE |\n| ----------------------- | ----- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |\n| mail | IN | A/AAAA | any | 1.2.3.4 |\n| spam | IN | CNAME | any | mail.domain.tld. |\n| webmail | IN | CNAME | any | mail.domain.tld. |\n| postfixadmin | IN | CNAME | any | mail.domain.tld. |\n| @ | IN | MX | 10 | mail.domain.tld. |\n| @ | IN | TXT | any | \"v=spf1 a mx ip4:SERVER_IPV4 ~all\" |\n| {{selector}}._domainkey | IN | TXT | any | \"v=DKIM1; k=rsa; p=YOUR DKIM Public Key\" |\n| _dmarc | IN | TXT | any | \"v=DMARC1; p=reject; rua=mailto:postmaster@domain.tld; ruf=mailto:admin@domain.tld; fo=0; adkim=s; aspf=s; pct=100; rf=afrf; sp=reject\" |\n\n**Notes:**\n\n* Make sure that the **PTR record** of your IP matches the FQDN (default: mail.domain.tld) of your mailserver host. This record is usually set in your web hosting interface.\n* {{selector}} defaults to ``mail`` unless changed via ``DKIM_SELECTOR``\n* DKIM, SPF and DMARC records are recommended to build a good reputation score.\n* The DKIM public key will be available on host after the container startup:\n\n```\n/mnt/docker/mail/dkim/domain.tld/{{selector}}.public.key\n```\n\nTo regenerate your public and private keys, remove the `/mnt/docker/mail/dkim/domain.tld` folder. By default a **1024-bit** key is generated, you can increase this size by setting the `DKIM_KEY_LENGTH` environment variable with a higher value. Check your domain registrar support to verify that it supports a TXT record long enough for a key larger than 1024 bits.\n\nThese DNS record will raise your trust reputation score and reduce abuse of your domain name. You can find more information here:\n\n* http://www.openspf.org/\n* http://www.opendkim.org/\n* https://dmarc.org/\n* http://arc-spec.org/\n\n#### Testing\n\nYou can audit your mailserver with the following assessment services:\n\n* https://www.mail-tester.com/\n* https://www.hardenize.com/\n* https://observatory.mozilla.org/\n* https://www.emailprivacytester.com/ (MUA side)\n\n

Back to table of contents :arrow_up_small:

\n\n### Installation\n\n#### 1 - Prepare your environment\n\n:bulb: The reverse proxy used in this setup is [Traefik](https://traefik.io/), but you can use the solution of your choice (Nginx, Apache, Haproxy, Caddy, H2O, etc pp).\n\n:warning: This docker image may not work with some hardened Linux distribution using security-enhancing kernel patches like GrSecurity, please use a [supported platform](https://docs.docker.com/install/#supported-platforms).\n\n```bash\n# Create a new docker network for Traefik (IPv4 only)\ndocker network create http_network\n# If you want to support IPv6, please refer to [IPv6 support]\n\n# Create the required folders and files\nmkdir -p /mnt/docker/traefik/acme && cd /mnt/docker \\\n&& curl https://raw.githubusercontent.com/mailserver2/mailserver/master/docker-compose.sample.yml -o docker-compose.yml \\\n&& curl https://raw.githubusercontent.com/mailserver2/mailserver/master/sample.env -o .env \\\n&& curl https://raw.githubusercontent.com/mailserver2/mailserver/master/traefik.sample.toml -o traefik/traefik.toml \\\n&& curl https://raw.githubusercontent.com/mailserver2/mailserver/master/file.sample.toml -o traefik/file.toml \\\n&& touch traefik/acme/acme.json \\\n&& chmod 600 docker-compose.yml .env traefik/traefik.toml traefik/file.toml traefik/acme/acme.json\n```\n\nEdit the `.env` and `traefik.toml`, adapt to your needs, then start all services:\n\n```\ndocker-compose up -d\n```\n\n#### 2 - Postfixadmin installation\n\nPostfixAdmin is a web based interface used to manage mailboxes, virtual domains and aliases.\n\n* Docker image: https://github.com/hardware/postfixadmin\n* How to setup: [Postfixadmin initial configuration](https://github.com/mailserver2/mailserver/wiki/Postfixadmin-initial-configuration)\n\n#### 3 - Rainloop installation (optional)\n\nRainloop is a simple, modern and fast web mail front end with Sieve scripts support (filters and vacation message), GPG and a modern user interface.\n\n* Docker image: https://github.com/hardware/rainloop\n* How to setup: [Rainloop initial configuration](https://github.com/mailserver2/mailserver/wiki/Rainloop-initial-configuration)\n\n#### 4 - Done, congratulation ! :tada:\n\nAt first launch, the container takes few minutes to generate SSL certificates (if needed), DKIM keypair generation and update Clamav database, all of this takes some time (1/2 minutes). This image comes with a snake-oil self-signed certificate, please use your own trusted certificates. [See below](https://github.com/mailserver2/mailserver#ssl-certificates) for configuration.\n\n**List of webservices available:**\n\n| Service | URI |\n| --------------------- | -------------------------------- |\n| **Traefik dashboard** | https://mail.domain.tld/ |\n| **Rspamd dashboard** | https://spam.domain.tld/ |\n| **Administration** | https://postfixadmin.domain.tld/ |\n| **Webmail** | https://webmail.domain.tld/ |\n\nTraefik dashboard use a basic authentication (user:admin, password:12345), the password can be encoded in MD5, SHA1 and BCrypt. You can use [htpasswd ](https://httpd.apache.org/docs/2.4/programs/htpasswd.html) to generate those ones. Users can be specified directly in the `traefik.toml` file. Rspamd dashboard use the password defined in your `docker-compose.yml`.\n\nYou can check the startup logs with this command:\n\n```\n# docker logs -f mailserver\n\n[INFO] Let's encrypt live directory found\n[INFO] Using /etc/letsencrypt/live/mail.domain.tld folder\n[INFO] Creating DKIM keys for domain domain.tld\n[INFO] Database hostname found in /etc/hosts\n[INFO] Fetchmail forwarding is enabled.\n[INFO] Automatic GPG encryption is enabled.\n[INFO] ManageSieve protocol is enabled.\n[INFO] POP3 protocol is enabled.\n-------------------------------------------------------------------------------------\n2017-08-26T11:06:58.885562+00:00 mail root: s6-supervise : spawning clamd process\n2017-08-26T11:06:59.059077+00:00 mail root: s6-supervise : spawning freshclam process\n2017-08-26T11:06:59.395214+00:00 mail root: s6-supervise : spawning rspamd process\n2017-08-26T11:07:01.615597+00:00 mail root: s6-supervise : spawning unbound process\n2017-08-26T11:07:01.870856+00:00 mail root: s6-supervise : spawning postfix process\n2017-08-26T11:07:03.303536+00:00 mail root: s6-supervise : spawning dovecot process\n...\n```\n\n

Back to table of contents :arrow_up_small:

\n\n### Rancher Catalog\n\n![rancher-logo](https://i.imgur.com/R9AArJN.png)\n\nhttps://github.com/hardware/mailserver-rancher\n\nThis catalog provides a basic template to easily deploy an email server based on [hardware/mailserver](https://github.com/hardware/mailserver) very quickly. To use it, just add this repository to your Rancher system as a catalog in `Admin > Settings` page and follow [the readme](https://github.com/hardware/mailserver-rancher/blob/master/README.md). This catalog has been initiated by [@MichelDiz](https://github.com/MichelDiz).\n\n![rancher-ui](https://i.imgur.com/kdJxAiN.png)\n\n

Back to table of contents :arrow_up_small:

\n\n### Ansible Playbooks\n\n![logo](https://i.imgur.com/tvTG8pN.png)\n\nIf you use Ansible, I recommend you to go to see [@ksylvan](https://github.com/ksylvan) playbooks here: https://github.com/ksylvan/docker-mail-server\n\n

Back to table of contents :arrow_up_small:

\n\n### Environment variables\n\n| Variable | Description | Type | Default value |\n| -------------------------------- | ---------------------------------------------------------------------------------------- | ------------------- | --------------------- |\n| **VMAILUID** | vmail user id | *optional* | 1024 |\n| **VMAILGID** | vmail group id | *optional* | 1024 |\n| **VMAIL_SUBDIR** | Individual mailbox' subdirectory | *optional* | mail |\n| **DKIM_KEY_LENGTH** | Size of your DKIM RSA key pair | *optional* | 1024 |\n| **DKIM_SELECTOR** | Your DKIM selector | *optional* | `mail` |\n| **DEBUG_MODE** | Enable Postfix, Dovecot, Rspamd and Unbound verbose logging | *optional* | false |\n| **PASSWORD_SCHEME** | Passwords encryption scheme | *optional* | `SHA512-CRYPT` |\n| **DBDRIVER** | Database type: mysql, pgsql, ldap | *optional* | mysql |\n| **DBHOST** | Database instance ip/hostname | *optional* | mariadb |\n| **DBPORT** | Database instance port | *optional* | 3306 / 389 (sql/ldap) |\n| **DBUSER** | Database username | *optional* | postfix |\n| **DBNAME** | Database name | *optional* | postfix |\n| **DBPASS** | Database password or location of a file containing it | **required** *\\*1)* | null |\n| **REDIS_HOST** | Redis instance ip/hostname | *optional* | redis |\n| **REDIS_PORT** | Redis instance port | *optional* | 6379 |\n| **REDIS_PASS** | Redis database password or location of a file containing it | *optional* | null |\n| **REDIS_NUMB** | Redis database number | *optional* | 0 |\n| **RSPAMD_PASSWORD** | Rspamd WebUI and controller password or location of a file containing it | **required** | null |\n| **ADD_DOMAINS** | Add additional domains to the mailserver separated by commas (needed for dkim keys etc.) | *optional* | null |\n| **RELAY_NETWORKS** | Additional IPs or networks the mailserver relays without authentication | *optional* | null |\n| **WHITELIST_SPAM_ADDRESSES** | List of whitelisted email addresses separated by commas | *optional* | null |\n| **DISABLE_RSPAMD_MODULE** | List of disabled modules separated by commas | *optional* | null |\n| **DISABLE_CLAMAV** | Disable virus scanning | *optional* | false |\n| **DISABLE_SIEVE** | Disable ManageSieve protocol | *optional* | false |\n| **DISABLE_SIGNING** | Disable DKIM/ARC signing | *optional* | false |\n| **DISABLE_GREYLISTING** | Disable greylisting policy | *optional* | false |\n| **DISABLE_RATELIMITING** | Disable rate limiting policy | *optional* | true |\n| **DISABLE_DNS_RESOLVER** | Disable the local DNS resolver | *optional* | false |\n| **DISABLE_SSL_WATCH** | Disable watching of `acme.json` and the Let's Encrypt directory | *optional* | false |\n| **DISABLE_VHOSTS_OWNERSHIP_SET** | Disable set permission on `vhosts` folder | *optional* | false |\n| **ENABLE_POP3** | Enable POP3 protocol | *optional* | false |\n| **ENABLE_FETCHMAIL** | Enable fetchmail forwarding | *optional* | false |\n| **ENABLE_ENCRYPTION** | Enable automatic GPG encryption | *optional* | false |\n| **FETCHMAIL_INTERVAL** | Fetchmail polling interval | *optional* | 10 |\n| **RECIPIENT_DELIMITER** | RFC 5233 subaddress extension separator (single character only) | *optional* | + |\n\n\\*1) **DBPASS** is NOT required when using LDAP authentication\n\n* Use **DEBUG_MODE** to enable the debug mode. Switch to `true` to enable verbose logging for `postfix`, `dovecot`, `rspamd` and `Unbound`. To debug components separately, use this syntax: `DEBUG_MODE=postfix,rspamd`.\n* **VMAIL_SUBDIR** is the mail location subdirectory name `/var/mail/vhosts/%domain/%user/$subdir`. For more information, read this: https://wiki.dovecot.org/VirtualUsers/Home\n* **PASSWORD_SCHEME** for compatible schemes, read this: https://wiki.dovecot.org/Authentication/PasswordSchemes\n* Currently, only a single **RECIPIENT_DELIMITER** is supported. Support for multiple delimiters will arrive with Dovecot v2.3.\n* **FETCHMAIL_INTERVAL** must be a number between **1** and **59** minutes.\n* Use **DISABLE_DNS_RESOLVER** if you have some DNS troubles and DNSSEC lookup issues with the local DNS resolver.\n* Use **DISABLE_RSPAMD_MODULE** to disable any module listed here: https://rspamd.com/doc/modules/\n* **OPENDKIM_KEY_LENGTH** has been renamed to **DKIM_KEY_LENGTH**, but falls back to **OPENDKIM_KEY_LENGTH** for backwards compatability\n\nWhen using LDAP authentication the following additional variables become available. All *DBUSER*, *DBNAME* and *DBPASS* variables will not be used in this case:\n\n| Variable | Description | Type | Default value |\n| ----------------------------------- | ---------------------------------------------------- | -------------------------------------------- | ---------------------------- |\n| **LDAP_TLS_ENABLED** | Enable TLS on LDAP | *optional* | false |\n| **LDAP_TLS_CA_FILE** | The TLS CA File | **required** if **LDAP_TLS_ENABLED** |\n| **LDAP_TLS_F","has_starred","hub_user","immutable_tags_settings",{"_75":11,"_76":77},"enabled","rules",[78],".*","is_automated","permissions",{"_82":21,"_83":11,"_84":11},"read","write","admin","user","storage_size",1648760399,"orgData",{"_90":91,"_92":93,"_94":95,"_96":33,"_97":48,"_98":48,"_99":48,"_100":48,"_101":102,"_103":48,"_104":48,"_105":48,"_106":21},"id","be3236af6d7e426881ec2d848344d20a","uuid","be3236af-6d7e-4268-81ec-2d848344d20a","type","organization","orgname","full_name","location","company","profile_url","date_joined","2019-02-10T19:56:26.90248Z","gravatar_url","gravatar_email","badge","is_active","recentTags",[109,145,155,165,175,185,191,201,211,221],{"_110":44,"_111":112,"_113":114,"_90":115,"_116":117,"_50":134,"_135":112,"_136":33,"_137":56,"_57":138,"_139":140,"_141":125,"_142":134,"_143":66,"_144":21},"content_type","creator",5393168,"full_size",116570558,86961821,"images",[118],{"_119":120,"_121":122,"_123":48,"_124":125,"_126":127,"_128":129,"_130":48,"_131":-5,"_132":114,"_63":66,"_133":-5},"architecture","amd64","digest","sha256:e693e670b5a1c4f117d2216c882f19d29bd480c7d077bd6a8b3b8aedd8e8d3cc","features","last_pulled","2026-10-03T03:45:27.034242773Z","last_pushed","2021-01-11T17:57:16Z","os","linux","os_features","os_version","size","variant","2021-06-23T17:13:04.858247Z","last_updater","last_updater_username","media_type","latest","repository",8493638,"tag_last_pulled","tag_last_pushed","tag_status","v2",{"_110":44,"_111":112,"_113":146,"_90":147,"_116":148,"_50":153,"_135":112,"_136":33,"_137":56,"_57":154,"_139":140,"_141":151,"_142":153,"_143":66,"_144":21},116926927,155409292,[149],{"_119":120,"_121":150,"_123":48,"_124":151,"_126":152,"_128":129,"_130":48,"_131":-5,"_132":146,"_63":66,"_133":-5},"sha256:765ce4b4dcff43884a90fb2fad862026c2234122f33c6dfe339f28a61821e7e6","2026-10-03T03:45:26.847875664Z","2021-06-23T17:26:46Z","2021-06-23T17:26:45.378665Z","v1.1.7",{"_110":44,"_111":112,"_113":156,"_90":157,"_116":158,"_50":163,"_135":112,"_136":33,"_137":56,"_57":164,"_139":140,"_141":161,"_142":163,"_143":66,"_144":21},116926648,155408760,[159],{"_119":120,"_121":160,"_123":48,"_124":161,"_126":162,"_128":129,"_130":48,"_131":-5,"_132":156,"_63":66,"_133":-5},"sha256:0115276894c87ae059f110fd607399465600cba16442d60e70f3145d5d49eb39","2026-10-03T03:45:26.865533598Z","2021-06-23T17:23:32Z","2021-06-23T17:23:31.873801Z","v1.1.6",{"_110":44,"_111":112,"_113":166,"_90":167,"_116":168,"_50":173,"_135":112,"_136":33,"_137":56,"_57":174,"_139":140,"_141":171,"_142":173,"_143":66,"_144":21},116570898,155408233,[169],{"_119":120,"_121":170,"_123":48,"_124":171,"_126":172,"_128":129,"_130":48,"_131":-5,"_132":166,"_63":66,"_133":-5},"sha256:132e93db5647946b02fbeca6144c335fc799c367d6386cbfb3c0ec4d2ee5cf1c","2026-10-03T03:45:26.85144005Z","2021-01-11T19:02:45Z","2021-06-23T17:18:59.904713Z","v1.4.1",{"_110":44,"_111":112,"_113":176,"_90":177,"_116":178,"_50":183,"_135":112,"_136":33,"_137":56,"_57":184,"_139":140,"_141":181,"_142":183,"_143":66,"_144":21},116570573,86963902,[179],{"_119":120,"_121":180,"_123":48,"_124":181,"_126":182,"_128":129,"_130":48,"_131":-5,"_132":176,"_63":66,"_133":-5},"sha256:3817fd568c259682e0d351efe8ee2fcade417316d14930033856a491c315aa89","2026-10-03T03:45:27.001181891Z","2021-01-11T18:55:24Z","2021-06-23T17:15:59.500816Z","master",{"_110":44,"_111":112,"_113":166,"_90":186,"_116":187,"_50":189,"_135":112,"_136":33,"_137":56,"_57":190,"_139":140,"_141":171,"_142":189,"_143":66,"_144":21},132780239,[188],{"_119":120,"_121":170,"_123":48,"_124":171,"_126":172,"_128":129,"_130":48,"_131":-5,"_132":166,"_63":66,"_133":-5},"2021-01-11T19:02:44.886052Z","v1.4.0",{"_110":44,"_111":112,"_113":192,"_90":193,"_116":194,"_50":199,"_135":112,"_136":33,"_137":56,"_57":200,"_139":140,"_141":197,"_142":199,"_143":66,"_144":21},117430627,123541269,[195],{"_119":120,"_121":196,"_123":48,"_124":197,"_126":198,"_128":129,"_130":48,"_131":-5,"_132":192,"_63":66,"_133":-5},"sha256:716a0a9c77910f54f178cc3f4e1000d820420a781dffd93fec35bfc834cac70a","2026-10-03T03:45:27.718853431Z","2020-10-28T19:38:46Z","2020-10-28T19:38:45.991915Z","v1.1.2",{"_110":44,"_111":112,"_113":202,"_90":203,"_116":204,"_50":209,"_135":112,"_136":33,"_137":56,"_57":210,"_139":140,"_141":207,"_142":209,"_143":66,"_144":21},115333286,123540580,[205],{"_119":120,"_121":206,"_123":48,"_124":207,"_126":208,"_128":129,"_130":48,"_131":-5,"_132":202,"_63":66,"_133":-5},"sha256:8f32989342e3f6967875ee04bfb96fc0618d2895c31a743deccccd640bb8c23c","2026-10-03T03:45:27.701543442Z","2020-10-28T19:33:49Z","2020-10-28T19:33:48.286882Z","v1.1.3",{"_110":44,"_111":112,"_113":212,"_90":213,"_116":214,"_50":219,"_135":112,"_136":33,"_137":56,"_57":220,"_139":140,"_141":217,"_142":219,"_143":66,"_144":21},116117536,123539813,[215],{"_119":120,"_121":216,"_123":48,"_124":217,"_126":218,"_128":129,"_130":48,"_131":-5,"_132":212,"_63":66,"_133":-5},"sha256:0a6a82bcfd9c8f029af0cd38b52eb21e1b694fd5340fb577cc4af5ba14b0c265","2026-10-03T03:45:28.737480784Z","2020-10-28T19:28:58Z","2020-10-28T19:28:57.143396Z","v1.3.0",{"_110":44,"_111":112,"_113":222,"_90":223,"_116":224,"_50":229,"_135":112,"_136":33,"_137":56,"_57":230,"_139":140,"_141":227,"_142":229,"_143":66,"_144":21},123758525,122007821,[225],{"_119":120,"_121":226,"_123":48,"_124":227,"_126":228,"_128":129,"_130":48,"_131":-5,"_132":222,"_63":66,"_133":-5},"sha256:71b6d94a90708f42ed798f5c91c7292464c120ba4bb13ef7847902059fe60759","2026-10-03T03:45:28.714278368Z","2020-10-18T11:39:33Z","2020-10-18T11:39:32.55426Z","v1.2.0","sbxKitMetadata","isPotentialSpam","isHubSbxKitsEnabled","showSbxLogoOverride","sbxTrademarkText","displaySecurityMetadata","tagAttestations","tagsHaveAttestations",[],"selectedTag","attestationsUrl","routes/_layout.r.$namespace.$reponame.builds",{"_31":11,"_36":-5},"actionData","errors"]

oursource/mailserver