Having an SMTP server installed locally can help in a lot of different projects.
Many different server types need an SMTP server configuration to relay generated emails to users. Without such a configuration, it's impossible for many of these servers to communicate with its own users.

Email is arguably the most basic form of automated electronic configuration in the modern digital world. From account activation links to password reset tokens, a lot of basic user functionality can be achieved only if the server is equipped with a proper SMTP relay in its configuration.

But why do we even need an SMTP server in the first place? Well, we don't really need one but, at the end of the day, it's very handy to have one, nonetheless.

How does email work?

Email works on different levels but the general gist of it is that it all boils down to SMTP servers acting as the backbone of all email providers.
SMTP is a protocol that allows email servers to send an email from one another, either encrypted with TLS on port 25 using the STARTTLS command, or even in plaintext.
Email clients, i.e. most of the software used to access the emails from one's inbox, use retrieval protocols such as POP3 or IMAP to access the SMTP server and download the relevant emails off the server onto the local machine to display them.

This system, while archaic in many ways, is the foundation of modern day communication. All email systems boil down to these simple concepts. Any innovative feature that they may offer on top, uses these basic principles to function behind the scenes.

So why do we need an SMTP server?

Well, the SMTP server will act as an outbound gateway for all generated emails of our various services. All email needs an originating SMTP server to be sent. If we wouldn't install one, we would need to use a third-party one instead, such as a gmail server, or a hotmail server.

This would require hardcoding our user credentials for our gmail account or hotmail account into our configurations of our various services (either that or creating a technical gmail account for this specific purpose) but this is laborious and there's always the chance that these configurations will be exposed, in case of a hack, to outside entities.

Instead, relying on our own SMTP server, we don't need to hardcode our login gmail credentials to have an email sending service available. We can just install our own one!

Excited yet? Well, you should be! In this guide, I'll configure a special type of service called Postfix. Let's start!

Postfix configuration

I'll skip the installation part, as that's distro dependent. Moreover, it's been so long since I installed Postfix on my machine that I cannot remember the exact details so that I can write them down in the first place.

As such, please follow whatever online guide you can find for your particular Linux distro on how to install and initially configure Postfix. These should be very common.

For once, I will not encourage the installation of Postfix docker image because I wish for this email functionality to be available to me even if the docker systemd service is stopped, so that I can manually send emails to specific addresses even without any docker containers running or even needing for docker to be installed on the system, at all.

Once Postfix is installed properly, test it by also installing the sendmail utility and then issuing a test email to your own personal inbox to see if it works using the following command:

The address after "sendmail" can obviously be changed to any valid email address that references your inbox so that you can quickly check if it works or not.

With that said, let's now tinker with the configuration!

The main configuration file is "/etc/postfix/main.cf". On my distro, Postfix works as a systemd service that's meant to constantly run. Be sure to run the following command after installation, to make sure the service will always start up on reboot or shut down:

Once this is done, open the aforementioned configuration file with write privileges and let's start editing lines!

First, TLS configuration:

These parameters are by no means mandatory and I would generally omit them. Postfix will use these certificates in TLS communication with clients. The above configuration will allow for STARTTLS to occur from port 25 (which is normally in text mode and unencrypted only), so that the connection will be more secure.

While I generally consider encryption to be a very nice to have feature, assuming all your services are running in docker containers on the same machine as the Postfix server, this encryption channel is unnecessary as, ultimately, all communication between email clients and the Postfix server will be, effectively, to localhost, i.e. no data will be sent over the wire. As such, there's no way for unencrypted data to be intercepted.

This configuration is presented mostly for the sake of completeness.

Now, the more relevant parameters are the following:

There's a lot to unpack there!
The easiest parameter to explain is the "myhostname" one. This tells Postfix the domain it's running under. This may or may never be relevant and I believe that this option can even be omitted (maybe).

