README.md

docker-mailserver

1. About
2. Requirements
3. How to use
   1. How to update domains and users on fly
   2. How to setup email aliases
4. How to connect via a mail client (Thunderbird)
5. How to develop locally
6. How to test and troubleshoot the setup

About

A docker image that will provide an out of the box mailserver using

• postfix
• dovecot
• IMAP and POP with mysql driver so you can use mail clients like Thunderbird with ease
• Multiple domains supported, you can have send or receive emails coming for both [email protected] and [email protected]
• roundcube UI to send and check the received emails [WIP]

Requirements

Tools

• Docker installed
• Docker compose installed

Prerequisites

• Your mx record points to the machine where you will use this docker mailserver will run
  • 
• Your mailserver domain A record (or cname) points to the machine where this docker mailserver will run.
  • 
• Your webserver is configured to listen for your mailserver domain port 80, so letsencrypt can generate and renew the ssl certificate
• You need to expose the ports that you will use through your security group or firewall. Port 465 and 143 must be available, the rest are optional only if you use them
  • 25 # smtp
  • 465 # smtps
  • 110 # pop3
  • 143 # imap
  • 993 # imaps
  • 995 # pop3s

System requirements

Recommended:

• 1 Core
• 2GB RAM
• Swap enabled for the container

Minimum:

• 1 vCore
• 512MB RAM
• You'll need to deactivate some services like ClamAV to be able to run on a host with 512MB of RAM. Even with 1G RAM you may run into problems without swap

How to use

First execute the following command to download and install the tool. You can change docker-mailserver in the third line with whatever path you want for the install

curl -LJO https://raw.githubusercontent.com/kristijorgji/docker-mailserver/main/install.sh \
 && chmod a+x install.sh \
 && ./install.sh docker-mailserver

After the installation you will see a message of what configurations you can make before starting the docker container of the mailserver

You can modify those variables to your wishes, those involve things like

• your mailserver domain name
• your mailserver supported domains (can have more than one)
• your mailserver users
• etc

If you want to make more changes to the configurations of postfix/dovecot or any tool, just modify the jinja2 templates at configs folder after the tool installs the mailserver.

Everything else is auto-generated during the start of the container including the self signed ssl certificates with the domain name provided The provisioning is done via ansible and jinja2 templates, that is why the configuration templates end in .j2 extension

How to update domains and users on the fly

First change the configuration at configs/vars/vault.yml which contains your email accounts and domains.

Afterward from the root of this project run

. update.sh

That is all.

Setting up aliases

Example: All emails targeting [email protected] should be received only by [email protected]

NOTE: [email protected] will not receive anything in this setup.

This is very easy to setup.

Change configs/vars/vault.yml mail_virtual_aliases variable and list the alias there like below:

mail_virtual_aliases:
  - { id: 1, domainId: 1, source: "[email protected]", destination: "[email protected]" }

PS: The domainId will be the id of the domain you use, but technically it does not matter much redirect will even work across domains for same mailserver

Finally run the update script

. update.sh

How to develop locally

Run make ress to create a docker image and log into one container created from the created image

Afterward you can execute the boot provisioning by going to cd /dev-docker-data

then bash entrypoint.sh

Or if you want only to execute the ansible provisioning, can do:

cd /dev-docker-data/ansible
ansible-playbook playbook.yml

How to test and troubleshoot the setup