Getting Started

Requirements

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.

Important

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

Installing

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.

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 https://github.com/shaunduncan/helga src/helga
$ cd src/helga
$ python setup.py 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 https://github.com/shaunduncan/helga
$ 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 192.168.10.101. 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 setup.py.

$ python setup.py 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