Mailman 3 – The Definitive Install Guide (for now)

Sadly no, this is not about a Kevin Costner reboot. If it were, it would be too costly to present to you and you’d poorly receive it. This is about the open source package Mailman3 and its bickering cousins Postorius & Hyperkitty.

I wanted to publicy share an install guide because, let’s face it, the install documentation for the Mailman Suite just sucks. It sucks bad. This is not a snub to the developers, they spend a tremendous amount of time writing needful code and making it available to the world. The state of the documentation, at the time of this writing, is like many things in life: it is what it is.
Postman
When I read the docs, the various how-to articles and everything written on SO, I get the sudden urge to quote President Trump and say “Fake News.” Most docs are outdated, incomplete or missing critical elements.

My frustration/cynicism is not directed towards the authors of such documents because, at one point in time, they were probably right. The fact of the matter is that the software has evolved so much over time, what worked together 6 months ago no longer works today and we need some fresh tutorials.

While I don’t have the time present to present any tutorials, I will provide you with an install doc. These instructions were validated on Oracle 7 Linux (several times). I can not vouch for any other pip packages other than the ones I list below, nor can I vouch for any other environments. That being said, I think most recent distros with python 3.5 will suffice.

With this information, I sincerely hope you save yourself the time, energy and head injuries I sustained while trying to install Mailman Core, Postorius & Hyperkitty (names that sound like the software version of a Nirvana song).

1. Clone the mailman suite from https://gitlab.com/mailman/mailman-suite.git in the /opt directory
2. Clone the mailman-hyperkitty plugin from https://gitlab.com/mailman/mailman-hyperkitty.git in the /opt
3. Create Python 3.5 virtual environment - /opt/venv-3.5
4. Activate the environment: source /opt/venv-3.5/bin/activate
5. CD to /opt/mailman-hyperkitty & 'python3 setup.py install'
6. pip3 install -r requirements.txt to ensure compatible versions (this document validated with these specific versions). File contents are as follows:

aiosmtpd==1.1
alembic==0.9.10
arrow==0.12.1
atpublic==1.0
blessed==1.15.0
certifi==2018.4.16
chardet==3.0.4
click==6.7
decorator==4.3.0
defusedxml==0.5.0
Django==1.11.14
django-allauth==0.36.0
django-appconf==1.0.2
django-compressor==2.2
django-extensions==2.0.7
django-gravatar2==1.4.2
django-haystack==2.8.1
django-mailman3==1.2.0a2
django-paintstore==0.2
django-picklefield==1.0.0
django-q==0.9.4
djangorestframework==3.8.2
dnspython==1.15.0
falcon==1.4.1
flufl.bounce==3.0
flufl.i18n==2.0.1
flufl.lock==3.2
httplib2==0.11.3
HyperKitty==1.2.0
idna==2.7
lazr.config==2.2.1
lazr.delegates==2.0.4
lockfile==0.12.2
mailman==3.2.0
mailman-hyperkitty==1.1.1
mailmanclient==3.2.0
Mako==1.0.7
MarkupSafe==1.0
networkx==2.1
nose==1.3.7
oauthlib==2.1.0
passlib==1.7.1
postorius==1.2.1
python-dateutil==2.7.3
python-editor==1.0.3
python-mimeparse==1.6.0
python3-openid==3.1.0
pytz==2018.5
rcssmin==1.0.6
requests==2.19.1
requests-oauthlib==1.0.0
rjsmin==1.0.12
robot-detection==0.4
six==1.11.0
SQLAlchemy==1.2.9
urllib3==1.23
wcwidth==0.1.7
Whoosh==2.7.4
zope.component==4.4.1
zope.configuration==4.1.0
zope.event==4.3.0
zope.i18nmessageid==4.1.0
zope.interface==4.5.0
zope.schema==4.5.0

7. Edit /opt/venv-3.5/var/etc/mailman.cfg and add the following:
[mailman]
layout: local
[paths.local]
var_dir: /opt/venv-3.5/var
[mta]
incoming: mailman.mta.postfix.LMTP
outgoing: mailman.mta.deliver.deliver
lmtp_host: 127.0.0.1
lmtp_port: 8024
smtp_host: localhost
smtp_port: 25
configuration: python:mailman.config.postfix

[archiver.hyperkitty]
class: mailman_hyperkitty.Archiver
enable: yes
configuration: /opt/mailman-hyperkitty/mailman-hyperkitty.cfg

