Getting Started


All python requirements for running helga are listed in requirements.txt. Helga supports SSL connections to a chat server (currently IRC, XMPP, and HipChat); in order to compile SSL support, you will need to install both openssl and libssl-dev packages, as well as libffi6 and libffi-dev (the latter are required for cffi, needed by pyOpenSSL version 0.14 or later).

Optionally, you can have Helga configured to connect to a MongoDB server. Although this is not strictly required, many plugins require a connection to operate, so it is highly recommended. “Why MongoDB”, you ask? Since MongoDB is a document store, it is much more flexible for changing schema definitions within plugins. This completely eliminates the need for Helga to manage schema migrations for different plugin versions.


Helga is currently only supported and tested for Python versions 2.6 and 2.7


Helga is hosted in PyPI. For the latest version, simply install:

Note, that if you follow the development instructions below and wish to install helga in a virtualenv, you will need to activate it prior to installing helga using pip. In the future, there may be a collection of .rpm or .deb packages for specific systems, but for now, pip is the only supported means of install.

Deploying with Docker

Helga can now be run in docker. In this you’ll build the docker image yourself, then run it using the docker command. It is recommended that you only use this method if you are already familiar with docker.

$ docker build -t <image:tag> .
$ docker run -d [opts] <image:tag> [opts]

The opts you can choose in the run command are standard options for running docker. If you want to use a settings file that is non-standard, or a persistant datbase, you’ll want to use the -v option to mount those volumes. Additionally, you may add opts to the helga command after specifying the image you’re building.

Some gotchas: If you’re mounting a volume with -v you will need to specify the full path to the directory containing the files you want shared.

If you’re using an altenative settings file you’ll need to add the –settings=/path/to/ opt to the run command.

If you are using an local mongodb, you’ll need to mount it like below, and make sure your settings file reflects the mounted file.

$ docker run -d -v /home/settings:/opt/settings helga:16.04 --settings=/opt/settings/
$ docker run -d -v /path/to/mongodb:/opt/mongodb helga:16.04

Development Setup

To setup helga for development, start by creating a virtualenv and activating it:

$ virtualenv helga
$ cd helga
$ source bin/activate

Then grab the latest copy of the helga source:

$ git clone src/helga
$ cd src/helga
$ python develop

Installing helga this way creates a helga console script in the virtualenv’s bin directory that will start the helga process. Run it like this:

$ helga

Using Vagrant

Alternatively, if you would like to setup helga to run entirely in a virtual machine, there is a Vagrantfile for you:

$ git clone
$ cd helga
$ vagrant up

This will provision an ubuntu 12.04 virtual machine with helga fully installed. It will also ensure that IRC and MongoDB servers are running as well. The VM will have ports 6667 and 27017 for IRC and MongoDB respectively forwarded from the host machine, as well as private network IP Once this VM is up and running, simply:

$ vagrant ssh
$ helga

The source directory includes an irssi configuration file that connects to the IRC server at localhost:6667 and auto-joins the #bots channel; to use this simply run from the git clone directory:

$ irssi --home=.irssi

Running Tests

Helga has a full test suite for its various components. Since helga is supported for multiple python versions, tests are run using tox, which can be run entirely with helga’s

$ python test

Alternatively, if you would like to run tox directly:

$ pip install tox
$ tox

Helga uses pytest as it’s test runner, so you can run individual tests if you like, but you will need to install test requirements:

$ pip install pytest mock pretend freezegun
$ py.test

Building Docs

Much like the test suite, helga’s documentation is built using tox:

$ tox -e docs

Or alternatively (with installing requirements):

$ pip install sphinx alabaster
$ cd docs
$ make html