A short link to this page is https://wiki.list.org/x/17891742

Clear message

Setting Up Hyperkitty for Development

This is cobbled together from http://wiki.list.org/display/DEV/A+5+minute+guide+to+get+the+Mailman+web+UI+running and https://hyperkitty.readthedocs.org/en/latest/development.html and testing things out!!

These instructions are most likely out of date. Please refer to the general setup guide here and Hyperkitty's docs here.

Get mailman 3 and postorius working

Here's the basic setup steps to get mailman and postorius working:

  1. Make a directory to store everything. I set up /home/duffy/Repositories.
  2. Make sure you have some necessary packages. I use Fedora 21 so I'll refer to Fedora stuff. You may need to adjust package names for your distro, and this list may not be exhaustive:
    •  sudo yum install python-setuptools python-devel python-virtualenv python3-devel git gcc nodejs-less postfix

      On Debian and Ubuntu, this may be something like:  sudo apt-get install python-setuptools python-dev python-virtualenv python3-dev git gcc node-less nodejs postfix

Note: If you get errors like  lessc: command not found  or  FilterError  while compiling bootstrap-custom.css it means either you don't have less-css compiler installed or its version is <1.5 (which is the minimum required for hyperkitty). Run the command below:

 sudo npm install -g less .

  1. Get all of the source code you need.
    • $ cd ~/Repositories
      $ git clone git@gitlab.com:mailman/mailman.git
      $ git clone git@gitlab.com:mailman/mailmanclient.git
      $ git clone git@gitlab.com:mailman/django-mailman3.git
      $ git clone git@gitlab.com:mailman/postorius.git
      $ git clone git@gitlab.com:mailman/hyperkitty.git
      $ git clone git@gitlab.com:mailman/mailman-hyperkitty.git

In order for git clone git@gitlab.com:mailman/... to work, you must have a gitlab.com account with your SSH public key uploaded. Otherwise, use git clone https://gitlab.com/mailman/...

  1. Make your virtual environments. Mailman needs Python 3.4+ but Postorius and HyperKitty still run on 2.7. The command names are different because Python 3 has the ability to create virtual environments built-in.

    • $ pyvenv-3.4 venv-3.4
      $ virtualenv venv-2.7
      $ source venv-2.7/bin/activate
  2. Set up mailman using the python executable from the 3.4 virtualenv. You should get a positive message at the end of this saying that mailman is essentially running.
    • $ cd mailman
      $ ../venv-3.4/bin/python setup.py develop
      $ ../venv-3.4/bin/mailman start
      $ cd ..
  3. Set up everything else (it's a long slog but isn't that bad!). You will be prompted to enter details for a superuser account. Please enter an email address otherwise the database won't be setup correctly and you will run into errors later.
    • $ cd mailmanclient
      $ python setup.py develop
      $ cd ..
      $ cd postorius
      $ python setup.py develop
      $ cd example_project
      $ python manage.py migrate
      $ python manage.py createsuperuser
      $ cd ..
      $ cd hyperkitty
      $ python setup.py develop
      $ cd ..
  4. Start up the postorius web ui for mailman:
    • $ cd postorius/example_project
      $ python manage.py runserver

If you find yourself unable to log in to postorius, it may be because you don't have a mail server set up (so it can't send an email to verify your admin address). You can use a dummy email backend for a bit while you're testing by adding the line

EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'

to postorius/example_project/settings.py and then those emails will be printed to the postorius console. But don't leave that setting in when you get to the point where you want to send real emails!

Get HyperKitty going

Okay, now you're got postorius up and running, but you'll need to do some other config to get HyperKitty going. Just follow the guide here: https://hyperkitty.readthedocs.org/en/latest/development.html. Since we also have Postorius running, you'll have to add "8002" to the last runserver command, because you need an available port:

$ cd ../hyperkitty
$ django-admin.py runserver 8002 --pythonpath example_project  --settings settings &

Now you should be able to view the mailman management UI (postorius) at http://localhost:8000 and you should be able to view hyperkitty at http://localhost:8002.

Like with postorius, if you can't log in to hyperkitty, you might try adding the dummy email backend settings.py to print those emails to the console:

EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'

Again, don't leave that setting in when you get to the point where you want to send real emails!

If you want to tell Mailman to send the incoming emails to HyperKitty for archiving, you must install and setup the mailman-hyperkitty plugin.

$ cd mailman-hyperkitty
$ ../venv-3.4/bin/python setup.py develop
$ cd ../mailman

Now create a file mailman-hyperkitty.cfg and add the following to it:

#mailman-hyperkitty.cfg
[general]
base_url: http://localhost:8002/
api_key: SecretArchiverAPIKey

Now you have to enable hyperkitty in mailman, to do that, edit the mailman.cfg at var/etc/ and add the following config. Note that you need to fill in the absolute path to your mailman-hyperkitty.cfg in the configuration below.

#mailman.cfg
[archiver.hyperkitty]
class: mailman_hyperkitty.Archiver
enable: yes
configuration: <absolute path to mailman-hyperkitty.cfg>

And now restart Mailman using the new mailman.cfg configuration file:

../venv-3.4/bin/mailman stop
../venv-3.4/bin/mailman start