CamperBot

This is a full featured bot for Gitter.im/FreeCodeCamp chat rooms.

Main features:

• integration with github FCC wiki
• find (alias explain) command to show wiki pages
• wrapper for commands

The CamperBot is integrated into various FreeCodeCamp chat rooms.

Join us in Gitter.im/FreeCodeCamp/camperbot to discuss about camperbot development!

Test the CamperBot in the Gitter.im/FreeCodeCamp/camperbotPlayground room.

CamperBot was originally created by for Free Code Camp by @dcsan at RIKAI Labs, and is now maintained by our open source community.

Contents

• Introducing CamperBot!
• Installation instructions
• Mac / Linux
• Windows
• Make your own bot user
  • Getting your own appID
  • Configure your bot!
• Running tests
• Wiki Content
• System Overview
• Room Joins
• Bot Commands
• Wiki Data
• Room Messages
• Create own bot command
• Bot command details
• Environment Notes
• Contributing
• Chat with us!

Introducing CamperBot!

CamperBot is a full featured chat bot for Gitter.im developed to integrate with the chat rooms for FreeCodeCamp — the largest online coding bootcamp in the world , where it serves more than 60,000 campers.

Github Wiki Search

You can search for articles in a projects github wiki

Share wiki summaries in chat

Use explain to pull a wiki summary right into the chat:

Points system

Allow your users to send points to each other to say thanks @username

Fixed messages

Based on scannable expressions, send messages into the chat.

Extensible

Custom functions can easily be added. Check the System Overview

Installation instructions

To run camperbot, you need Node.js 4.2.0 or greater.

Mac / Linux

To install Node, follow the instructions here

• To make your local server automatically watch for file changes, install "nodemon" (you may need sudo)

npm install -g nodemon

• To download the app, clone the repository the bot is in:

git clone https://github.com/FreeCodeCamp/camperbot.git

• Run the following commands to run the app:

cd camperbot
cp dot-EXAMPLE.env .env
cp example.config.json config.json
git submodule update --remote --checkout --init --recursive
npm install
nodemon app.js

• That's it! The app should be running at http://localhost:7891.

You can now chat to your bot via Gitter.im at https://gitter.im/demobot/test

Windows

To install Node.js on Windows, follow these instructions.

• To make your local server automatically watch for file changes, install "nodemon" in an administrator console.

npm install -g nodemon

• To download the app, clone the repository the bot is in:

git clone https://github.com/FreeCodeCamp/camperbot.git

• Run the following commands to run the app:

cd camperbot
copy dot-EXAMPLE.env .env
copy example.config.json config.json
git submodule update --remote --checkout --init --recursive
npm install
nodemon app.js

• That's it! The app should be running at http://localhost:7891.

You can now chat to your bot via Gitter.im at https://gitter.im/demobot/test

Make your own bot user

If you've followed the instructions so far your bot instance is the demobot provided for you.

The .env file you copied above contains login info. This is using the shared "demobot" account so you may find yourself in a chatroom with other people using the same ID!

Here are instructions on getting your own bot user running.

Setup GitHub user

The first thing you'll want to do is set up a GitHub account which will be the username of your bot

You can either

• make a new account
• use an existing account

Follow the instructions for signing up on https://github.com/

change the SERVER_ENV=demobot in your .env to server_ENV=USERNAMEHERE where USERNAMEHERE is your github user name.

Getting your own appID

To setup your own gitter login info, you should create your own Gitter API key on their developer site, and replace the info in that .env file. Get your own API keys for gitter from: https://developer.gitter.im/apps

When you sign in to the developer page select the option to make an app. Name the app what you want and set the callback url to http://localhost:7891/login/callback

The next page should show you various API keys/secrets. Use those to replace the demobot default options in your .env.

Configure your bot

Now it is time to set up your bot w/ the app. Copy example.config.json to config.json and open config.json in your editor. Replace all instances of GITHUB_USER_ID with your user name set up earlier.

Take note of the the rooms property of config. You can set up additional gitter rooms to connect your bot to here. The default room is GITHUB_USERID/test feel free to change this.

You may chat with us in the CamperBot Dev chat room if you have problems. contributors chatroom.

Running tests

Tests are located in the test/ folder can be run, along with linting, by running gulp. This is a watch task that will rerun whenever a .js file changes.

Wiki Content

The wiki content is pulled in from FCC's wiki using a git submodule. But then we just copy it and commit it back to the main app as submodules are nasty to deal with on production servers.

bin/wiki-update.sh

System Overview

data/RoomData.js

The list of rooms your bot is going to join.

To start with create your own bot, a test room to enter and debug in. This needs to be changed so you would only join your own rooms, otherwise developers will get into a situation where everyone is joining the same rooms and the bots go crazy talking to each other!

lib/bot/BotCommands.js

This is where you add things that the bot can do. Some commands are broken into separate files such as cmds/thanks.js and cmds/update.js. Each command gets a input which is a blob of data including what the user entered, and a bot instance.

KBase.js

The Knowledge base. This is an interface to all the data in the wiki.

RoomMessages.js

This is for static messages that are fired based on regex matches. If you just want to add some basic responses, this is the place to edit.

How to add a new Bot Command

Look at BotCommands, echo function. This is an example of a command being called. Anytime a user types a line starting with echo that will get passed to this function in input.

echo: function(input, bot) {
    var username = input.message.model.fromUser.username;
    return "@" + username + " said: " + input.message.model.text;
}

The input object contains keyword and params fields. If you type echo this you'll get

//input
{
    keyword: 'echo',
    params: 'this'
}

From any command you just return the new string you want to output. So you can add new commands with this knowledge.

More detail on how commands are found and called

In GBot.js

if (input.command) {
    // this looks up a command and calls it
    output = BotCommands[input.keyword](input, this);
} else {

BotCommands is a list of functions. E.g.

BotCommands.thanks = function() { ... }

where input.keyword is thanks then

BotCommands[input.keyword] is like saying BotCommands.thanks()

so then the params get also added in (input, this) so its

BotCommands[input.keyword](input, this);
//becomes
BotCommands.thanks(input, bot);

All of the bot commands expect these two params. E.g. in thanks.js

var commands = {
    thanks: function (input, bot) {

In RoomMessages.js we also have a table of regex and matching functions.

{
    regex: /\bth?a?n?[xk]s?q?\b/gim,
    func: BotCommands.thanks
}

We may switch all to just use this method in future. Would you like to help?

Environment Notes

wiki data

We use git submodules for some wiki data. to get these submodules you would do:

git submodule update --remote --checkout --init --recursive

Contributing

Have a look at the HelpWanted label issues and consider making some first steps!

The labels, P1 = priority one, and 'S' means a small task, so good places to start.

Chat with us!

Chat with us in the contributors chatroom if you get stuck.