Configure Web Frontend

Mailman 3 has a web frontend which can be used to administer the Core, manage subscriptions and view the Archives. There are two principal components, Postorius, the Mailman’s web frontend, and Hyperkitty, the Mailman’s official Archiver.

Both Postorius and Hyperkitty are built atop Django, a Python based web framework.

See also

What is Django?

Django is generally configured using a python module called settings.py which is usually present at the root of the Django project. It doesn’t have to be at the root of the project, but anywhere importable by python.

Assuming that you have already cloned or installed the Django project and know their location, we can now start configuring Mailman Components. If you haven’t have a look at Setting up Django Project .

Setting up Admin Account

To create a superuser account in Django, run the following interactive command:

$ cd mailman-suite_project
$ python manage.py createsuperuser

Before you can login with this user, you have to configure Django to send emails, so that it can verify the email provided for the superuser account above.

In Postorius, a superuser is assumed to be the Site Owner and has access to all the domains, mailing lists and their settings. List Owners and Moderators can be added based on per-list basis and don’t need to have a superuser account in Django.

Setting up Email (required)

It is important that Django be able to send emails to verify the addresses that are subscribing to the Mailman. This configuration is separate from what is done is Core. Please have a look at how to setup email backend for django. A simple configuration would look something like this for a mail server listening on localhost:

# To be added to Django's settings.py

EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'
EMAIL_HOST = 'localhost'
EMAIL_PORT = 25
EMAIL_HOST_USER = <username>
EMAIL_HOST_PASSWORD = <password>

Note

Mailman Suite project in Gitlab disables sending of emails when DEBUG=True is set in settings.py, and instead prints the emails to a directory emails under mailman-suite_project. If you don’t see any outgoing emails, please check your settings.py and set DEBUG=False.

If you want to sent out emails along with DEBUG=True, you can remove the conditional setting at the bottom of settings.py in mailman-suite project.

Here are some settings that determine how your emails from them look like:

  • DEFAULT_FROM_EMAIL : This is the default address that used used as the FROM header in all the emails from your django installation.
  • SERVER_EMAIL : This is the address from which the errors emails will be sent to you.

Note

In order to make django send mails, you need to change EMAIL_BACKEND from django.core.mail.backends.console.EmailBackend to django.core.mail.backends.smtp.EmailBackend in the mailman-suite project, if you are using that.

Note that both of these are general Django related settings and will affect other parts of your Django installation too.

Running the task queue (required)

Hyperkitty uses django_q as a task queue. It supports various different backends like Redis, Disque, IronMQ, SQS etc. Please check the documentation to better understand how to configure it. The most basic setup where it uses Django orm as the queue can be configured using the settings below:

Q_CLUSTER = {
   'timeout': 300,
   'save_limit': 100,
   'orm': 'default',
}

You will also have to run python manage.py qcluster command along with Hyperkitty. See Hyperkitty’s docs about asynchronous tasks.

Enable full text search (required)

Hyperkitty uses django-haystack for its full text search. There are several full text engines that can be used. See django-haystack documentation for more details about the different backend engines that it supports. For the most basic setup, you can use whoosh backend. To install the library try:

$ sudo pip2 install whoosh

Then add the following configuration to the Django’s settings.py to enable whoosh engine for full text search.:

HAYSTACK_CONNECTIONS = {
      'default': {
      'ENGINE': 'haystack.backends.whoosh_backend.WhooshEngine',
      'PATH': os.path.join(BASE_DIR, "fulltext_index"),
      # You can also use the Xapian engine, it's faster and more accurate,
      # but requires another library.
      # http://django-haystack.readthedocs.io/en/v2.4.1/installing_search_engines.html#xapian
      # Example configuration for Xapian:
      #'ENGINE': 'xapian_backend.XapianEngine'
      },
}

Scheduled Tasks (required)

There are some routine tasks that need to be run alongside Django, most of which are meant to do some specific routine functions in Hyperkitty. You can add the following to your crontab run them using other cron-like interfaces.:

# This goes in /etc/cron.d/mailman

# Replace "apache" by your webserver user ("www-data" on Debian systems) and
# set the path to the Django project directory

@hourly  apache  django-admin runjobs hourly  --pythonpath /path/to/project --settings settings
@daily   apache  django-admin runjobs daily   --pythonpath /path/to/project --settings settings
@weekly  apache  django-admin runjobs weekly  --pythonpath /path/to/project --settings settings
@monthly apache  django-admin runjobs monthly --pythonpath /path/to/project --settings settings
@yearly  apache  django-admin runjobs yearly  --pythonpath /path/to/project --settings settings
* * * * *  apache  django-admin runjobs minutely  --pythonpath /path/to/project --settings settings
2,17,32,47 * * * * apache  django-admin runjobs quarter_hourly --pythonpath /path/to/project --settings settings

Setting up Database (required)

Django supports a wide variety of databases and you can have a look at the documentation for different options and ways to configure your database to use with Django.

Configure Login to Django

Postorius & Hyperkitty both use django-allauth for authentication because it supports a wire variety of social providers and also allows users to sign up with their email if they desire.

Note that if you have any problems with the account signup/signin related emails, you should look the documentation for django-allauth.

Some of the very basic settings that are required to be set for Postorius & Hyperkitty to work are mentioned below:

  • ACCOUNT_AUTHENTICATION_METHOD = “username_email”
  • ACCOUNT_EMAIL_REQUIRED = True
  • ACCOUNT_EMAIL_VERIFICATION = “mandatory”
  • ACCOUNT_DEFAULT_HTTP_PROTOCOL = “http”
  • ACCOUNT_UNIQUE_EMAIL = True

Configure Postorius & Hyperkitty

Here are the parameters that will affect Postorius and Hyperkitty will function. These parameters are configured in your Django’s settings.py.

  • MAILMAN_REST_API_URL : Complete URL to the Core’s REST API Server. Usually, Mailman Core listens on port 8001 for REST API. e.g. http://localhost:8001/

  • MAILMAN_REST_API_USER : Username for the Core’s REST API, default value in core is ‘restadmin’ if not set.

  • MAILMAN_REST_API_PASS : Password for Mailman REST API User, default value in core is ‘restpass’ if not set.

  • MAILMAN_ARCHIVER_KEY : The Key used to authenticate the emails for archiving in Hyperkitty. Its value should be exactly same as set in Core.

    Also note that the value in settings.py will be within single quotes, but in mailman.cfg it will be without any quotes.

  • FILTER_VHOST : Filter the list of available lists in Hyperkitty depending on the domain it is being currently served from. Mailman 3 supports multiple domains in a single installation.

  • Add compressor.finders.CompressorFinder to your STATICFILES_FINDERS.

  • LOGIN_URL = ‘account_login’

  • LOGIN_REDIRECT_URL = ‘list_index’

  • LOGOUT_URL = ‘account_logout’

  • This setting is for django-compressor which is used here to compile and compress static files:

    COMPRESS_PRECOMPILERS = (
      ('text/x-scss', 'sassc -t compressed {infile} {outfile}'),
      ('text/x-sass', 'sassc -t compressed {infile} {outfile}'),
    )