This installation guide covers HyperKitty, the web user interface to access GNU Mailman v3 Archives. To install GNU Mailman follow the instructions in the documentation: http://mailman.readthedocs.io/
Install the code¶
Install the HyperKitty package and its dependencies with the following commands:
sudo python setup.py install
You will also need to install the Sass CSS processor using your package
manager or the project’s installation documentation. You can either use the
default Ruby implementation or the C/C++ version, called libsass (the binary
sassc). The configuration file in
defaults to the
sassc version, but you just have to edit the
COMPRESS_PRECOMPILERS mapping to switch to the Ruby implementation, whoose
binary is called
Those tools are usually packaged by your distribution. On Fedora the Ruby
package is named
rubygem-sass, so you can install it with:
sudo yum install rubygem-sass
On Debian and Ubuntu, the Ruby package is available in the
package, which you can install with:
sudo apt-get install ruby-sass
There is no package of libsass or sassc on either distribution today, but it is being worked on.
It is however recommended to use Virtualenv to install HyperKitty, even for a non-development setup (production). Check out the development documentation for details.
Setup your django project¶
You now have installed the necessary packages but you still need to setup the
Django site (project). Example files are provided in the
Change the database setting in
your preferred database. Edit this file to reflect the correct database
credentials, the configuration variable is
DATABASES (at the top of the
Or better yet, instead of changing the
settings.py file itself, copy the
values you want to change to a file called
settings_local.py and change
them there. It will override the values in
settings.py and will make future
Detailed information on how to use different database engines can be found in the Django documentation.
Setting up the databases¶
The HyperKitty database is configured using the
DATABASE setting in
settings.py file, as usual. The database can be created with the
django-admin migrate --pythonpath example_project --settings settings
HyperKitty also uses a fulltext search engine. Thanks to the Django-Haystack library, the search engine backend is pluggable, refer to the Haystack documentation on how to install and configure the fulltext search engine backend.
HyperKitty’s default configuration uses the Whoosh backend, so if you want
to use that you just need to install the
Whoosh Python library.
Importing the current archives¶
If you are currently running Mailman 2.1, you can run the
management command to import existing archives into the mailman database. This
command will import the Mbox files: if you’re installing HyperKitty on the
machine which hosted the previous version of Mailman, those files are available
locally and you can use them directly.
The command’s syntax is:
django-admin hyperkitty_import --pythonpath example_project --settings settings -l ADDRESS mbox_file [mbox_file ...]
ADDRESSis the fully-qualified list name (including the
@sign and the domain name)
mbox_filearguments are the existing archives to import (in mbox format).
The archive mbox file for a list is usually available at the following location:
If the previous archives aren’t available locally, you need to download them from your current Mailman 2.1 installation. The file is not web-accessible.
Before importing an archive mbox, it is a good idea to check its integrity with the hyperkitty/contrib/check_hk_import script and with Mailman 2.1’s bin/cleanarch script.
After importing your existing archives, you must add them to the fulltext search engine with the following command:
django-admin update_index --pythonpath example_project --settings settings
Refer to the command’s documentation for available switches.
Running HyperKitty on Apache with mod_wsgi¶
This guide assumes that you know how to setup a VirtualHost with Apache.
If you are using SQLite, the
.db file as well as its folder need to be
writable by the web server.
example_project/apache.conf to point to your source code location.
Add following line to your apache/httpd configuration file:
And reload Apache. We’re almost ready. But you need to collect the static files from HyperKitty (which resides somewhere on your pythonpath) to be able to serve them from the site directory. All you have to do is run:
django-admin collectstatic --pythonpath example_project --settings settings django-admin compress --pythonpath example_project --settings settings
django-admin command may be called
on your installation method.
These static files will be collected in the
directory and served by Apache. You should now be all set. Try accessing
HyperKitty in your web browser.
Connecting to Mailman¶
To receive incoming emails from Mailman, you must install the
mailman-hyperkitty module available on PyPI in Mailman’s virtualenv, and
then add the following lines to
[archiver.hyperkitty] class: mailman_hyperkitty.Archiver enable: yes configuration: /path/to/example_project/mailman-hyperkitty.cfg
An example of the mailman-hyperkitty.cfg file is shipped with the mailman-hyperkitty package.
You must set the URL to your HyperKitty installation in that file.
It is also highly recommanded to change the API secret key and in the
MAILMAN_ARCHIVER_KEY variable in
After having made these changes, you must restart Mailman. Check its log files
to make sure the emails are correctly archived. You should not see “
archiver: hyperkitty” messages.
Make sure you installed the
in the same environment in which Mailman’s daemon is executed
otherwise it will raise an exception.
After installing HyperKitty for the first time, you can populate the database with some data that may be useful, for example a set of thread categories to assign to your mailing-list threads. This can be done by running the following command:
django-admin loaddata --pythonpath example_project --settings settings first_start
Thread categories can be edited and added from the Django administration
/admin to your base URL).
You must also make sure that Mailman has generated the databases files that Postfix (or another MTA) will use to lookup the lists. Otherwise SMTP delivery will fail, and that will also impact HyperKitty when it will try to validate email addresses on registration. You can force Mailman to generate those database files with the following command:
You can add HTML snippets to every HyperKitty page by using Django’s TEMPLATE DIRS facility and overriding the following templates:
hyperkitty/headers.html: the content will appear before the
hyperkitty/top.html: the content will appear before the
hyperkitty/bottom.html: the content will appear before the
By default, HyperKitty stores the email attachments in the database. If you
would rather have them stored on the filesystem, you can set the
HYPERKITTY_ATTACHMENT_FOLDER configuration value to a directory.
Make sure that the user running the Django process (for example,
www-data) has the permissions to write in this directory.
If you want to disable support for gravatars in Hyperkitty, you can set
GRAVATAR_SECURE_URL = ''. This will prevent Hyperkitty to go out to
gravatar to load images for email senders.
To upgrade an existing installation of HyperKitty, you need to update the code base and run the commands that will update the database schemas. Before updating any of those databases, it is recommended to shut down the webserver which serves HyperKitty (Apache HTTPd for example).
To update the HyperKitty database, run:
django-admin migrate --pythonpath example_project --settings settings
After this command complete, your database will be updated, you can start your webserver again.
There are a few tasks in HyperKitty that need to be run at regular intervals.
example_project directory contains an example
that you can put in your
To improve performance, HyperKitty uses a distributed task queue that offloads long operations to separate processes called “workers”. Those workers must be started with the following command:
django-admin qcluster --pythonpath example_project --settings settings
An example service file for systemd is provided in the
directory to start the workers at boot time, and manage them like an ordinary
system service. The service file is called
qcluster.service, make sure you
edit the path to the project on the
Some preliminary RPMs for Fedora 21 are available from the repository described in this repo file:
There are also RPMs for RHEL 7 available using this repo file:
The long-term plan is to submit HyperKitty and Mailman3 for inclusion into Fedora. At the moment, the packages are rather stable, but the dependencies can change. These packages have been tested on Fedora 21 and RHEL7 with the targeted SELinux policy set to enforcing.