Development

Building documentation

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 doc/_build/html directory.

The documentation can also be browsed online at: https://hyperkitty.readthedocs.org.

Communication channels

Hang out on IRC and ask questions on #mailman or join the mailing list mailman-users@mailman3.org.

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
pip install -e '.[dev]'

You will also need to install the Dart Sass CSS processor. Use your distribution’s Dart Sass package if one is available, or follow Dart Sass’ installation documentation. HyperKitty uses the Dart Sass command-line executable, whose binary is called sass.

Common installation options include:

  • macOS with Homebrew:

    brew install dart-sass

  • Linux distributions with a Dart Sass package can use their system package manager. For example, Arch Linux provides dart-sass:

    sudo pacman -S dart-sass

    Debian and Ubuntu do not currently provide a dart-sass command-line package. Their sassc package is LibSass-based and should not be used for this setup.

  • Any supported platform: download the standalone Dart Sass archive for your operating system and add the extracted dart-sass directory to your PATH.

  • Any platform with Node.js/npm:

    npm install -g sass

The configuration file in example_project/settings.py defaults to Dart Sass with --style=compressed and --no-source-map. You can check your local installation with:

sass --version

We no longer recommend sassc/LibSass because LibSass has reached end of life and no longer receives updates. We also no longer recommend ruby-sass as there have been compatibility issues with recent versions.

Configuration

For a development setup, you should create a file example_project/settings_local.py with at least the following content:

DEBUG = True
TEMPLATE_DEBUG = DEBUG
USE_SSL = False

It’s also recommended to change the database access paths in the DATABASES and HAYSTACK_CONNECTIONS variables. Absolute paths are required.

If you ever want to turn the DEBUG variable to False (by removing it from 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 COMPRESS_ENABLED to TRUE and COMPRESS_OFFLINE to TRUE in 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 TRUE.

But for development purposes, it’s better to keep DEBUG = True.

Note

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

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/cleanarch3 script and with the hyperkitty/contrib/check_hk_import 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

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

Warning

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.

Testing

Use the following command:

django-admin test --settings hyperkitty.tests.settings_test hyperkitty

All test modules reside in the hyperkitty/tests directory 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 __init__.py: