Hubot is a chat bot built on the Hubot framework.
It was initially generated by generator-hubot, and configured to be deployed by enterprise usage.
This README is intended to help get you started.
Please update with any information that can help others understand how she is deployed and configured.
You will need to install a few libraries to install Hubot. The commands are:
sudo bash
sudo apt-get update
sudo apt-get install nodejs npm python-setuptools python-dev build-essential pylint libjson-perl openjdk-8-jdk
sudo easy_install pip
sudo pip install requests
Install redis for back end brain, allow binding, and start at spin up
sudo apt-get install redis-server
sudo sed -i 's|bind 127.0.0.1|#bind 127.0.0.1|g' /etc/redis/redis.conf
sudo systemctl enable redis-server.service
Create the user with command:
useradd -m Hubot-Name
sudo vi /etc/sudoers
add the line:
Hubot-Name ALL=(ALL) NOPASSWD:ALL
under:
# User privilege specification
root ALL=(ALL:ALL) ALL
Write this file with :wq!
You will need to become the hubot user and clone the base repo down the first time.
sudo su - Hubot-Name
sudo mkdir /opt/Hubot-Name
sudo chown Hubot-Name:Hubot-Name /opt/Hubot-Name
cd /opt/Hubot-Name
git clone https://$TOKEN@github.com/OrgName/RepoName.git /opt/hubot/
Go to your main channel you want to configure your hubot instance and select Options and add an app Select Hubot Set basic configs and copy connector url to hubot.env NOTE: The name must match the hubot name!
Hubot is configured to run on an ubuntu instance
You can start/restart Hubot by running :
/opt/Hubot-Name/start.sh
NOTE: You need to be the user: Hubot to run this command!
You'll see some start up output and a prompt :
[Wed Dec 27 2017 11:56:02 GMT+0000 (UTC)] DEBUG Parsing help for /opt/Hubot-Name/node_modules/hubot-cron/src/scripts/cron.coffee
[Wed Dec 27 2017 11:56:02 GMT+0000 (UTC)] DEBUG Parsing help for /opt/Hubot-Name/node_modules/hubot-codinglove/src/codinglove.coffee
[Wed Dec 27 2017 11:56:02 GMT+0000 (UTC)] DEBUG Parsing help for /opt/Hubot-Name/node_modules/hubot-standup-alarm/scripts/standup.coffee
[Wed Dec 27 2017 11:56:02 GMT+0000 (UTC)] DEBUG Successfully connected to Redis
[Wed Dec 27 2017 11:56:02 GMT+0000 (UTC)] INFO Data for Hubot brain retrieved from Redis
[Wed Dec 27 2017 11:56:03 GMT+0000 (UTC)] INFO Found 32 flows, and I have joined 28 of them.
[Wed Dec 27 2017 11:56:03 GMT+0000 (UTC)] INFO Connecting to Flowdock as user Hubot (id 218853).
[Wed Dec 27 2017 11:56:03 GMT+0000 (UTC)] INFO Flowdock: connecting
[Wed Dec 27 2017 11:56:03 GMT+0000 (UTC)] INFO Flowdock: connected and streaming
[Wed Dec 27 2017 11:56:03 GMT+0000 (UTC)] INFO Flowdock: listening to flows: Lukas-TestGround, Lukas-Personal...
...
Hubot will start logging as soon as she is started. Her logs can be located at:
/opt/Hubot-Name/logs/Hubot.log
From her logging you can see all activity she can currently listen to, and how she is responding.
You will be able to see Github payloads being passed to her for inspection, her various listeners responding in various chat rooms, etc...
Then you can interact with Hubot by going to Flowdock, Slack, or most other internet based chats, and finding a room with her listening, and typing Hubot help.
Hubot> Hubot help
Hubot animate me <query> - The same thing as `image me`, except adds [snip]
Hubot help - Displays all of the help commands that Hubot knows about.
...
Hubot has a very long list of actions she can accomplish. Please check her full help list to see the commands she can interact with.
A few scripts (including some installed by default) require environment variables to be set as a simple form of configuration.
Each script should have a commented header which contains a "Configuration" section that explains which values it requires to be placed in which variable. When you have lots of scripts installed this process can be quite labour intensive. The following shell command can be used as a stop gap until an easier way to do this has been implemented.
grep -o 'hubot-[a-z0-9_-]\+' external-scripts.json | \
xargs -n1 -i sh -c 'sed -n "/^# Configuration/,/^#$/ s/^/{} /p" \
$(find node_modules/{}/ -name "*.coffee")' | \
awk -F '#' '{ printf "%-25s %s\n", $1, $2 }'
How to set environment variables will be specific to your operating system. Rather than recreate the various methods and best practices in achieving this, it's suggested that you search for a dedicated guide focused on your OS.
Most of Hubot secrets are stored in this file. She needs a place to store endpoint urls, api keys, tokens, usernames, passwords, etc...
To hide this information, you can encrypt this file, and at deployment time, the file is decrypted and placed into location and values are loaded.
If you ever need to make an update to her hubot.env, the process is as follows:
- log into hubot machine
- su - Hubot-Name
- vi /opt/Hubot-Name/hubot.env
- make the additions/modifications/deletions needed
- /opt/Hubot-Name/deploy/pushEnvUpdateToGhe.pl
The script will give a warning message and run a small timer to prevent any accidents. It will then run all the automation needed to encrypt the file, upload, etc...
It is in the best interest we keep this file encrypted. It stores usernames, passwords, tokens, and other valuable keys.
Not backing this file up also would be a big risk, so we need to store it in source control encrypted.
The encryption technique is fairly simple and we have it automated which is helpful.
The main scripts:
- Automation/Deploy/encryptEnv
- Automation/Deploy/decryptEnv
- Automation/Deploy/pushEnvUpdateToGhe.pl
The math is done in the encrypt and decrypt scripts, but its basically using the build systems gpg keys to sign and encrypt and decrypt.
This could become an issue if you ever moved Hubot from one machine to another. At that point, the encrypted key could NOT be decrypted from the new machine. To solve that type of issue, you would need to decrypt the key in the old machine, transfer it to new machine, and encrypt it there. Then the decryption would work again.
The whole process for this works in the following format.
- When Hubot is deployed, she pulls the encrypted hubot.env from the deploy folder, to her root
- She then runs her decrypt script against it to be able to read the values
- If she cant decrypt the file, she will fail to start
All scripts live in the folder: scripts and are nested below that.
When Hubot is started she will only read from files ending in .coffee from that folder.
For the various integrations, they are nested in folders below.
An example script is included at scripts/Basic-Fun.coffee, so check it out to
get started, along with the Scripting Guide.
For many common tasks, there's a good chance someone has already one to do just the thing.
The process we try to follow is do the real work outside of the coffeescript.
Most integrations work in the form of:
- coffeescript to listen for Hubot commands
- coffeescript will delegate the work and output to another script of your choice.
This form works well as connecting to api's, other machines, etc... can be done easily in python, ruby, etc...
There will inevitably be functionality that everyone will want. Instead of writing it yourself, you can use existing plugins.
Hubot is able to load plugins from third-party npm packages. This is the
recommended way to add functionality to your hubot. You can get a list of
available hubot plugins on npmjs.com or by using npm search:
% npm search hubot-scripts panda
NAME DESCRIPTION AUTHOR DATE VERSION KEYWORDS
hubot-pandapanda a hubot script for panda responses =missu 2014-11-30 0.9.2 hubot hubot-scripts panda
...
To use a package, check the package's documentation, but in general it is:
- Use
npm install --saveto add the package topackage.jsonand install it - Add the package name to
external-scripts.jsonas a double quoted string
You can review external-scripts.json to see what is included by default.
It is also possible to define external-scripts.json as an object to
explicitly specify which scripts from a package should be included. The example
below, for example, will only activate two of the six available scripts inside
the hubot-fun plugin, but all four of those in hubot-auto-deploy.
{
"hubot-fun": [
"crazy",
"thanks"
],
"hubot-auto-deploy": "*"
}NOTE: Be aware that not all plugins support this usage and will typically fallback to including all scripts.
Before hubot plugin packages were adopted, most plugins were held in the hubot-scripts package. Some of these plugins have yet to be migrated to their own packages. They can still be used but the setup is a bit different.
To enable scripts from the hubot-scripts package, add the script name with
extension as a double quoted string to the hubot-scripts.json file in this
repo.
Hubot uses a Redis DB 'brain' to store some of her memories and basic data. This is used for basic actions and to store who can run certain functions.
Adapters are the interface to the service you want your hubot to run on, such as Campfire, Slack, Flowdock, IRC. There are a number of third party adapters that the community have contributed. Check Hubot Adapters for the available ones.
To configure the webhook, you will need to navigate to Settings in your repository.
Select the Webhooks sub tab.
Create a new Webhook with the following information.
For Payload URL: http://ec2-52-37-117-161.us-west-2.compute.amazonaws.com:5555/hubot/github-repo-listener
Content Type: Application/Json
Secret: 2spooky4me
Let me Select Individual Events: Push and Pull Request
Verify it is selected: Active and Save
Hubot listens to her own repository for pull requests and merge to master.
When a pull request is closed and merged to master, Hubot will start her upgrade process.
She will call Jenkins to run Hubot-Pipeline
This script will:
- Send notification update
- Build test bot
- Verify it starts successfully
- Backup Hubot
- Build Hubot
- Send notification update
You can restart Hubot by logging into the machine and running the script:
/opt/Hubot-Name/start.sh