https://github.com/ceejbot/opsbot
the npm operations chatbot is fully operational
https://github.com/ceejbot/opsbot
Last synced: about 1 year ago
JSON representation
the npm operations chatbot is fully operational
- Host: GitHub
- URL: https://github.com/ceejbot/opsbot
- Owner: ceejbot
- License: isc
- Created: 2014-03-15T16:38:35.000Z (over 12 years ago)
- Default Branch: master
- Last Pushed: 2022-05-12T16:53:23.000Z (about 4 years ago)
- Last Synced: 2024-11-06T22:52:04.334Z (over 1 year ago)
- Language: JavaScript
- Homepage:
- Size: 246 KB
- Stars: 15
- Watchers: 5
- Forks: 6
- Open Issues: 53
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# opsbot
Hermione the npm operations [Slack](https://slack.com) chat battlestation is fully operational and is capable of demonstrating its power on a target, a military target. Name the system!
[](https://www.npmjs.org/package/opsbot) [](http://travis-ci.org/ceejbot/opsbot) [](https://coveralls.io/github/ceejbot/opsbot?branch=master) [](https://david-dm.org/ceejbot/opsbot)
## deploying
You'll want to create your own little node package for your installation. This package needs a `package.json`, a configuration file, and a shell script to run the bot.
Here's a nice minimal package.json, requiring opsbot & a third-party plugin:
```json
{
"name": "deathstar",
"version": "0.0.0",
"description": "a bot of destruction",
"scripts": {
"start": "opsbot config.js",
"dev": "NODE_ENV=dev opsbot testconfig.js"
},
"dependencies": {
"opsbot": "~3.0.0",
"opsbot-owl": "^0.0.1"
}
}
```
To create your configuration file, start by copying [config.example.js](https://github.com/ceejbot/opsbot/blob/master/config.example.js). Edit to your taste. You can have it log to console and/or log to a file depending on how you want to keep its logs. `npm start` runs the bot in prod mode. `npm run dev` will run it with pretty-printed console output.
List the plugins you want to load as fields in the `plugins` hash. The value should be an object with any required configuration for the plugin. Note that opsbot can load both built-in plugins and plugins installed via npm.
Example configuration:
```json
{
botname: "hermione",
admin_channel: "your-admin-channel-id",
brain: { dbpath: "./db" },
plugins:
{
bartly:
{
apikey: "your-bart-api-key",
station: "powl",
tzOffset: 420,
},
}
}
```
Create a Slack bot and copy its API key. You must provide that key in the environment variable `SLACK_TOKEN`. One way to do that is to create a `.env` file containing the text `SLACK_TOKEN=your-token-here`. Opsbot will read that file if it's present.
## built-in commands
`botname: help`: return a help message
`botname: status`: gives bot uptime, loaded plugins, and location of the bot's brain.
## writing plugins
Plugs in are [yargs command modules](http://yargs.js.org/docs/#methods-commandmodule). To write a plugin, write a yargs command and then load it into opsbot via config. The handler for the yargs command has an object with all the usual yargs parsed items in it, plus a `reply()` function that can be called as many times as you wish to post messages to the Slack channel the original command came from.
`reply('string of text')` posts the given string of text.
`reply(messsageObj)` posts a message as formatted according to the [Slack message API](https://api.slack.com/methods/chat.postMessage).
Here's very boring plugin.
```javascript
function builder(yargs) {}
function handler(argv)
{
argv.reply('https://cldup.com/5B3kURG8aE.jpg');
}
module.exports = {
command: 'ORLY ',
describe: 'If you say ORLY?, you get the obvious response.',
builder: builder,
handler: handler
};
```
Let's suppose we've published this on npm as `opsbot-owl`. To load this epic chatbot feature, you'd add the module as a dependency of your bot package and then mention it in the config like this:
```json
{
botname: "wol",
admin_channel: "your-admin-channel-id",
plugins:
{
"opsbot-owl": true
}
}
```
## Provided plugins
__bartly:__ Real-time BART departure information by station. Requires an API key and, of all things, a timezone offset.
__flip:__ Table flip!
__rageflip:__ Really table flip!
__karma:__ Give points and take them away. Requires a database.
__npm:__ Fetch package information from npm.
__statuscats:__ Show an [http status cat](http://http.cat).
__statuscats:__ Show an [http status dog](http://httpstatusdogs.com).
__morph:__ Morph one word into another using a nice short path.
Each plugin has more documentation at the top of its source file.
## Plugin storage
Opsbot uses [levelup](https://github.com/rvagg/node-levelup) to provide a persistent key/value brain to plugins. Each plugin is, on construction, given an options object with a sublevel-namespaced db object in the `brain` field. This object might not be available if the opsbot configuration hasn't given it a path to store the db in, so your plugin should assert if it requires the brain but is not given one. See an example in the built-in `karma` plugin.
## Contributing
Write more plugins, add features to the existing plugins, it's all good.
Please follow the code style in existing files. `npm run lint` catches style problems as well as bugs. `xo --fix` might or might not actually fix them. If you write your own plugins, I don't much care what you do. Please try to be at least as responsible as I have been about writing tests.
If you want to use promises, go ahead! [bluebird](https://github.com/petkaantonov/bluebird) is already in the package deps.
If you write a plugin for opsbot & publish it on npm, please let me know so I can link it here! It might also help to give it the keyword `opsbot` so other people can find it when they search.
## License
[ISC](http://opensource.org/licenses/ISC)