Hyperkitty

Hyperkitty is a Django based archiver and archive interface for Mailman.

Installation

To use Hyperkitty, a working web server setup is required (e.g. using Apache HTTP Server to forward to the WSGI directly, or using Nginx forwarding requests to an application server such as UWSGI).

Install the hyperkitty package.

Warning: Hyperkitty should only be accessed over TLS (unless only accessed directly from the machine running it for testing purposes), as it otherwise exposes passwords and user data to the network.

Configuration

The web application is configured in /etc/webapps/hyperkitty/settings_local.py (which is included by the default configuration in /usr/share/webapps/hyperkitty/settings.py).

Note: Hyperkitty should store user sensitive data (e.g. sqlite database) in /var/lib/hyperkitty/data/, as that directory is only accessible by root and the application itself.

Change the default secret for the application:

/etc/webapps/hyperkitty/settings_local.py

SECRET_KEY = '''something-very-secret'''

Make sure to disable debugging when running in production:

/etc/webapps/hyperkitty/settings_local.py

DEBUG = False

Add a valid email configuration (so that the Django application can verify subscribers):

/etc/webapps/hyperkitty/settings_local.py

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

Note: The DEFAULT_FROM_MAIL and SERVER_MAIL configuration options can be used to define the From: header of mails sent for internal authentication and error reporting, respectively.

To connect with a running mailman instance's REST API, configuration options have to be added to hyperkitty's configuration.

/etc/webapps/hyperkitty/settings_local.py

MAILMAN_REST_API_URL = 'http://localhost:8001'
MAILMAN_REST_API_USER = 'rest_admin'
MAILMAN_REST_API_PASS = 'rest_admin_password'

To configure the archive integration with a mailman instance first setup the integration with hyperkitty on mailman's side and then configure hyperkitty to accept those connections:

/etc/webapps/hyperkitty/settings_local.py

MAILMAN_ARCHIVER_KEY = 'SecretArchiverAPIKey'
MAILMAN_ARCHIVER_FROM = ('127.0.0.1', '::1')

The valid hosts or domain names for the application need to be defined:

Hosting

Nginx and uWSGI

Hyperkitty comes with a working uWSGI configuration file in .

Install nginx and uwsgi-plugin-python, create a per-application socket for uWSGI (see UWSGI#Accessibility of uWSGI socket for reference) and activate the unit.

For a local test setup, serving Hyperkitty at http://localhost/hyperkitty/ add the following Nginx configuration to your setup:

Setup

After first installation make sure to generate a database:

[hyperkitty]$ django-admin migrate --pythonpath /usr/share/webapps/hyperkitty/ --settings settings

Afterwards, the static data for the application needs to be collected:

[hyperkitty]$ django-admin collectstatic --pythonpath /usr/share/webapps/hyperkitty/ --settings settings

To compress the data, run the following:

[hyperkitty]$ django-admin compress --pythonpath /usr/share/webapps/hyperkitty/ --settings settings

Enable and start the systemd service for required asynchronous operations on the web application.

Populate the database with default data (when setting up for the first time):

[hyperkitty]$ django-admin loaddata --pythonpath /usr/share/webapps/hyperkitty/ --settings settings first_start

Create a superuser account for the Django application:

[hyperkitty]$ django-admin createsuperuser --pythonpath /usr/share/webapps/hyperkitty --settings settings

Log in to the admin interface of the Django application at http://localhost/hyperkitty/admin to be able to add more besides the default or to add additional .

Tips and tricks

Importing mailman2 archives

Hyperkitty can import archives from mailman < 3.0.

Note: Run the following commands as the hyperkitty user (e.g. using sudo or su).

[hyperkitty]$ django-admin hyperkitty_import --pythonpath /usr/share/webapps/hyperkitty --settings settings -l ADDRESS mbox_file [mbox_file ...]

Here is the fully-qualified list name (e.g. [email protected]) and the argument represents existing archives (in mbox format) to import (usually found in ).

Afterwards the full-text search index can be updated manually:

[hyperkitty]$ django-admin update_index_one_list --pythonpath /usr/share/webapps/hyperkitty --settings settings ADDRESS

Content-Security-Policy Header

It is possible to define a Content-Security-Policy HTTP response header for HyperKitty. This allows content and resources only from specified locations.

When using nginx add the following to the directive in which HyperKitty is setup in:

Disabling Gravatar support

The builtin Gravatar support can be disabled in the configuration:

This option was introduced in Hyperkitty 1.3.4. In earlier versions, use this instead:

Saving mail attachments to disk

By default Hyperkitty stores mail attachments in its database. However, it can be configured to save the attachments to disk instead:

Note: The location needs to be accessible and writable by the hyperkitty user.

Template customization

Using Django's TEMPLATES-DIRS capabilities, it is possible to override the following templates to change the looks of the application:

: the content will appear before the tag
: the content will appear before the tag
: the content will appear before the </body> tag

Xapian search backend

Hyperkitty can make use of a Xapian based search backend. Install the package and configure the backend:

Make sure to create the search index for all lists afterwards. Run the following command as the user (e.g. using sudo or su):

[hyperkitty]$ django-admin update_index --pythonpath /usr/share/webapps/hyperkitty --settings settings

Troubleshooting

SMTP AUTH extension not supported by server

If upon first login with the admin user a is thrown (logged to /var/log/hyperkitty/hyperkitty.log), make sure to verify the settings in /etc/webapps/hyperkitty/settings_local.py.

By default e.g. is set to which might trigger a failed login via SMTP.