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#### 3bis - Afterlogic Webmail Lite installation (optional)\n\nAccording to your preference, you can use Afterlogic Webmail Lite as alternative.\n\n* Docker image : https://github.com/hardware/afterlogic-webmail-lite\n* How to setup : [Afterlogic Webmail Lite initial configuration](https://github.com/hardware/mailserver/wiki/AfterLogic-Webmail-Lite-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 | *optional* | mysql\n| **DBHOST** | Database instance ip/hostname | *optional* | mariadb\n| **DBPORT** | Database instance port | *optional* | 3306\n| **DBUSER** | Database username | *optional* | postfix\n| **DBNAME** | Database name | *optional* | postfix\n| **DBPASS** | Database password or location of a file containing it | **required** | 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* 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

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: hardware/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-compose.yml to generate a certificate for your mailserver FQDN (default : mail.domain.tld) subdomain.\n\n```yml\n# docker-compose.yml\n\nlabels:\n - traefik.frontend.rule=Host:mail.${DOMAIN}\n```\n\nAlternatively, you can specify your domains in the `traefik.toml` to generate a SAN certificate :\n\n```toml\n[acme]\nonHostRule = false\n\n[[acme.domains]]\nmain = \"domain.tld\"\nsans = [\"mail.domain.tld\", \"spam.domain.tld\", \"postfixadmin.domain.tld\", \"webmail.domain.tld\"]\n```\n\nOr a wildcard certificate :\n\n:warning: ACME wildcard certificates can only be generated thanks to a `DNS-01` challenge.\n\n```toml\n[acme]\nonHostRule = false\n\n# https://docs.traefik.io/v1.6/configuration/acme/#dnschallenge\n[acme.dnsChallenge]\nprovider = \"your_dns_provider\"\ndelayBeforeCheck = 0\n\n[[acme.domains]]\nmain = \"*.domain.tld\"\n```\n\nIf the startup script does not find the appropriate SSL certificate and private key, look at Traefik's logs to see what's going on.\n\n```\ndocker logs -f mailserver\n\n[INFO] Search for SSL certificates generated by Traefik\n[INFO] ...\n[INFO] ...\n[INFO] acme.json found with ACME v2 format, dumping into pem files\n[ERROR] The certificate for mail.domain.tld or the private key was not found !\n[INFO] Don't forget to add a new traefik frontend rule to generate a certificate for mail.domain.tld subdomain\n[INFO] Look /mnt/docker/traefik/acme/dump.log and 'docker logs traefik' for more information\n```\n\n```toml\n# traefik.toml\n\n[acme]\nacmeLogging = true\n```\n\n```\ndocker-compose restart traefik && docker logs -f traefik\n```\n\nWhen SSL certificates are renewed, the mail server must be restarted. You can proceed as follows :\n\n1. Install incron `apt-get install incron`\n2. Add `root` user in `/etc/incron.allow`\n3. Create the following incron job with `incrontab -e` :\n\n```\n/mnt/docker/traefik/acme/acme.json IN_MODIFY docker-compose -f /path/to/yml restart mailserver\n```\n\nThis job trigger a restart of the mail server container when traefik's acme file is updated.\n\n#### Custom certificates\n\nYou can use Let's Encrypt or any other certification authority. Setup your `docker-compose.yml` like this :\n\n```yml\nmailserver:\n image: hardware/mailserver\n volumes:\n - /mnt/docker/ssl:/etc/letsencrypt\n ...\n```\n\nRequest your certificates in `/mnt/docker/ssl/live/mail.domain.tld` with an [ACME client](https://letsencrypt.org/docs/client-options/) if you use Let's Encrypt, otherwise get your SSL certificates with the method provided by your CA and put everything needed in this directory.\n\nRequired files in this folder :\n\n:bulb: If you only have the fullchain.pem and privkey.pem, the startup script extract automatically the cert.pem and chain.pem from fullchain.pem.\n\n| Filename | Description |\n|----------|-------------|\n| privkey.pem | Private key for the certificate |\n| cert.pem | Serv","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",334768833,"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",1945217,"full_size",122243099,"id",79036252,"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:b12cbd78862b6e3091790a7f76fe1d1d71dbb34c1d17b279025b09ab9d91c7dc","features","last_pulled","2026-09-13T01:57:50.214901592Z","last_pushed","2019-12-07T12:29:02Z","os","linux","os_features","os_version","size","variant","2019-12-07T12:29:01.128464Z","last_updater","last_updater_username","media_type","latest","repository",8140779,"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},131616660,79035485,[128],{"_98":99,"_100":129,"_102":44,"_103":130,"_105":131,"_107":108,"_109":44,"_110":-5,"_111":125,"_59":62,"_112":-5},"sha256:3dd33875d1394e2e0f138a1e54e960f67dbda18cd92f7e4437a16a22e2d426a9","2026-09-01T11:16:20.153173348Z","2019-12-07T17:40:44Z","2019-12-07T17:40:43.957992Z","1.1-stable","sbxKitMetadata","isPotentialSpam","isHubSbxKitsEnabled","displaySecurityMetadata","tagAttestations","tagsHaveAttestations",[],"routes/_layout.r.$namespace.$reponame.tags",{"_34":143,"_150":151,"_139":164,"_165":11},{"_36":144,"_38":145,"_41":42,"_43":44,"_45":11,"_46":47,"_48":49,"_50":146,"_53":31,"_28":29,"_54":55,"_56":40,"_57":58,"_59":60,"_61":62,"_63":-5,"_64":58,"_65":66,"_67":11,"_68":29,"_69":147,"_75":11,"_76":149,"_81":29,"_82":83},[],[40],[52],{"_71":11,"_72":148},[74],{"_78":17,"_79":11,"_80":11},"tags",{"_152":153,"_154":-5,"_155":-5,"_156":157},"count",2,"next","previous","results",[158,161],{"_88":40,"_89":90,"_91":125,"_93":126,"_95":159,"_46":132,"_114":90,"_115":29,"_116":52,"_53":133,"_118":119,"_120":130,"_121":132,"_122":62,"_123":17},[160],{"_98":99,"_100":129,"_102":44,"_103":130,"_105":131,"_107":108,"_109":44,"_110":-5,"_111":125,"_59":62,"_112":-5},{"_88":40,"_89":90,"_91":92,"_93":94,"_95":162,"_46":113,"_114":90,"_115":29,"_116":52,"_53":117,"_118":119,"_120":104,"_121":113,"_122":62,"_123":17},[163],{"_98":99,"_100":101,"_102":44,"_103":104,"_105":106,"_107":108,"_109":44,"_110":-5,"_111":92,"_59":62,"_112":-5},[],"canDeleteTags","actionData","errors"]

xoneso/mailserver

Tags for xoneso/mailserver