Hyperkitty
Hyperkitty is a Django based archiver and archive interface for Mailman.
Contents
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.
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
).
/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
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.The valid hosts or domain names for the application need to be defined:
/etc/webapps/hyperkitty/settings_local.py
ALLOWED_HOSTS = [ 'localhost', 'lists.example.com' ]
Hosting
hyperkitty
). It is using /etc/webapps/hyperkitty/
, /var/lib/hyperkitty/
and /run/hyperkitty/
for configurations, static caches and (potentially) sockets, respectively.Nginx and uWSGI
Hyperkitty comes with a working uWSGI configuration file in /etc/uwsgi/hyperkitty.ini
.
Install nginx and uwsgi-plugin-python, create a per-application socket for uWSGI (see UWSGI#Accessibility of uWSGI socket for reference) and activate the uwsgi-secure@hyperkitty.socket
unit.
For a local test setup, serving Hyperkitty at http://localhost:80/hyperkitty add the following Nginx configuration to your setup:
/etc/nginx/hyperkitty.conf
server { listen 80; server_name localhost; charset utf-8; client_max_body_size 75M; root /usr/share/webapps/hyperkitty; access_log /var/log/nginx/access.hyperkitty.log; error_log /var/log/nginx/error.hyperkitty.log; location ~^/(accounts|admin|hyperkitty)/(.*)$ { include /etc/nginx/uwsgi_params; uwsgi_pass unix:/run/hyperkitty/hyperkitty.sock; } }
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 hyperkitty-qcluster.service
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
Tips and tricks
Importing mailman2 archives
Hyperkitty can import archives from mailman < 3.0.
[hyperkitty]$ django-admin hyperkitty_import --pythonpath /usr/share/webapps/hyperkitty --settings settings -l ADDRESS mbox_file [mbox_file ...]
Here ADDRESS
is the fully-qualified list name (e.g. list@example.com
) and the mbox_file
argument represents existing archives (in mbox format) to import (usually found in /var/lib/mailman/archives/private/LIST_NAME.mbox/LIST_NAME.mbox
).
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
Disabling Gravatar support
The builtin Gravatar support can be disabled in the configuration:
/etc/webapps/hyperkitty/settings_local.py
GRAVATAR_SECURE_URL =
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:
/etc/webapps/hyperkitty/settings_local.py
HYPERKITTY_ATTACHMENT_FOLDER = /var/lib/hyperkitty/data/attachments
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:
-
hyperkitty/headers.html
: the content will appear before the</head>
tag -
hyperkitty/top.html
: the content will appear before the<body>
tag -
hyperkitty/bottom.html
: the content will appear before the</body>
tag
Xapian search backend
Hyperkitty can make use of a Xapian based search backend. Install the python-xapian-haystack package and configure the backend:
/etc/webapps/hyperkitty/settings_local.py
HAYSTACK_CONNECTIONS = { 'default': { 'ENGINE': 'xapian_backend.XapianEngine', 'PATH': "/var/lib/hyperkitty/data/xapian_index", }, }
Make sure to create the search index for all lists afterwards. Run the following command as the hyperkitty
user (e.g. using sudo or su):
[hyperkitty]$ django-admin update_index --pythonpath /usr/share/webapps/hyperkitty --settings settings
See also
- Hyperkitty Documentation - The upstream documentation
- Mailman Suite Documentation - The (high level) upstream documentation for the entire Mailman Suite (Mailman, Hyperkitty and Postorius)