# Installation

Note

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 is `sassc`). The configuration file in `example_project/settings.py` 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 package 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/settings.py` 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 `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 upgrades easier.

Note

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 `settings.py` 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 ...]

where:

- `ADDRESS` is the fully-qualified list name (including the `@` sign and the domain name)
- The `mbox_file` arguments are the existing archives to import (in mbox format).

The archive mbox file for a list is usually available at the following location:

    /var/lib/mailman/archives/private/LIST_NAME.mbox/LIST_NAME.mbox

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.

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

Note

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

Note

Your `django-admin` command may be called `django-admin.py` 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`:

    [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 `settings.py` (or `settings_local.py`).

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 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:

    mailman aliases

## Customization

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

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, `apache` or `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.

## Upgrading

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.

## Asynchronous tasks

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.

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 `example_project` 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 `ExecStart` line.

## RPMs

Some preliminary RPMs for Fedora 21 are available from the repository described in this repo file:

    http://repos.fedorapeople.org/repos/abompard/hyperkitty/hyperkitty.repo

There are also RPMs for RHEL 7 available using this repo file:

    https://repos.fedorapeople.org/repos/abompard/hyperkitty/hyperkitty-el.repo

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.

## License

HyperKitty is licensed under the GPL v3.0