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.
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/file.py 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/my_settings.py
$ 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 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