Development

Communication channels

Hang out on IRC and ask questions on #mailman or join the mailing list hyperkitty-devel@lists.fedorahosted.org.

Setting up Hyperkitty for development

The recommanded 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://github.com/hyperkitty/kittystore.git
cd kittystore
python setup.py develop
cd ..
git clone https://github.com/hyperkitty/hyperkitty.git
cd hyperkitty
python setup.py develop
cd ..
git clone https://github.com/hyperkitty/hyperkitty_standalone.git

Configuration

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

DEBUG = True
TEMPLATE_DEBUG = DEBUG
ASSETS_DEBUG = DEBUG
ASSETS_AUTO_BUILD = DEBUG
USE_SSL = False

It’s also recommanded to change the database access paths in the DATABASES, KITTYSTORE_URL and KITTYSTORE_SEARCH_INDEX variables.

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 at first and each time you change the static files:

django-admin collectstatic --pythonpath hyperkitty_standalone --settings settings
django-admin assets --pythonpath hyperkitty_standalone --settings settings build --parse-templates

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

There are two databases in HyperKitty: one for the Django app, configured in the regular DATABASES variable, and one for the KittyStore backend, configured in the KITTYSTORE_URL variable.

Now you can create the KittyStore and HyperKitty databases, and set their access URLs in hyperkitty_standalone/settings.py (or hyperkitty_standalone/settings_local.py). HyperKitty’s database can be created using the following command:

django-admin syncdb  --pythonpath hyperkitty_standalone --settings settings
django-admin migrate --pythonpath hyperkitty_standalone --settings settings

KittyStore’s database is configured using an URI. The syntax is as follows:

KITTYSTORE_URL = "scheme://username:password@hostname:port/database_name"

The scheme may be “sqlite”, “postgres”, or “mysql”. For example, with sqlite:

KITTYSTORE_URL = "sqlite:////path/to/hyperkitty/directory/kittystore.db'

Note

If you’re using SQLite and you’re getting “Database is locked” errors, stop your webserver during the import.

KittyStore also uses a fulltext search engine which resides in a directory on the filesystem. The path to this directory must be configured in the KITTYSTORE_SEARCH_INDEX variable. This directory should be writable by the user running Mailman and readable by the user running HyperKitty (usually your webserver). It will be automatically created when the regular KittyStore database is created. The command to create the KittyStore database is:

kittystore-updatedb -p hyperkitty_standalone -s settings

Importing the current archives

If you are currently running Mailman 2.1, you can run kittystore-import 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:

kittystore-import --settings MODULE --pythonpath PATH -l NAME mbox_file [mbox_file ...]

where:

  • MODULE is the python module with HyperKitty’s Django settings,
  • PATH is an additionnal path to add to Python if the settings module can’t be imported directly (this should be familiar if you know how to use Django’s django-admin command)
  • NAME is the fully-qualified list name (including the @ sign and the domain name)
  • The mbox_file arguments are the existing archives to import. Make sure you point

at the *.txt version of the files and not the *.gz.

If the previous archives aren’t available locally, you need to download them from your current Mailman 2.1 installation. The kittystore-download21 command can help you do that, its syntax is:

kittystore-download21 -u URL -l LIST_NAME [-d destdir]

where:

  • URL is the base URL of your current Mailman 2.1 installation, typically the part before the /pipermail subdirectory when you’re looking at your current archives. Make sure you remember to include the ‘http://‘ in this string.
  • LIST_NAME is the name of the mailing-list without the domain (before the @ sign)

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 hyperkitty_standalone --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 --pythonpath hyperkitty_standalone --settings settings 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: