Akeneo: The Missing MTA Documentation

by Don Bales, Developer Mentor

Monday, August 24, 2020

Sincerely, Akeneo has some of the best documentation available for installing their software. Here's the main link: https://docs.akeneo.com/4.0/install_pim/index.html. Follow the instructions for Installing Akeneo Manually.

And, it is well worth your time to read the requirements documentation. That will give you an overall understanding of what you'll being doing. Here are some issues:

Missing Documentation

Installing and Configuring a Mail Transfer Agent (MTA)

The Akeneo installation documentation ignores the application's requirement for access to a Simple Mail Transfer Protocol (SMTP) server, in order to be able to send notification's via email. Accordingly, I've added a section below for Installing and Configuring Postfix (an MTA) on Ubuntu.

After the MTA is operational on the application's host, you need to modify the .env file, setting:

MAILER_URL=localhost:25

Installing and Configuring Postfix (an MTA) on Ubuntu

Before you start, you need to have an SMTP server you can securely connect to with a username and password. You need to specify the relayhost (server's DNS name and port), and in the username and password. SO make sure you have them on hand before you start.

Ubuntu 20

Install package mailutils, which contains postfix. During the installation it will prompt for the mail transfer agent (MTA) type, which you should reply: Internet Site.

$ sudo apt install mailutils

Next, edit postfix's main.cf file, in order to make SSL encryption mandatory, and to specify the authentication credentials.

$ sudo vim /etc/postfix/main.cf

Look for a key named: smtp_tls_security_level. If you find it, change the value to encrypt. If you can't find it, add it.

Look for a key named: relayhost. Specify the SMTP [host]:port here. For example, if you are using gmail:

relayhost = [smtp.gmail.com]:587

Add these key=value pairs to the end of the file, in order to specify the location of the authentication credentials:

smtp_sasl_auth_enable = yes
smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
smtp_sasl_security_options = noanonymous

Here's a sample configuration file where I specify gmail as my smtp server (/etc/postfix/main.cf):

# See /usr/share/postfix/main.cf.dist for a commented, more complete version

# Debian specific: Specifying a file name will cause the first
# line of that file to be used as the name. The Debian default
# is /etc/mailname.
#myorigin = /etc/mailname

smtpd_banner = $myhostname ESMTP $mail_name (Ubuntu)
biff = no

# appending .domain is the MUA's job.
append_dot_mydomain = no

# Uncomment the next line to generate "delayed mail" warnings
#delay_warning_time = 4h

readme_directory = no

# See http://www.postfix.org/COMPATIBILITY_README.html -- default to 2 on
# fresh installs.
compatibility_level = 2

# TLS parameters
smtpd_tls_cert_file=/etc/ssl/certs/ssl-cert-snakeoil.pem
smtpd_tls_key_file=/etc/ssl/private/ssl-cert-snakeoil.key
smtpd_tls_security_level=may

smtp_tls_CApath=/etc/ssl/certs
#smtp_tls_security_level=may
smtp_tls_security_level = encrypt
smtp_tls_session_cache_database = btree:${data_directory}/smtp_scache

smtpd_relay_restrictions = permit_mynetworks permit_sasl_authenticated defer_unauth_destination
myhostname = rpi4-8g-desktop
alias_maps = hash:/etc/aliases
alias_database = hash:/etc/aliases
myorigin = /etc/mailname
mydestination = $myhostname, rpi4-8g-desktop.local, rpi4-8g-desktop, localhost.localdomain, localhost
relayhost = [smtp.gmail.com]:587
mynetworks = 127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128
mailbox_size_limit = 0
recipient_delimiter = +
inet_interfaces = all
inet_protocols = all

smtp_sasl_auth_enable = yes
smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
smtp_sasl_security_options = noanonymous

Now create a new authentication credentials file named /etc/postfix/sasl_passwd:

$ sudo vim /etc/postfix/sasl_passwd

Specify the destination and authentication credentials as follows:

# destination credentials
[smtp.gmail.com]:587 TheUsername@gmail.com:ThePassword

NOTE: The destination value must match the relayhost value exactly. In this example, I specified: [smtp.gmail.com]:587 for the relayhost in file main.cf, so I specified the exact same value for the destination in file sasl_passwd.

Now that the sasl_passwd file exists, we must secure it so only root can see the password:

$ sudo chmod 600 /etc/postfix/sasl_passwd

Next, we need to hash encode the credentials file:

$ sudo postmap /etc/postfix/sasl_passwd

You can verify the files exist, are in the correct location: /etc/postfix, are owned by root, and are secured:

$ sudo ls -lap /etc/postfix/sasl_passwd*

And, you can verify there are now syntax errors in the configuration files by executing:

$ sudo postfix check

NOTE: You may safely ignore any warning level messages displayed by postfix check.

Now reload the postfix configuration:

$ sudo systemctl reload postfix

Let's test the configuration sending an actual email message. Change the recipient@domain.name to your email address.

$ echo "Test Postfix Gmail SMTP Relay" | mail -s "Postfix Gmail SMTP Relay"
recipient@domain.name

Last, tail the postfix log file in order to see the progress of processing you test email message:

$ sudo tail /var/log/mail.log

Once you have Postfix installed, configured, and working on the Akeneo host, you can specify: localhost:25 in Akeneo's .env file for key: MAILER_URL. After specifying the smtp host in the .env file, you can test the configuration by sending an email through Akeneo using bin/console as follows: Change the sender@domain.name and recipient@domain.name to your email address.

bin/console swiftmailer:email:send \
--from sender@domain.name \
--to recipient@domain.name \
--subject "Testing Swiftmail on Akeneo `hostname`" \
--body "Did you get this message?"

Now Akeneo should be able to send notifications using postfix on its host.