Skip to content

Instantly share code, notes, and snippets.

What would you like to do?

Creating a complete botbot development environment using Docker containers

Botbot is a strange piece of software, it consists of three different repositories and uses at least three different programming languages (namely Python, Go and JS).

For basic plugin development using botbot-shell if often sufficient but as soon as you want to do some manual integration testing or work on botbot-web you're going to need a full dev environment.

The goal of this guide is to walk you through setting up a complete botbot setup that I would not exactly recommend for production but should be fine for development and testing.

Disclaimer: This guide assumes you won't want to work on botbot-bot as we haven't forked that yet but go should allow for installing packages from local sources the same way pip does.

This guide is based on the official installation guide.


  • Python 2
  • Go
  • Docker
  • virtualenv
  • postgresql (we need pg_config)
  • Some IRC server, could be something like freenode or your own (I use a docker one)

Cloning & Dependencies

git clone

git clone

Create a virtualenv and activate it:
virtualenv -p python2 venv
source venv/bin/activate
or if you're using virtualenvwrapper:
mkvirtualenv -p python2 botbot
workon botbot

Run botbot-web's makefile, this will take quite a while:
make dependencies


While this is running, let's continue by setting up our docker containers, pull redis and postgres:
docker pull redis
docker pull postgres

And start them:
docker run --name botbot-redis -p -d redis
docker run --name botbot-postgres -e POSTGRES_PASSWORD=botbotpasswd -p -d postgres

The official guide has some additional steps for database setup so we'll run them on the postgres container:
docker exec botbot-postgres createdb -U postgres botbot
docker exec botbot-postgres psql -U postgres -c "create extension hstore"


Now back to botbot-web, first cd into its directory:
cd botbot-web

Now copy .env.example to .env and change the line

Now activate the env:
export $(cat .env | grep -v ^# | xargs)
You'll only have to do this during the installation, honcho should handle it in the future.

Final steps

If you're lucky and botbot-web is done installing the dependencies, you can now continue.

Seeing as we're going to work from a local clone of botbot-plugins, uninstall the current one and tell pip to use the repo instead:
pip uninstall botbot-plugins
pip install -e /path/to/botbot-plugins

For some reason Procfile assumes is in $PATH so you'll have to replace in Procfile with ./

Before you can run botbot, you need to set up the database for it by running:
./ migrate

Then create an admin account:
./ createsuperuser

Now you can start the server using honcho start.

You should now have a running botbot installation! However if you're testing your bot, please create a testing channel for that and do not do that in #metabrainz.

Tips and Tricks

You can start modules seperately using honcho start <module>.
E.g. to be able to keep bot and web running while working on plugins, run honcho start bot web in one terminal and honcho start plugins in another.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment