This is a community contributed guide. Please let us know via a Github Issue if you're having any difficulty following the guide so that we can update it.
This guide is focused on only using SMTP ports (not POP3 and IMAP) with the intent to send received mail to another MTA service such as Gmail. It is not intended to have a MUA client (eg: Thunderbird) to retrieve mail directly from
docker-mailserver via POP3/IMAP.
In this setup
docker-mailserver is not intended to receive email externally, so no anti-spam or anti-virus software is needed, making the service lighter to run.
Adding the docker network's gateway to the list of trusted hosts (eg: using the
connected-networks option), can create an open relay. For instance if IPv6 is enabled on the host machine, but not in Docker.
If you're running a version of
docker-mailserverearlier than v10.2, you'll need to get
setup.sh. Otherwise you can substitute
docker exec mailserver setup <command>.
Pull the docker image:
docker pull docker.io/mailserver/docker-mailserver:latest.
Create the file
docker-compose.ymlwith a content like this:
version: '3.8' services: mailserver: image: docker.io/mailserver/docker-mailserver:latest container_name: mailserver hostname: mail # Change this to your domain, it is used for your email accounts (eg: firstname.lastname@example.org): domainname: example.com ports: - "25:25" - "587:587" - "465:465" volumes: - ./docker-data/dms/mail-data/:/var/mail/ - ./docker-data/dms/mail-state/:/var/mail-state/ - ./docker-data/dms/mail-logs/:/var/log/mail/ - ./docker-data/dms/config/:/tmp/docker-mailserver/ # The "from" path will vary based on where your certs are locally: - ./docker-data/nginx-proxy/certs/:/etc/letsencrypt/ - /etc/localtime:/etc/localtime:ro environment: - ENABLE_FAIL2BAN=1 # Using letsencrypt for SSL/TLS certificates - SSL_TYPE=letsencrypt # Allow sending emails from other docker containers # Beware creating an Open Relay: https://docker-mailserver.github.io/docker-mailserver/edge/config/environment/#permit_docker - PERMIT_DOCKER=network # All env below are default settings: - ONE_DIR=1 - ENABLE_POSTGREY=0 - ENABLE_CLAMAV=0 - ENABLE_SPAMASSASSIN=0 # You may want to enable this: https://docker-mailserver.github.io/docker-mailserver/edge/config/environment/#spoof_protection # See step 8 below, which demonstrates setup with enabled/disabled SPOOF_PROTECTION: - SPOOF_PROTECTION=0 cap_add: - NET_ADMIN # For Fail2Ban to work
- The docs have a detailed page on Environment Variables for reference.
You may need to open ports
465on the firewall. For example, with the firewall
ufw allow 25 ufw allow 587 ufw allow 465
Configure your DNS service to use an MX record for the hostname (eg:
If you manually manage the DNS zone file for the domain, it would look something like this:
mail IN A 10.11.12.13 ; mail-server for example.com 3600 IN MX 1 mail.example.com. ; Add SPF record IN TXT "v=spf1 mx ~all"
Then don't forget to change the serial number and to restart the service.
Generate DKIM keys for your domain via
./setup.sh config dkim.
Copy the content of the file
docker-data/dms/config/opendkim/keys/example.com/mail.txtand add it to your DNS records as a TXT like SPF was handled above.
I use bind9 for managing my domains, so I just paste it on
mail._domainkey IN TXT ( "v=DKIM1; h=sha256; k=rsa; " "p=MIIBIjANBgkqhkiG9w0BAQEFACAQ8AMIIBCgKCAQEAaH5KuPYPSF3Ppkt466BDMAFGOA4mgqn4oPjZ5BbFlYA9l5jU3bgzRj3l6/Q1n5a9lQs5fNZ7A/HtY0aMvs3nGE4oi+LTejt1jblMhV/OfJyRCunQBIGp0s8G9kIUBzyKJpDayk2+KJSJt/lxL9Iiy0DE5hIv62ZPP6AaTdHBAsJosLFeAzuLFHQ6USyQRojefqFQtgYqWQ2JiZQ3" "iqq3bD/BVlwKRp5gH6TEYEmx8EBJUuDxrJhkWRUk2VDl1fqhVBy8A9O7Ah+85nMrlOHIFsTaYo9o6+cDJ6t1i6G1gu+bZD0d3/3bqGLPBQV9LyEL1Rona5V7TJBGg099NQkTz1IwIDAQAB" ) ; ----- DKIM key mail for example.com
Get an SSL certificate, we have a guide for you here (Let's Encrypt is a popular service to get free SSL certificates).
docker-mailserverand check the terminal output for any errors:
Create email accounts and aliases:
./setup.sh email add email@example.com passwd123 ./setup.sh email add firstname.lastname@example.org passwd123 ./setup.sh alias add email@example.com firstname.lastname@example.org ./setup.sh alias add email@example.com firstname.lastname@example.org ./setup.sh email list ./setup.sh alias list
Aliases make sure that any email that comes to these accounts is forwarded to your third-party email address (
email@example.com), where they are retrieved (eg: via third-party web or mobile app), instead of connecting directly to
docker-mailsererwith POP3 / IMAP.
./setup.sh email add firstname.lastname@example.org passwd123 ./setup.sh email add email@example.com passwd123 ./setup.sh alias add firstname.lastname@example.org email@example.com ./setup.sh alias add firstname.lastname@example.org email@example.com ./setup.sh alias add firstname.lastname@example.org email@example.com ./setup.sh alias add firstname.lastname@example.org email@example.com ./setup.sh email list ./setup.sh alias list
This extra step is required to avoid the
553 5.7.1 Sender address rejected: not owned by usererror (the accounts used for submitting mail to Gmail are
Send some test emails to these addresses and make other tests. Once everything is working well, stop the container with
ctrl+cand start it again as a daemon:
docker-compose up -d.