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\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/datoma/mailserver/master/docker-compose.sample.yml -o docker-compose.yml \\\n&& curl https://raw.githubusercontent.com/datoma/mailserver/master/sample.env -o .env \\\n&& curl https://raw.githubusercontent.com/datoma/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/datoma/postfixadmin\n* How to setup : [Postfixadmin initial configuration] Postfixadmin-initial-configuration.md\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/datoma/rainloop\n* How to setup : [Rainloop initial configuration] Rainloop-initial-configuration).md\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/datoma/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### 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 contents :arrow_up_small:

\n\n### Relaying from other networks\n\nThe **RELAY_NETWORKS** is a space separated list of additional IP addresses and subnets (in CIDR notation) which the mailserver relays without authentication. Hostnames are possible, but generally disadvised. IPv6 addresses must be surrounded by square brackets. You can also specify an absolut path to a file with IPs and networks so you can keep it on a mounted volume. Note that the file is not monitored for changes.\n\nYou can use this variable to allow other local containers to relay via the mailserver. Typically you would set this to the IP range of the default docker bridge (172.17.0.0/16) or the default network of your compose. If you are unable to determine, you might just add all RFC 1918 addresses `192.168.0.0/16 172.16.0.0/12 10.0.0.0/8`\n\n:warning: A value like `0.0.0.0/0` will turn your mailserver into an open relay!\n\n

Back to table of contents :arrow_up_small:

\n\n### SSL certificates\n\n#### Let's Encrypt certificates generated by Traefik\n\nTo use Let's Encrypt certificates generated by Traefik, mount a new docker volume like this :\n\n```yml\nmailserver:\n image: datoma/mailserver\n volumes:\n - /mnt/docker/traefik/acme:/etc/letsencrypt/acme\n ...\n```\n\nThe startup script read the `acme.json`* file generated by Traefik and split into pem files all appropriate certificates (CN = mail.domain.tld).\n\n:bulb: *Compatible with both Traefik `>=1.5.0` and `1.6+` ACME json format, with **SAN** and **wildcard** certificates support.\n\n```\ndocker logs -f mailserver\n\n[INFO] Search for SSL certificates generated by Traefik\n[INFO] acme.json found with ACME v2 format, dumping into pem files\n[INFO] Let's encrypt live directory found\n[INFO] Using /etc/letsencrypt/live/mail.domain.tld folder\n```\n\nDon't forget to add a new traefik frontend rule somewhere in your docker-c","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",461658568,"orgData","recentTags",[87],{"_88":40,"_89":90,"_91":92,"_93":94,"_95":96,"_46":114,"_115":90,"_116":29,"_117":52,"_53":118,"_119":120,"_121":105,"_122":114,"_123":62,"_124":17},"content_type","creator",787559,"full_size",114432862,"id",96160130,"images",[97],{"_98":99,"_100":101,"_102":103,"_104":105,"_106":107,"_108":109,"_110":103,"_111":-5,"_112":92,"_59":62,"_113":-5},"architecture","amd64","digest","sha256:9124ed5976fef35f6ec7d94347c5937b967c01db07f136b050490b5b33e7a76e","features","","last_pulled","2026-09-23T01:02:12.354159437Z","last_pushed","2020-04-20T21:33:48Z","os","linux","os_features","os_version","size","variant","2020-04-20T21:33:47.150992Z","last_updater","last_updater_username","media_type","latest","repository",8863276,"tag_last_pulled","tag_last_pushed","tag_status","v2","sbxKitMetadata","isPotentialSpam","isHubSbxKitsEnabled","showSbxLogoOverride","sbxTrademarkText","displaySecurityMetadata","tagAttestations","tagsHaveAttestations",[],"routes/_layout.r.$namespace.$reponame.builds",{"_27":11,"_32":-5},"actionData","errors"]