Next is the "smtpd_relay_restrictions" which has a bunch of values assigned to it. The only one relevant to talk about is "permit_mynetworks", which informs Postfix that it's fine to relay any outgoing email from the IP addresses and hosts defined in the "mynetworks" variable, without having to authenticate them with user passwords.
Basically, this means that, as long as a service connects to port 25 of the current machine from an originating IP that's listed under "mynetworks" this means that Postfix will accept whatever email that service is trying to send and relay it over to its destination.

"mydestination = localhost" not sure about this one?

"mynetworks" tells Postfix which machines are trusted. SMTP needs to trust sources of email before it can relay them. If you specify "permit_mynetworks" to "smtpd_relay_restrictions" then any machine whose IP is listed in this parameter can relay its email through this Postfix instance.

Basically, what this means is that, all your docker services need to have their IPs listed in this parameter for Postfix to relay their emails further. This is mandatory. If you omit any docker service's IP from this list, that service will not be able to use Postfix as its SMTP server to relay email even if the Postfix server is technically reachable by it via ICMP echo packets.

To find the IP address for a specific docker container, please run "docker inspect <container_id>" and then look up the "IPAddress" field from the resulting output, under the "Networks" JSON property. Note: it's not the "Gateway" field, that's something else!

Please be aware, though, that docker allocates IPs dynamically. So even if a container has a specific IP at one point, it doesn't mean that it will have the same IP next time a new container is spawned from the same image (i.e. after a system reboot). As such, this can, in theory, mean that your configuration will work at one point but, after a system reboot, it won't work anymore. This would mean that you either have to specify manual static IP addresses for your docker images so that they will always take the exact same IP all the time (not recommended and it goes against the entire philosophy of docker) or, you can just do what I did and simply whitelist all the possible private IPs under "172.16.0.0/12". This basically resolves to all the 16 continous class B private IP addresses in the IPv4 address space, as seen here. Docker will, by default, use IPs in a subrange in this address space, when allocating IPs to newly spawned containers.

This approach has the advantage that whichever IP docker will assign to a newly created container, that IP will always fall somewhere in this range, so it will already be whitelisted. Moreover, since this is a private address range, not a public one, nobody outside the current LAN of the server can impersonate it, nor can they breach the local network from the outside if proper firewall and NAT rules are set in place by the network administrator, which means there's never a risk that someone might try misusing our Postfix server from outside our network.

Finally, there's the "inet_interfaces" configuration parameter. This one specifies under which identities the current installation of Postfix will be assumed by the server. Postfix will accept all requests destined to any of these addresses as its own and will handle them.

In a docker configuration, assuming the services are using a "bridge" network driver, they will all have their own IP addresses in the aforementioned address space, and these addresses will be distinct from the proper address of the machine where Postfix is installed. As such, they need a target to resolve to reach the machine running Postfix. This target will be IP 172.17.0.1. When configuring each individual docker service, enter that IP as the IP of the SMTP server to use, as well as port 25, as its connection port. These should be the only parameters you should need to configure everything to work properly. 172.17.0.1 was a random address that I decided on. Really, it has no real relevance and can be changed to any private IPv4 address, whether in class B, C or A. The only point is that it should be reachable through this network driver.

Troubleshooting issues with Postfix reachability from docker containers

If whichever docker container you're currently running doesn't seem to connect to 172.17.0.1 and its image contains the ping utility pre-installed in it, you can attach your current terminal session into that container and access it via "docker exec -it <docker_container_id> /bin/bash" and then simply issuing a "ping 172.17.0.1" to send ICMP echo packets to your SMTP server from inside the container itself. If there are replies, this means the container can reach your local Postfix server so the problem is most likely from Postfix dropping the requests intentionally. Alternatively, this could be a firewall misconfiguration problem but this has never happened to me before, although I recognize that it may be theoretically possible.

To further validate this, issue the following command to see the last log error reports from Postfix, including the notifications of rejected requests:

Note, you need sudo privileges to read the mail.log file, as it is owned by the syslog user and it has restricted reading privileges.

Wrapping it up

That's it! As soon as you finish editing the main configuration file, please remember to restart the Postfix service afterwards so that the changes can take effect immediately (or reboot the machine).

Happy coding!