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