The full documentation is located in the “doc” subfolder. It can be generated in various formats once you have installed Sphinx. To generate the HTML documentation, run the following command:
make -C doc html
The HTML files will be available in the
The documentation can also be browsed online at: https://hyperkitty.readthedocs.org.
Hang out on IRC and ask questions on
#mailman or join the mailing list
Setting up HyperKitty for development¶
The recommended way to develop on HyperKitty is to use VirtualEnv. It will create an isolated Python environment where you can add HyperKitty and its dependencies without messing up your system Python install.
First, create the virtualenv and activate it:
virtualenv venv_hk source venv_hk/bin/activate
Then download the components of HyperKitty:
git clone https://gitlab.com/mailman/hyperkitty.git cd hyperkitty python setup.py develop
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 pacakge 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.
For a development setup, you should create a
example_project/settings_local.py file with at least the following
DEBUG = True TEMPLATE_DEBUG = DEBUG USE_SSL = False
It’s also recommended to change the database access paths in the
HAYSTACK_CONNECTIONS variables. Absolute paths are required.
If you ever want to turn the
DEBUG variable to
False (by removing it
settings_local.py), you’ll have to run two additional commands then
and each time you change the static files:
django-admin collectstatic --pythonpath example_project --settings settings django-admin compress --pythonpath example_project --settings settings
Normally, to generate compressor content, you’ll need to set
settings_local.py. However, you can force the generation of
compressor content by adding the
--force switch to the
django-admin compress command, which
will run the compressor even if the
COMPRESS settings are not
But for development purposes, it’s better to keep
DEBUG = True.
django-admin command may be called
on your installation method.
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. Make sure you point at the
*.txtversion of the files and not the
If the previous archives aren’t available locally, you need to download them
from your current Mailman 2.1 installation. The
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]
URLis the base URL of your current Mailman 2.1 installation, typically the part before the
/pipermailsubdirectory when you’re looking at your current archives. Make sure you remember to include the ‘http://‘ in this string.
LIST_NAMEis the name of the mailing-list without the domain (before the
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.
If you’re coding on HyperKitty, you can use Django’s integrated web server. It can be run with the following command:
django-admin runserver --pythonpath example_project --settings settings
You should use the development server only locally. While it’s possible to make your site publicly available using the dev server, you should never do that in a production environment.
Use the following command:
django-admin test --settings hyperkitty.tests.settings_test hyperkitty
All test modules reside in the
and this is where you should put your own tests, too. To make the django test
runner find your tests, make sure to add them to the folder’s