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 prefered distro. 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| mail._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* 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/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 `OPENDKIM_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).\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/hardware/mailserver/master/docker-compose.sample.yml -o docker-compose.yml \\\n&& curl https://raw.githubusercontent.com/hardware/mailserver/master/sample.env -o .env \\\n&& curl https://raw.githubusercontent.com/hardware/mailserver/master/traefik.sample.toml -o traefik/traefik.toml \\\n&& touch traefik/acme/acme.json \\\n&& chmod 600 docker-compose.yml .env traefik/traefik.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/hardware/mailserver/wiki/Postfixadmin-initial-configuration)\n\n#### 3 - Rainloop installation (optional)\n\nRainloop is a simple, modern and fast webmail 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/hardware/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 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/hardware/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| **OPENDKIM_KEY_LENGTH** | Size of your DKIM RSA key pair | *optional* | 1024\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 ratelimiting 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| **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\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_FORCE** | Force TLS connections | **required** if **LDAP_TLS_ENABLED** | false\n| **LDAP_BIND** | Bind to LDAP Server | *optional* | true\n| **LDAP_BIND_DN** | The DN to bind to | **required** if **LDAP_BIND** |\n| **LDAP_BIND_PW** | LDAP password or location of a file containing it | **required** if **LDAP_BIND** |\n| **LDAP_DEFAULT_SEARCH_BASE** | The base DN for all lookus | **required** |\n| **LDAP_DEFAULT_SEARCH_SCOPE** | The default scope for all lookups (sub, base or one) | *optional* | sub\n| **LDAP_DOMAIN_SEARCH_BASE** | The search base for domain lookups | *optional* | ${LDAP_DEFAULT_SEARCH_BASE}\n| **LDAP_DOMAIN_SEARCH_SCOPE** | The search scope for domain lookups | *optional* | ${LDAP_DEFAULT_SEARCH_SCOPE}\n| **LDAP_DOMAIN_FILTER** | The search filter for domain lookups | **required** |\n| **LDAP_DOMAIN_ATTRIBUTE** | The attibutes for domain lookup | **required** |\n| **LDAP_DOMAIN_FORMAT** | The format for domain lookups | *optional* |\n| **LDAP_MAILBOX_SEARCH_BASE** | The search base for mailbox lookups | *optional* | ${LDAP_DEFAULT_SEARCH_BASE}\n| **LDAP_MAILBOX_SEARCH_SCOPE** | The search scope for mailbox lookups | *optional* | ${LDAP_DEFAULT_SEARCH_SCOPE}\n| **LDAP_MAILBOX_FILTER** | The search filter for mailbox lookups | **required** |\n| **LDAP_MAILBOX_ATTRIBUTE** | The attibutes for mailbox lookup | **required** |\n| **LDAP_MAILBOX_FORMAT** | The format for domain mailbox | *optional* |\n| **LDAP_ALIAS_SEARCH_BASE** | The search base for domain lookups | *optional* | ${LDAP_DEFAULT_SEARCH_BASE}\n| **LDAP_ALIAS_SEARCH_SCOPE** | The search scope for domain lookups | *optional* | ${LDAP_DEFAULT_SEARCH_SCOPE}\n| **LDAP_ALIAS_FILTER** | The search filter for domain lookups | **required** |\n| **LDAP_ALIAS_ATTRIBUTE** | The attibutes for domain lookup | **required** |\n| **LDAP_ALIAS_FORMAT** | The format for domain lookups | *optional* |\n| **LDAP_FORWARD_SEARCH_BASE** | The search base for forward lookups | *optional* | ${LDAP_DEFAULT_SEARCH_BASE}\n| **LDAP_FORWARD_SEARCH_SCOPE** | The search scope for forward lookups | *optional* | ${LDAP_DEFAULT_SEARCH_SCOPE}\n| **LDAP_FORWARD_FILTER** | The search filter for forward lookups | *optional* |\n| **LDAP_FORWARD_ATTRIBUTE** | The attibutes for forward lookup | *optional* |\n| **LDAP_FORWARD_FORMAT** | The format for forward lookups | *optional* |\n| **LDAP_GROUP_SEARCH_BASE** | The search base for group lookups | *optional* | ${LDAP_DEFAULT_SEARCH_BASE}\n| **LDAP_GROUP_SEARCH_SCOPE** | The search scope for group lookups | *optional* | ${LDAP_DEFAULT_SEARCH_SCOPE}\n| **LDAP_GROUP_FILTER** | The search filter for group lookups | *optional* |\n| **LDAP_GROUP_ATTRIBUTE** | The attibutes for group lookup | *optional* |\n| **LDAP_GROUP_FORMAT** | The format for group lookups | *optional* |\n| **LDAP_SENDER_SEARCH_BASE** | The search base for sender lookups | *optional* | ${LDAP_DEFAULT_SEARCH_BASE}\n| **LDAP_SENDER_SEARCH_SCOPE** | The search scope for sender lookups | *optional* | ${LDAP_DEFAULT_SEARCH_SCOPE}\n| **LDAP_SENDER_FILTER** | The search filter for sender lookups | **required** |\n| **LDAP_SENDER_ATTRIBUTE** | The attibutes for sender lookup | **required** |\n| **LDAP_SENDER_FORMAT** | The format for sender lookups | **required** |\n| **LDAP_DOVECOT_USER_ATTRS** | Dovecot user attribute mapping | **required** |\n| **LDAP_DOVECOT_USER_FILTER** | Dovecot user search filter | **required** |\n| **LDAP_DOVECOT_PASS_ATTRS** | Dovecot user password attribute mapping | **required** |\n| **LDAP_DOVECOT_PASS_FILTER** | Dovecot user password filter | **required** |\n| **LDAP_DOVECOT_ITERATE_ATTRS** | Dovecot user iterate attributes | *optional* |\n| **LDAP_DOVECOT_ITERATE_FILTER** | Dovecot user iterate filters | *optional* |\n| **LDAP_MASTER_USER_ENABLED** | Enable LDAP master users | *optional* | false\n| **LDAP_MASTER_USER_SEPARATOR** | LDAP master user seperator | **required** if **LDAP_MASTER_USER_ENABLED** | \\*\n| **LDAP_MASTER_USER_SEARCH_BASE** | LDAP master user search base | **required** if **LDAP_MASTER_USER_ENABLED** | ${LDAP_DEFAULT_SEARCH_BASE}\n| **LDAP_MASTER_USER_SEARCH_SCOPE** | LDAP master user scope | **required** if **LDAP_MASTER_USER_ENABLED** | ${LDAP_DEFAULT_SEARCH_SCOPE}\n| **LDAP_DOVECOT_MASTER_USER_ATTRS** | LDAP master user dovecot attributes | **required** if **LDAP_MASTER_USER_ENABLED** |\n| **LDAP_DOVECOT_MASTER_USER_FILTER** | LDAP master user dovecot search filter | **required** if **LDAP_MASTER_USER_ENABLED** |\n\n

Back to table of contents :arrow_up_small:

\n\n### Automatic GPG encryption of all your emails\n\n#### How does it work ?\n\n[Zeyple](https://infertux.com/labs/zeyple/) catches email from the postfix queue, then encrypts it if a corresponding recipient's GPG public key is found. Finally, it puts it back into the queue.\n\n![zeyple](https://i.imgur.com/gGQZL4V.png)\n\n#### Enable automatic GPG encryption\n\n:heavy_exclamation_mark: **Please enable this option carefully and only if you know what you are doing.**\n\nSwitch `ENABLE_ENCRYPTION` environment variable to `true`. The public keyring will be saved in `/var/mail/zeyple/keys`.\nPlease don't change the default value of `RECIPIENT_DELIMITER` (default = \"+\"). If encryption is enabled with another delimiter, Zeyple could have an unpredictable behavior.\n\n#### Import your public key\n\n:warning: Make sure to send your public key on a gpg keyserver before to run the following command.\n\n```\ndocker exec -ti mailserver encryption.sh import-key YOUR_KEY_ID\n```\n\n#### Import all recipients public keys\n\nThis command browses all `/var/mail/vhosts/*` domains directories and users subdirectories to find all the recipients addresses in the mailserver.\n\n```\ndocker exec -ti mailserver encryption.sh import-all-keys\n```\n\n#### Specify another gpg keyserver\n\n```\ndocker exec -ti mailserver encryption.sh import-key YOUR_KEY_ID hkp://pgp.mit.edu\ndocker exec -ti mailserver encryption.sh import-all-keys hkp://keys.gnupg.net\n```\n\n#### Run other GPG options\n\nYou can use all options of gpg command line except an already assigned parameter called `--homedir`.\n\n\n```bash\ndocker exec -ti mailserver encryption.sh --list-keys\ndocker exec -ti mailserver encryption.sh --fingerprint\ndocker exec -ti mailserver encryption.sh --refresh-keys\ndocker exec -ti mailserver encryption.sh ...\n```\n\nDocumentation : https://www.gnupg.org/documentation/manuals/gnupg/Operational-GPG-Commands.html\n\n

Back to table of content","has_starred","hub_user","immutable_tags_settings",{"_71":11,"_72":73},"enabled","rules",[74],".*","is_automated","permissions",{"_78":17,"_79":11,"_80":11},"read","write","admin","user","storage_size",626541669,"orgData","recentTags",[87,124],{"_88":40,"_89":90,"_91":92,"_93":94,"_95":96,"_46":113,"_114":90,"_115":29,"_116":52,"_53":117,"_118":119,"_120":104,"_121":113,"_122":62,"_123":17},"content_type","creator",11183203,"full_size",310967362,"id",123825094,"images",[97],{"_98":99,"_100":101,"_102":44,"_103":104,"_105":106,"_107":108,"_109":44,"_110":-5,"_111":92,"_59":62,"_112":-5},"architecture","amd64","digest","sha256:c9fc2ecfe671968d935b67c2b37d7f5808be29300efc39327155920a83074c43","features","last_pulled","2026-09-23T13:39:51.696346132Z","last_pushed","2021-01-27T18:38:55Z","os","linux","os_features","os_version","size","variant","2021-01-27T18:38:54.269548Z","last_updater","last_updater_username","media_type","latest","repository",10132421,"tag_last_pulled","tag_last_pushed","tag_status","v2",{"_88":40,"_89":90,"_91":125,"_93":126,"_95":127,"_46":132,"_114":90,"_115":29,"_116":52,"_53":133,"_118":119,"_120":130,"_121":132,"_122":62,"_123":17},315535485,123834138,[128],{"_98":99,"_100":129,"_102":44,"_103":130,"_105":131,"_107":108,"_109":44,"_110":-5,"_111":125,"_59":62,"_112":-5},"sha256:831048a39eed73acd543ce254ce6b287982fa4a7044279cfc84661d526feb4d3","2026-09-08T08:19:38.493909442Z","2020-10-30T13:59:13Z","2020-10-30T15:00:59.209417Z","0.1","sbxKitMetadata","isPotentialSpam","isHubSbxKitsEnabled","showSbxLogoOverride","sbxTrademarkText","displaySecurityMetadata","tagAttestations","tagsHaveAttestations",[],"routes/_layout.r.$namespace.$reponame.builds",{"_27":11,"_32":-5},"actionData","errors"]

bcornelsen/mailserver