- Simple Lightweight API Bot (SLAPI)
- Adapter Settings
- Bot ConfigFile
- Admin Settings
- Help Settings - Running the server - Local - Running w/ Docker - CLI w/ Mounted Sock Port - Docker Compose w/ DinD
- Slack Team & Ability to Add Custom Integrations
- Docker 1.10 or later - See Docker section for more info
- Ruby 2.3 or later - See Ruby section for options
- Bundler - See Bundler Section
SLAPI is our concept of a Slack bot. It's blind to languages. While it may be written in Ruby and using Sinatra for it's API interface, it does not care what you use for your plugins.
If you can stick it in a Docker Container or Slap an API on it, you can make it a plugin. (We refer to them as SLAPINs)
SLAPI is in the early stages, we just released the MVP. There is no pre-existing plugins, yet (give us time!). Just examples and test plugins for references.
Check out the getting started below and feel free to open an issue for anything, even if you just want us to explain a little more about something.
Head over to Here for a walk through of the basics getting started
IMPORTANT: Make sure you have looked at Prerequisites first
There are rake tasks created to make this quick to get started.
Running either will create a bot.local.yml file with the exported key and give the most basic configuration.
git clone https://github.com/ImperialLabs/slapi.git
cd slapi
export SLACK_TOKEN=xoxb-XXXXXXXXXXXX-TTTTTTTTTTTTTT
bundle install --binstubs --path vendor/bundle
bundle exec rake local
IMPORTANT: Make sure you have looked at Prerequisites first
git clone https://github.com/ImperialLabs/slapi.git
cd slapi
export SLACK_TOKEN=xoxb-XXXXXXXXXXXX-TTTTTTTTTTTTTT
rake docker
Here's a quick script plugin to get you out the door, kick the tires and give it a go!
just place this in the ./config/plugins/
folder as whatever name you wish to use for it in the bot (e.g. hello.yml
)
plugin:
type: script
language: bash
listen_type: passive
help:
world: "Says Hello World!"
description: "simple hello world"
write: |
#!/bin/bash
if [ "${1}" == 'world' ]; then
echo 'Hello World!'
else
echo 'No World for You!'
fi
Docker must be installed for the bot to work.
- Windows Install - https://docs.docker.com/docker-for-windows/install/
- OSX Install - https://docs.docker.com/docker-for-mac/install/
- Linux Install - https://docs.docker.com/engine/installation/#time-based-release-schedule (See Docker for Linux on left Side)
- Important: If running in Linux, ensure user running SLAPI can run docker, check by running
docker ps
- To enable a user to run docker without sudo go here https://docs.docker.com/engine/installation/linux/linux-postinstall/#manage-docker-as-a-non-root-user
- Important: If running in Linux, ensure user running SLAPI can run docker, check by running
Run the following
gem install bundler
bundle install
The project is set up with extra helpers for VS Code. If you chose to use this then you should be able to run:
gem install bundler
bundle install --binstubs --path vendor/bundle
You will need a bot configuration from Slack. See: https://api.slack.com/bot-users
Once you have configured a bot then you will have a token like: "xoxb-XXXXXXXXXXXX-TTTTTTTTTTTTTT"
You will need to put this in the file config/bot.yml or config/bot.local.yml for example:
NOTE: any .local.yml or .test.yml files are automatically ignored by git or docker
# Adapter Settings
adapter:
type: slack # Enables option alternative adapters
token: # API token
## Coming Soon ##
# user_agent: # User-agent, defaults to Slack Ruby Client/version.
# proxy: # Optional HTTP proxy.
# ca_path: # Optional SSL certificates path.
# ca_file: # Optional SSL certificates file.
# endpoint: # Slack endpoint, default is https://slack.com/api.
# logger: # Optional Logger instance that logs HTTP requests.
# Bot ConfigFile
bot:
name: bot # name for bot to respond to (optional)
# Admin Settings
admin:
users: # Array of names or IDs who are admins
dm_limit: # True/False Limits bot DMs, will not respond to DMs from non-admins.
# Help Settings
help:
level: 1 # 1/2; 1 only lists plugin names, 2 lists names and opts
dm_user: false # True/False; True to send all help requests as DM, false to post in room
plugins:
location: '../../config/plugins/'
To run Sinatra simply run:
If using Global
rackup -p 4567
If using Project
bundle exec rackup -p 4567
Which will use simple the thin server.
This should work in Visual Studio Code when selecting the Sinatra
debug option, however sometimes it seems you need to restart all of Visual Studio Code.
When running in Visual Studio Code, Sinatra tends to run on port 9292.
The settings for Visual Studio Code can be found in the launch.json
file.
To build the docker container locally simply run:
docker build --tag=slapi_local ./
Run with SLAPI using localhost Docker for Plugins
To run the docker container:
NOTE: This will only work on Linux or OSX Based Hosts
NOTE:Running without a config attached your bot will not connect you may want to add a -v /path/to/config:/usr/src/slapi/config
or run docker exec -it slapi_local bash
and manually edit one for testing.
docker run -d -p 4567:4567 -v /var/run/docker.sock:/var/run/docker.sock --name slapi_local slapi_local
To run a released version:
docker run -d -p 4567:4567 -v /var/run/docker.sock:/var/run/docker.sock --name slapi slapi/slapi:latest
Run w/ Config files:
docker run -d -p 4567:4567 -v /var/run/docker.sock:/var/run/docker.sock -v /path/to/config:/usr/src/slapi/config --name slapi slapi/slapi:latest
This setup should work on all Operating Systems supported by Docker
Run the standard compose file docker-compose.yml inside the root of the project
Pulls Latest SLAPI Build and mounts the local ./config directory for bot configs. Change the compose file as needed.
docker-compose up
Build SLAPI container from scratch w/ compose.
docker-compose -f slapi-build-compose.yml up
Overview of how the bot is put together and what's available for use
SLAPI has several API endpoints available to plugins and/or applications.
See more in depth documentation here
- Chat:
- Speak: Simple post to chat options
- Attachment: Formatted Data posted to chat (Title, Text)
- Emote: Post to chat as emote
- Ping: receive a pong
- Brain:
- Save: Save data into bot brain
- Delete: Delete data from bot brain
- Query_Key: Search for a key value in bot brain
- Query Hash: Search for all keys in bot brain, each plugin has it's own hash
- Plugin:
- Reload: Can call a reload of plugins without restart bot
SLAPI utilizes redis for the bot brain.
Brain is only accessible via API for plugins
See more in depth documentation here
SLAPI has 3 different types of plugin options.
See more in depth documentation here
- Script:
- Allows just utilizing a simple script as a plugin
- Currently supports the following languages: Shell/Bash, Ruby, Python, NodeJS
- Has two data options
- Simple: passes the
hello world
from@bot say hello world
to container as exec - All: passes the entire json blob to container as exec.
- Simple: passes the
- Container:
- Allows the use of any language or app that can run in docker on linux
- Has two data options
- Simple: passes the
hello world
from@bot say hello world
to container as exec - All: passes the entire json blob to container as exec.
- Simple: passes the
- API:
- Allows use of anything that can be called by API
- Requires to specific endpoints for SLAPI
- Info Endpoint: Provide the data to build the bot help
- Command Endpoint: Configurable endpoint for SLAPI to post a json payload to with all the information from slack
We have built a rake file to help wrap some of the madness
Just run rake
or bundle exec rake
for a current list of tasks
Both quick options require a export SLACK_TOKEN=xoxb-XXXXXXXXXXXX-TTTTTTTTTTTTTT
There are two quick options here
- local
- Creates a bot.local.yml with the exported Slack Token
- Runs a local bot using rackup in production mode
- docker
- Creates a bot.local.yml with the exported Slack Token
- Runs compose to setup the latest version in dockerhub
You can also just use to avoid creating a bot config
- run:local_prod or run:local_dev (if you want debug)
- run:docker
Important Must be a token from the https://imperiallabs.slack.com/
Quick Option
Requires a export SLACK_TOKEN=xoxb-XXXXXXXXXXXX-TTTTTTTTTTTTTT
- integration
- Creates a bot.local.yml with the exported Slack Token
- Runs a local bot using rackup in production mode
Again, to avoid bot config creation just do
- integration:spec
If you just want to clear out the cruft (scripts, bot.test.yml, bundle clean)
- cleanup
IMPORTANT: Make sure you have looked at Prerequisites first
When just want to absolutely just run the integration tests
git clone https://github.com/ImperialLabs/slapi.git
cd slapi
export SLACK_TOKEN=xoxb-XXXXXXXXXXXX-TTTTTTTTTTTTTT
bundle install --binstubs --path vendor/bundle
bundle exec rake integration
Quick install/config Instructions for rbenv or rvm as there is a visual studio launch.json included that supports both for debugging
git clone https://github.com/rbenv/rbenv.git ~/.rbenv
git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
echo "gem: --no-document" > ~/.gemrc #(optional)
cat >> '~/.bashrc' << 'EOF'
if [ -d "~/.rbenv" ]; then
export PATH="$HOME/.rbenv/bin:$PATH"
fi
EOF
cat >> '~/.bashrc' << 'EOF'
rbenv ()
{
local command;
command="$1";
if [ "$#" -gt 0 ]; then
shift;
fi;
case "$command" in
rehash | shell)
eval "$(rbenv "sh-$command" "$@")"
;;
*)
command rbenv "$command" "$@"
;;
esac
}
EOF
cat >> '~/.bashrc' << 'EOF'
eval "$(rbenv init -)"
EOF
Install whatever version you wish as long as it's greater than 2.3
rbenv install 2.3.3
rbenv global 2.3.3
You will need to install bundler on the default gemset (even if you work on another gemset) to not have to change the launch.json for VSCode.
So for whatever ruby you are working on:
rvm gemset use default
gem install bundler
The reason for this is so that the "pathToBundler": "${env.HOME}/.rvm/gems/${env.rvm_ruby_string}/wrappers/bundle"
does not need to change as you switch rubies.
At the time of this writing, since this is using beta versions of the debugger and has many latest libraries that are interdependent, you may have to run:
gem update —system
rm -rf vendor/bundle
bundle install --binstubs --path vendor/bundle
To get the latest RubyGems.
There are currently rspec integration tests using capybara. These could use more help.
To run this tests simply:
rspec
Since these are integration tests they will cause messages to be posted in a channel at imperiallabs.slack.com.
imperiallabs.slack.com is currently a free Slack team that you would need an invite to join.
Ensure you have followed all the tasks in Bundler Section
To run all tests in Visual Studio Code use the RSpec - all
configuration.
Select Sinatra-rbenv
or Sinatra-rvm
in VS Code depending on your setup to do standard debugging.
Or use a plugin in your favorite editor.
If Making changes to the Dockerfile and/or container itself build your changes by running:
docker build --tag=slapi_local ./
Run with SLAPI using localhost Docker for Plugins
To run the docker container: NOTE: This will only work on Linux or OSX Based Hosts
To run the docker container:
docker run -d -p 4567:4567 -v /var/run/docker.sock:/var/run/docker.sock --name slapi_local slapi_local
This setup should work on all Operating Systems supported by Docker
Utilizes the image built previously, this is probably the option you want to use for windows. There has been issues getting docker-compose to build images on windows, so utilize the build option under Remote Testing header.
docker-compose -f slapi-dev-prebuilt-compose.yml up
Build SLAPI container/image from scratch w/ compose.
docker-compose -f slapi-dev-compose.yml up
The debuggers run on port 1234, so just connect to 127.0.0.1:1234
If you are using VS Code, you can select the Attach to Docker
profile in the debugger.
Rubocop is being used. Try to keep the lint clean by either addressing the issues or updating the .rubocop.yml.
To run rubocop either run:
rubocop
- Fork the repo on GitHub
- Clone the project to your own machine
- Commit changes to your own branch
- Push your work back up to your fork
- Submit a Pull Request so that we can review your changes
NOTE: Be sure to merge the latest from "upstream" before making a pull request!
- Clone the project to your own machine
- Create a new branch from master
- Commit changes to your own branch
- Push your work back up to your branch
- Submit a Pull Request so the changes can be reviewed
NOTE: Be sure to merge the latest from "upstream" before making a pull request!