opkit-example v1.0.3

opkit-example

opkit-example is an example DevOps bot for Slack written using the opkit framework (available at https://github.com/bandwidthcom/opkit under the MIT license). This bot aims to not only show the capabilities of opkit as a framework, but to also serve, out of the box, as a reasonably useful bot for managing AWS EC2-based deployments on the fly.

Deployment Instructions - Heroku

Opkit-example can run easily on a single free or hobby tier Heroku instance. Follow the below link to deploy Opkit-Example to Heroku:

You'll also need to set four environment variables (Heroku calls them 'config vars') for the bot to actually fully work. The amazon tokens are not necessary, but the commands that use AWS will not work without the environment variables set.:

token: Your Slack API token. You can get one at https://$YOUR_TEAM.slack.com/apps/manage/custom-integrations.
amazonId: Your AWS ID.
amazonSecret: Your AWS Secret ID (other API token they provide)
amazonRegion: Your AWS region (e.g. 'us-east-1')

We recommend naming your Slack bot user opkit. You can even give it a funny avatar.

Deployment Instructions - Local

By default, this example uses MongoDB to persist data, and the auth functionality included depends on MongoDB. You will need a MongoDB URI stored as an environment variable called MONGODB_URI in addition to the four variables defined above. To deploy locally, npm install opkit-example, and run node server.js with your variables set. By default, Heroku will give you a hobby dyno; changing the type to "free" will allow you to run the bot for free.

Operation Instructions

Once you've deployed your bot, invite the bot user to the relevant channels. Run opkit populate before other commands to populate the MongoDB with user information for access control purposes. The command will only work once; feel free to delete lines 13 and 17 in the server.js file to remove it from the help command's listing.

The example bot has a few commands that you may find useful; the bot has a help command, at opkit help, that lists all of the commands. The opkit health command provides a summary of your CloudWatch alarms; use opkit health notok to zero in on the failing alarms. Start and stop your environments using opkit ec2 start and opkit ec2 stop, solve all of your problems by turning it off and back on again with ec2 reboot, and retrieve logs using opkit ec2 getlogs. You don't even need a sysadmin!

Have some exclusive resource (remote boxes or environments?) Opkit has a built-in method for keeping track of "who's using the environment". opkit env use and opkit env release let you queue up to use the remote box, and opkit env add and opkit env delete add and remove those boxes. Note that, by default, persistence occurs on a provisioned Mongo sandbox. Look below for information on how to persist to a different database!

There are many other commands, too; use opkit help to get a list of them.

Advanced operation and modification

Changing your data store

If you prefer a different data store, change line 23 of server.js to either RedisPersister or PostresPersister, passing in the appropriate URL. The default authentication function, however, only supports Mongo.

Adding more commands

Commands have a format; they should have a name, a syntax, a script to "package" them together, a description, and a manpage. The actual command field can be a function(message, bot, auth, brain), and it should return a promise. Take a look at a few commands to see how they work and what metadata is necessary to run them. The "minimum viable command", as it were, is lib\pls.js. Full schemas for these objects are provided in the opkit readme. The opkit package includes many helper functions that simplify querying AWS; the javadoc available at http://bwdemos.com/opkit/ documents these helper functions.