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.

Setting up Admin Account¶

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

(venv)$ mailman-web 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.

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

@hourly  mailman  /opt/mailman/venv/bin/mailman-web runjobs hourly
@daily   mailman  /opt/mailman/venv/bin/mailman-web runjobs daily
@weekly  mailman  /opt/mailman/venv/bin/mailman-web runjobs weekly
@monthly mailman  /opt/mailman/venv/bin/mailman-web runjobs monthly
@yearly  mailman  /opt/mailman/venv/bin/mailman-web runjobs yearly
* * * * *  mailman  /opt/mailman/venv/bin/mailman-web runjobs minutely
2,17,32,47 * * * * mailman  /opt/mailman/venv/bin/mailman-web runjobs quarter_hourly

To Check what jobs do exist and will run on scheduled time, you can run:

(venv) $ mailman-web runjobs -l
Job List: 11 jobs
 appname           - jobname                - when     - help
--------------------------------------------------------------------------------
 django_extensions - cache_cleanup          - daily    - Cache (db) cleanup Job
 django_extensions - daily_cleanup          - daily    - Django Daily Cleanup Job
 hyperkitty        - empty_threads          - monthly  - Remove empty threads
 hyperkitty        - new_lists_from_mailman - hourly   - Import new lists from Mailman
 hyperkitty        - orphan_emails          - daily    - Reattach orphan emails
 hyperkitty        - recent_threads_cache   - daily    - Refresh the recent threads cache
 hyperkitty        - sync_mailman           - daily    - Sync user and list properties with Mailman
 hyperkitty        - thread_order_depth     - yearly   - Compute thread order and depth for all threads
 hyperkitty        - thread_starting_email  - hourly   - Find the starting email when it is missing
 hyperkitty        - update_and_clean_index - monthly  - Update the full-text index and clean old entries
 hyperkitty        - update_index           - hourly   - Update the full-text index

Setting up Email¶

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.

Running the task queue¶

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 = {
   'retry': 360,
   '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:

(venv)$ pip 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'
      },
}

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