Getting started with Bo

Installation

Bo is best installed from pypi via pip (recommended) or easy_install. The use of virtualenv is highly recommended to avoid polluting the global Python environment. For example, to install Bo using pip:

$ pip install bo

Deploy on Heroku

Instead of running it local, you can deploy Bo on Heroku:

$ git init bo-heroku
$ cd bo-heroku/
$ heroku create --stack cedar
$ wget -O config.yaml "https://raw.githubusercontent.com/konikos/bo/master/conf/xmpp.yaml"
$ echo "bo" >requirements.txt
$ echo "worker: bo -c config.yaml" >Procfile

Set your password in config.yaml and probably add some plugins.

Warning

If you use a GMail account, read this to avoid getting locked out of your account.

Now, run the following to get Bo working:

$ git commit -a -m 'init'
$ git push heroku master
$ heroku ps:scale worker=1

If you are having issues running Bo, use heroku logs to examine the output from Bo and heroku restart to restart it.

Basic usage

After installation you can test the bo command:

$ bo
usage: bo [-h] -c CONFIG [-l LOGFILE] [-q | -d]
bo: error: argument -c/--config is required

The bo commands requires a configuration file to set up a bot. Configuration files are written in YAML. Here is an example to get you started:

name: Bo Example

plugins:
  - bo.dist.plugins.rand
  - bo.dist.plugins.uptime
  - module: bo.dist.plugins.logs
    config:
      max_entries: 100
  - bo.dist.plugins.sing

connectors:
  - name: Console
    module: bo.dist.connectors.console

The configuration is pretty self-explanatory; it gives a name to the bot, and sets up some plugins as well as the console connector in order to interact with the bot via the console. The bo.dist.plugins.logs entry is different than the rest because configuration is needed for the plugin (in this case, the max_entries option).

Save the configuration as console.yaml and run bo to interact with Bo for the first time:

$ bo -c /path/to/console.yaml