= 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!!

{{{#!wiki caution
These instructions are most likely out of date. Please refer to the general setup guide [[http://docs.mailman3.org/en/latest/prodsetup.html|here]] and Hyperkitty's docs [[http://hyperkitty.readthedocs.io/en/latest/install.html|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. 
 1. 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
}}}
{{{#!wiki note

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
}}}
 1. 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 ..
}}}
 1. 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 ..
}}}
 1. 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!


== Link Mailman to HyperKitty ==

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
}}}