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
dart-sass version (dartsass) 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
dart-sass implementation, whose binary is called sass
and which doesn’t
recognize the short form of the -t/--style
option.
We no longer recommend ruby-sass as there have been compatibility issues with recent versions.
Recent Debian and Ubuntu have a sassc
package, which you can install with:
sudo apt-get install sassc
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.
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
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.
Note
Make sure you installed the mailman_hyperkitty
module
in the same environment in which Mailman’s daemon is executed
otherwise it will raise an exception.
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>
taghyperkitty/top.html
: the content will appear before the<body>
taghyperkitty/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
HYPERKITTY_ENABLE_GRAVATAR = False
. This prevents loading and displaying
gravatar images.
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