Skip to content

Setup

This guide will walk you through setting up errbot for local development 🔨

Project Components

Key concepts:

There are three main components to errbot:

  • The chatbot itself - This is errbot, the python app running in a docker container which processes requests - src/errbot/
  • The chat-service - This is what you are connecting your chatbot to. This could be Discord, Slack, etc.. I will be using Discord for this guide but Slack is also tested and works fine.
  • The database - This could be literally anything to store state since the nature of containers is ephimeral. For this project I have chosen AWS DynamoDB for state storage. When testing locally I use LocalStack to mock AWS DynamoDB.

Prerequisites

If you got all the items below downloaded and are familiar with setting up a bot account for your chat service (Slack, Discord, etc), you can skip right to the usage section.

Depending on which "backend" or "chat-service" you plan on using, you will need an authentication token to start your bot.

Lastly, you will need to be familiar with how to add your bot to your chat service.

Adding your bot to a chat service examples:

Slack

In the case of Slack, this can be done by mentioning your bot in any channel and you will be prompted to invite the bot right there.

Note, this particular repo leans towards Discord for most things. However, as of this writing, all features of this bot work in Slack as well with the exception of having the bot join a voice channel as that is not a feature of Slack.. yet

Discord

This bot has already been provisioned to Discord. It is included as a reference should the bot ever need to be rebuilt

With Discord, things are a little different. You will need to first enable SERVER MEMBERS INTENT for your bot application. After that, you need to go into the Oauth2 page for your bot and select the bot scope. This will expand more options. You may go as crazy or as restrictive as you want with the chat permissions. That part is totally up to you.

Once your permissiosn are scoped out, you will need to copy the oauth2 link that is generated.

It could look something like this: https://discord.com/api/oauth2/authorize?client_id=<number>&permissions=<number>&scope=bot

Note: You can find an example invite link farther below

Enter that link into your web browser and it should give you a list of servers to invite your bot to. Add it to your favorite server!

To setup your bot, you will need to modify your config.env file. To make things easier, there is a config.example.env file in the root of this repo.

  1. Rename config.example.env to config.env *required
  2. Set BACKEND=<backend> *required
  3. Set CHAT_SERVICE_TOKEN='<token>' *required
  4. Change BOT_PREFIX='!' if you want *optional

Usage - Locally

Important: Make sure you followed the setup instructions above first

For plugin testing and running the bot locally, you may run the following command to launch a local instance of your bot and interact with it over the command line:

$ make local
[#] Starting local bot test environment
[#] Killing old docker processes
docker-compose rm -fs
Stopping chatbot ... done
Going to remove chatbot
Removing chatbot ... done
[#] Building docker containers
docker-compose build
Building chatbot
[+] Building 1.3s (22/22) FINISHED
...
..
.
[#] TEST Container is now running!
[#] Interact with me over the CLI prompt below
...
..
.
[@local_admin âž¡ @errbot] >>>

Note: You may notice some errors in your output. This is expected if you do not have all the proper credentials setup in your creds.env file. For example, if you have an API token that is needed for a plugin, and that token is not present in the environment, that plugin will fail to load. All others should load fine and you can test normally.

Read more about the errbot local dev environment here

Windows Tips for Local Usage

If for some reason you are using Windows and not WSL, you can build a local image using the following commands:

$ docker-compose build
[+] Building 1.3s (22/22) FINISHED
$ docker run -it --rm --env-file config.env --env-file creds.env -e LOCAL_TESTING=True errbot_chatbot:latest

This will result in a CLI prompt to errbot locally so you can test. Simply press CTRL+C to exit when you are done

Usage - Connected to a Chat Service

Completed the simple setup locally? Awesome! Let's start the bot connected to a live chat service:

Note: make run will start the bot and attach it to Discord (or another chat service) for usage. If you are looking to start a local instance of the bot, see the Usage - Locally section earlier in this guide

$ make run
[#] Killing old docker processes
docker-compose rm -fs
No stopped containers
[#] Building docker containers
docker-compose up --build -d
Building chatbot
[+] Building 1.3s (23/23) FINISHED
Creating chatbot ... done
[#] Container is now running!

Note: for security reasons the creds.env file is not committed to this repo and NEVER should be.

If you followed the steps above and everything succeeded, you should get a DM from the bot stating that it is "Now Online". You should note that you will only get this message if BOT_ADMINS='@username' is set to your username in the config.env file.

Note x2: Running make run will start the errbot-dev bot and can be invoked with ! rather than the usual .. You can tweak this however you like with the BOT_PREFIX env var

That's it for the setup! If you followed the instructions above, your Docker container should start and most plugins should load correctly. Certain plugins like the league plugin require an API key so those will fail until that environment variable is provided but this is expected. All this and more will be covered in the next section!

What's next?

Continue on to the configuration section to learn how you can configure your bot to your preferences before you start development.