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:

Install the code

Install the HyperKitty package and its dependencies with the following commands:

sudo python 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 is sassc). The configuration file in example_project/ 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 sass.

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 pacakge is available in the ruby-sass 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 example_project subdirectory.

Change the database setting in example_project/ to your preferred database. Edit this file to reflect the correct database credentials, the configuration variable is DATABASES (at the top of the file).

Or better yet, instead of changing the file itself, copy the values you want to change to a file called and change them there. It will override the values in and will make future upgrades easier.


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 Django’s file, as usual. The database can be created with the following command:

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 hyperkitty_import 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 ...]


  • ADDRESS is the fully-qualified list name (including the @ sign and the domain name)
  • The mbox_file arguments are the existing archives to import. Make sure you point at the *.txt version of the files and not the *.gz.

If the previous archives aren’t available locally, you need to download them from your current Mailman 2.1 installation. The mailman2_download management command can help you do that, its syntax is:

django-admin mailman2_download --pythonpath example_project --settings settings -u URL -l LIST_NAME [-d destdir]


  • URL is the base URL of your current Mailman 2.1 installation, typically the part before the /pipermail subdirectory when you’re looking at your current archives. Make sure you remember to include the ‘http://‘ in this string.
  • LIST_NAME is the name of the mailing-list without the domain (before the @ sign)

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.

Edit example_project/apache.conf to point to your source code location.

Add following line to your apache/httpd configuration file:

Include "/{path-to-example_project}/apache.conf"

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


Your django-admin command may be called depending on your installation method.

These static files will be collected in the example_project/static 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 mailman.cfg:

class: mailman_hyperkitty.Archiver
enable: yes
configuration: /path/to/example_project/hyperkitty.cfg

An example of the 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 (or

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 “Broken archiver: hyperkitty” messages.

Initial setup

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 interface (append /admin to your base URL).


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 </head> tag
  • hyperkitty/top.html: the content will appear before the <body> tag
  • hyperkitty/bottom.html: the content will appear before the </body> tag


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. The example_project directory contains an example crontab file that you can put in your /etc/cron.d directory.


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.


HyperKitty is licensed under the GPL v3.0