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