Install DMA & add documentation (related to thecodingmachine#204)

Author: moqmar

utils/Dockerfile.blueprint

@@ -2,6 +2,7 @@
 
 ARG INSTALL_CRON=1
 ARG INSTALL_COMPOSER=1
+ARG INSTALL_DMA=1
 ARG PHP_VERSION
 ARG GLOBAL_VERSION
 FROM thecodingmachine/php:${PHP_VERSION}-${GLOBAL_VERSION}-slim-{{ $variant }}

utils/Dockerfile.slim.blueprint

@@ -418,3 +418,18 @@ ONBUILD RUN if [ -n "$NODE_VERSION" ]; then \
     sudo apt-get update && \
     sudo apt-get install -y --no-install-recommends yarn; \
     fi;
+
+# |--------------------------------------------------------------------------
+# | DragonFly Mail Agent
+# |--------------------------------------------------------------------------
+# |
+# | Installs DragonFly Mail Agent, a sendmail-compatible MTA that can be used
+# | to send email from PHP, either using direct delivery or through an SMTP
+# | smarthost.
+# |
+
+ONBUILD ARG INSTALL_DMA
+ONBUILD RUN if [ -n "$INSTALL_DMA" ]; then \
+    sudo apt-get update && \
+    sudo apt-get install -y --no-install-recommends dma
+

utils/README.blueprint.md

@@ -359,6 +359,34 @@ ENV APACHE_RUN_USER=www-data \
 ```
 
 
+## Sending email
+
+The `sendmail` binary is available through [DragonFly Mail Agent (DMA)](https://wiki.mageia.org/en/Dma_Dragonfly_Mail_Agent) to make the [`mail()`](https://www.php.net/manual/de/function.mail.php) function work. Without configuration, it sends email directly, using `[email protected]` as the sender by default - this won't work for various reasons (greylisting, spam blacklists, SPF record of example.org, ...), and email is quite complex to set up correctly with direct delivery.
+
+**Important**: To reliably send email, you thus should specify a smarthost which will be used as an SMTP relay - all you need is an account at any email provider that supports SMTP (ideally suited for mass/transactional mails, according to your usecase - e.g. Mailgun, Postmark, or a self-hosted [Postal](https://github.com/postalhq/postal) instance). Then, to configure DMA, you'll just have to set the following environment variables:
+
+```bash
+# your sender address
+[email protected]
+# your smarthost settings
+DMA_CONF_SMARTHOST=smtp.example.org
+DMA_AUTH_USERNAME=noreply
+DMA_AUTH_PASSWORD=helloworld123
+# further DMA settings, according to the DMA man page, prefixed with DMA_CONF_
+# (see https://manpages.debian.org/unstable/dma/sendmail.8.en.html#dma.conf)
+DMA_CONF_STARTTLS=1
+```
+
+DMA is **installed by default in the fat images**. If you are using the "*slim*" images, you need to install it by passing
+a single argument before the "FROM" clause in your Dockerfile:
+
+```Dockerfile
+ARG INSTALL_DMA=1
+FROM thecodingmachine/php:{{ $image.php_version }}-v3-slim-apache
+# The build triggers automatically the installation of DragonFly Mail Agent
+```
+
+
 ## Setting up CRON jobs
 
 You can set up CRON jobs using environment variables too.