valkyrie

valkyrie is a chat bot built on the Hubot framework. It was initially generated by generator-hubot.

This README is intended to help get you started. Definitely update and improve to talk about your own instance, how to use and deploy, what functionality is available, etc!

Valkyrie is the name of the Hubot we run in production. Valkyrie can be summoned by name (@Valkyrie) or via her alias (\).

Running Locally

Heimdall is the name of the Hubot we run when working locally on Hubot. Heimdall can be summoned by name (@Heimdall) or via his alias (?).

This allows us to run both production and development Hubots at the same time using the Flowdock adapter, and clearly differeniate which robot we are calling. (Note that both robots will reply to robot.hear commands since those don't require a direct invocation of the robot).

You can test your hubot by running the following, however some plugins will not behave as expected unless the environment variables they rely upon have been set.

If you don't have local values for env vars referenced in ./env-var.list, ask someone how to get these values.

One exception is the Matrix password (when using the Matrix adapter to connect to the Thesis chat server ;see section on Adapters). When using the bin/heimdall script, the script will search for a file matrix-password.gpg that can be decrypted using the gpg tool. If the file exists, the decrypted value will be placed into the HUBOT_MATRIX_PASSWORD environment variable for use by the adapter.

Note that this file is gitignored, and should be encrypted locally with a key accessible to your local gpg, and never committed to source control.

Running locally in the terminal

Install npm if you don't already have it:

brew install npm

You can start Heimdall locally by running:

$ bin/heimdall

You'll see some start up output (it can get pretty verbose - npm i is run at this time) and a prompt:

heimdall>

Then you can interact with Heimdall. If you don't know where to start, try typing ?help:

heimdall> ?help
heimdall> Shell: I can do a lot of things!  Which would you like to know more about? You can say:

(followed by a list of available commands)

Running locally with VS Code

We strongly recommend running locally using Visual Studio Code, to make use of its robust debugging functionality.

Add the following to the "configurations" list in your VS Code's launch.json:

{
    "type": "node",
    "request": "launch",
    "name": "Launch Heimdall Shell Adapter",
    "program": "${workspaceFolder}/node_modules/hubot/bin/hubot.js",
    "args": ["--alias", "?", "--name", "heimdall"],
    "runtimeArgs": ["-r", "coffeescript/register"],
    "console": "integratedTerminal"
},
{
    "type": "node",
    "request": "launch",
    "name": "Launch Heimdall Matrix Adapter",
    "program": "${workspaceFolder}/node_modules/hubot/bin/hubot.js",
    "args": ["--alias", "?", "--name", "heimdall", "-a", "matrix"],
    "runtimeArgs": ["-r", "coffeescript/register"],
    "console": "integratedTerminal"
},

You can then select either "Launch Heimdall Shell Adapter" or "Launch Heimdall Matrix Adapter" (see section on Adapters) from the "Run" menu of the debugging pane.

Running locally with Docker

You can also run using docker, which is what is deployed to kube:

$ brew install npm
$ npm install
$ npm audit fix
$ docker build -f infrastructure/docker/Dockerfile -t valkyrie .
$ docker run -it --env-file ./env-var.list --entrypoint "bin/hubot" valkyrie:latest

To log in to your running hubot container:

$ docker ps | grep 'valkyrie:latest' | awk '{print $1}' | xargs -o -I {} docker exec -it {} /bin/sh

Tests

Test coverage is currently not programmatically enforced, but we are working toward coverage for existing scripts. Any PRs opened should contain tests for new functionality introduced, and fix tests for any breaking changes.

Tests should be saved in the test/ directory; these will be run automatically by Circle CI whenever a branch is pushed to the remote. Test failures will abort the build, and prevent merging.

To run tests locally before pushing your branch: run npm test from the repo root.

Deploying

We use Circle CI in conjunction with Github for our deployment.

Merges to master (via Pull Requests) trigger an automatic deploy of that merge's build.

However, if there have been any changes to the heimdall-hubot-deployment.yaml, those changes will need to be manually applied.

Edit infrastructure/kube/thesis-ops/heimdall-hubot-deployment.yaml to replace USE_CIRCLE_CI_BUILDS with the relevant build number, and then apply:

$ kubectl apply -f infrastructure/kube/thesis-ops/heimdall-hubot-deployment.yaml

Manual deployment

To deploy a new build, you'll need to set up Google Cloud SDK, authenticate, install kubectl, and authenticate docker; again, on macOS:

$ brew cask install google-cloud-sdk
$ gcloud init
$ gcloud components install kubectl
$ gcloud container clusters get-credentials heimdall
$ gcloud auth configure-docker

When running gcloud init you'll want to authenticate with your Thesis credentials and use the heimdall cluster in region us-central-1.

You'll need to make google-cloud-sdk available on your path. brew cask info google-cloud-sdk gives general guidance on properly pathing your install.

The easiest way to check is to see if, after the above steps, you can run kubectl config current-context successfully.

To deploy a new build, you could tag and push your docker image:

$ docker tag heimdall:latest gcr.io/cfc-production/heimdall:my-cool-tag
$ docker push gcr.io/cfc-production/heimdall:my-cool-tag

Edit infrastructure/kube/thesis-ops/heimdall-hubot-deployment.yaml to reference your tag, and then apply:

$ kubectl apply -f infrastructure/kube/thesis-ops/heimdall-hubot-deployment.yaml

Configuration

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.

Scripting

An example script is included at scripts/example.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.

external-scripts

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:

1. Use npm install --save to add the package to package.json and install it
2. Add the package name to external-scripts.json as a double quoted string

You can review external-scripts.json to see what is included by default.

Advanced Usage

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": "*"
}

Be aware that not all plugins support this usage and will typically fallback to including all scripts.

hubot-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.

Persistence

If you are going to use the hubot-redis-brain package (strongly suggested), you will need to add the Redis to Go addon on Heroku which requires a verified account or you can create an account at Redis to Go and manually set the REDISTOGO_URL variable.

% heroku config:add REDISTOGO_URL="..."

If you don't need any persistence feel free to remove the hubot-redis-brain from external-scripts.json and you don't need to worry about redis at all.

Adapters

Adapters are the interface to the service you want your hubot to run on, such as Campfire or IRC. There are a number of third party adapters that the community have contributed. Check Hubot Adapters for the available ones.

If you would like to run a non-Flowdock or shell adapter you will need to add the adapter package as a dependency to the package.json file in the dependencies section.

Once you've added the dependency with npm install --save to install it you can then run hubot with the adapter.

% bin/hubot -a <adapter>

Where <adapter> is the name of your adapter without the hubot- prefix.

Debugging

If you'd like to test certain aspects of Valkyrie with a debugger, use robot.logger.debug and in your environment variables the flag export HUBOT_LOG_LEVEL="debug" which will enable those messages to appear in terminal output.