README.rst

csbot - an IRC bot

This is an IRC bot developed by members of HackSoc to provide various features in the #cs-york channel (and a few others) on Freenode.

Development

csbot is written for Python 3.6+ and based on the asyncio library which became part of the standard library in 3.4.

It's recommend to develop within a virtual environment. This should get you up and running [1]:

$ python3 -m venv venv3
$ source venv3/bin/activate
$ pip install -r requirements.txt
$ csbot --help

Look at csbot.deploy.cfg for an example of a bot configuration.

If you want to develop features for the bot, create a uniquely named plugin (see csbot/plugins/ for examples), try it out, preferably write some unit tests (see csbot/test/plugins/) and submit a pull request.

Deployment

Create csbot.cfg, and then use Docker Compose to build and launch the Docker containers (a MongoDB instance and the bot):

$ docker-compose up

This will use the published image. To build locally:

$ docker build -t alanbriolat/csbot:latest .

Environment variables to expose to the bot, e.g. for sensitive configuration values, should be defined in deploy.env. Environment variables used in docker-compose.yml should be defined in .env:

Variable	Default	Description
CSBOT_CONFIG_LOCAL	./csbot.cfg	Path to config file in host filesystem to mount at /app/csbot.cfg
CSBOT_CONFIG	csbot.cfg	Path to config file in container, relative to /app
CSBOT_WATCHTOWER	false	Set to true to use Watchtower to auto-update when published container is updated

Backup MongoDB once services are running:

$ docker-compose exec -T mongodb mongodump --archive --gzip --quiet > foo.mongodump.gz

Restore MongoDB:

$ docker-compose exec -T mongodb mongorestore --archive --gzip --drop < foo.mongodump.gz

Documentation

The code is documented to varying degrees, and Sphinx-based documentation is automatically generated on Read the Docs: http://hacksoc-csbot.readthedocs.org. Of particular use is the "How to write plugins" section.

You can build the documentation yourself with:

$ pip install -r requirements.docs.txt
$ cd doc/
$ ./regen_apidoc.sh
$ make html

Testing

csbot has some unit tests. (It'd be nice to have more.) To run them:

$ tox

We're also using GitHub Actions for continuous integration and continuous deployment.

[1]	csbot depends on lxml, which is a compiled extension module based on libxml2 and libxslt. Make sure you have the appropriate libraries and headers, e.g. python3-dev, libxml2-dev and libxslt1-dev on Ubuntu or Debian.