8. Edit the mailman-hyperkitty.cfg and add the base_url after the api_key entry (make sure the default base_url is removed or updated so there is only one base_url set).
base_url: http://my.domain.org/hyperkitty/
9. Edit the Django settings.py file in /opt/mailman-suite/mailman-suite_project. Below are the values that need to be added/changed.
DEBUG = False
SITE_ID = 2 (or approp site ID. Note: ID 2 won't exist until you login and create the domain in step #19. Apache restart is required after making changes to settings.py)

USE_X_FORWARDED_HOST = True
EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'
ALLOWED_HOSTS = '*'
MAILMAN_ARCHIVER_FROM - add the host ip

10. Configure Postfix:

a. If /etc/postfix/generic.db does not exist then run 'postmap /etc/postfix/generic'.
b. Edit /etc/postfix/main.cf and add the following lines at the bottom of the config:

myhostname = mailserver.domain.org
mydomain = my.domain.org
myorigin = $myhostname
relayhost = smtp.domain.com
smtp_generic_maps = hash:/etc/postfix/generic

# Support the default VERP delimiter.
recipient_delimiter = +

unknown_local_recipient_reject_code = 550
owner_request_special = no
transport_maps =
hash:/opt/venv-3.5/var/data/postfix_lmtp
local_recipient_maps =
hash:/opt/venv-3.5/var/data/postfix_lmtp
relay_domains =
hash:/opt/venv-3.5/var/data/postfix_domains

c. Ensure that Postfix is listening on all interfaces: inet_interfaces = all (the default is localhost)

11. CD to /opt/venv-3.5 and run 'mailman start'. Make sure you start/stop mailman in this location!!
12. Setup the Django backend - cd to /opt/mailman-suite/mailman-suite_project/ and run
a. python3 manage.py migrate
b. python3 manage.py collectstatic
c. python3 manage.py createsuperuser.py (this creates the primary admin account).

13. Start the queing service manager by running: 'nohup python3 manage.py qcluster &'
14. Configure the Apache virtual host as follows:
<VirtualHost *:80>
ServerName my.domain.org
DocumentRoot /opt/mailman-suite/mailman-suite_project
Alias /static /opt/mailman-suite/mailman-suite_project/static
<Directory "/opt/mailman-suite/mailman-suite_project/static">
Require all granted
</Directory>

WSGIScriptAlias / /opt/mailman-suite/mailman-suite_project/wsgi.py
<Directory "/opt/mailman-suite/mailman-suite_project">
Require all granted
</Directory>

WSGIDaemonProcess apache user=apache group=apache home=/opt/mailman-suite/mailman-suite_project python-path=/opt/mailman-suite/mailman-suite_project:/opt/venv-3.5/lib/python3.5/site-packages
WSGIProcessGroup apache
</VirtualHost>

15. Make sure the directory /opt/mailman-suite/mailman-suite_project and the files under are owned by Apache. Start/Restart apache at this point.
16. Configure the mailman cron jobs - vi /etc/cron.d/mailman and paste the following:
@hourly apache source /opt/venv-3.5/bin/activate; django-admin runjobs hourly --pythonpath /opt/mailman-suite/mailman-suite_project --settings settings
@daily apache source /opt/venv-3.5/bin/activate; django-admin runjobs daily --pythonpath /opt/mailman-suite/mailman-suite_project --settings settings
@weekly apache source /opt/venv-3.5/bin/activate; django-admin runjobs weekly --pythonpath /opt/mailman-suite/mailman-suite_project --settings settings
@monthly apache source /opt/venv-3.5/bin/activate; django-admin runjobs monthly --pythonpath /opt/mailman-suite/mailman-suite_project --settings settings
@yearly apache source /opt/venv-3.5/bin/activate; django-admin runjobs yearly --pythonpath /opt/mailman-suite/mailman-suite_project --settings settings

* * * * * apache source /opt/venv-3.5/bin/activate; django-admin runjobs minutely --pythonpath /opt/mailman-suite/mailman-suite_project --settings settings

2,17,32,47 * * * * apache source /opt/venv-3.5/bin/activate; django-admin runjobs quarter_hourly --pythonpath /opt/mailman-suite/mailman-suite_project --settings settings

17. Navigate to http://my.domain.org and login. Click on 'Create New Domain'. Above the blue 'Create domain' button there is a hyperlink add web hosts for Django. Click it.
18. Click Add Site and enter my.domain.org
19. Navigate back to the primary domain and click on 'Create New Domain' once more. This time, fill out form for submission:

Mail Host: my.domain.org
Description: Domain Mailing Lists
Alias Domain: This should be left blank
Web Host: click on the dropdown and select my.domain.org

Follow the steps above and you should be successful. Well..at least more than The Postman was.

Leave a Reply

Your email address will not be published. Required fields are marked *