RocketChat/botswana-snap

Name: botswana-snap

Owner: Rocket.Chat

Description: BOTSwana : The Kalahari of bots. Run any bot on any chat, painlessly!

Created: 2017-01-30 20:58:11.0

Updated: 2017-12-10 00:52:41.0

Pushed: 2017-09-10 04:29:36.0

Homepage:

Size: 56

Language: Shell

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

BOTSwana: the Kalahari of bots

Run as many bots as you want, with as many chats (Rocket.Chat, Slack, HipChat, and more…) as you want, painlessly!

BOTSwana enables you to develop, test, manage and run fleets of bots right on your Linux system.

You no longer have to struggle with installing complex bot runtime; or give up privacy and pay dearly for bot SaaS.

Leverage the connectivity, storage, and multi-core computing power of your Linux system to manage and run tens (or hundreds!) of bots simultaneously.

Unleash your personal Kalahari of Bots with BOTSwana TODAY !!

Installation

Until BOTSwana is officially registered at the snap store, download the latest snap file for your architecture and run:
sudo snap install botswana_x.x.x_arch.snap --dangerous

Authorizing users

Users must first be authorized to deploy and administer bots using BOTSwana. The root user can authorize other users by running:
sudo snap run botswana.authorize add 1000, replacing 1000 with the desired user ID.

To discover your regular user ID, simply run:
id

Sample output:
uid=1000(my_user) ...

Command reference for botswana.authorize

Usage: sudo snap run botswana.authorize <action> [uid]
Possible actions are:
add         - add uid to the list of authorized users
remove, rm  - remove uid from the list of authorized users
delete, del - same as remove
list        - list all users present in the list of authorized users
purge       - remove all uids from the list of authorized users
Note: only the 'list' and 'purge' actions may be used without a uid

Deploying bots

Interactively

Simply run snap run botswana.letloose and follow the prompts!

Automated deployment

For greater control over your bot, or to control it via scripts:

• Create a directory where to store the bot files; e.g.:
  mkdir /home/user/mybot
• Execute the following command, replacing /home/user/mybot with the directory you created:
  snap run botswana.deploy /home/user/mybot

Sample output:

Bot successfully deployed!
Edit, then execute the following file to configure and launch your bot:
/home/user/mybot/launch.sh

Finally, edit the launch.sh file to add the desired configuration, then execute it to run your bot as a background process.

Administering deployed bots

Listing active bots

To list all active bots, run:
snap run botswana.admin list

Queries

To find specific bots that may be active, boolean queries are available.

Available query parameters are:

• NAME
• ADAPTER

Available query connectors are:

• IS
• ISNT
• AND
• OR

Examples:

nd all active bots by the name "mybot":
 run botswana.admin list NAME IS mybot

nd all active bots by the name "mybot" and adapter "rocketchat":
 run botswana.admin list NAME IS mybot AND ADAPTER IS rocketchat

nd all active bots except ones whose adapter is "rocketchat":
 run botswana.admin list ADAPTER ISNT rocketchat

r more complex boolean queries, surround the entire query in quotes to allow the use of parentheses.
nd all active bots except ones named "mybot", unless their adapter is "rocketchat":
 run botswana.admin list "NAME ISNT mybot OR (NAME IS mybot AND ADAPTER IS rocketchat)"

Deactivating bots

To stop all active bots, run:
snap run botswana.admin stop

Please note

Bots deployed via snap run botswana.deploy cannot be stopped with this command.

Queries

To stop specific bots, boolean queries are available.

Available query parameters are:

• NAME
• ADAPTER

Available query connectors are:

• IS
• ISNT
• AND
• OR

Examples:

op all active bots by the name "mybot":
 run botswana.admin stop NAME IS mybot

op all active bots by the name "mybot" and adapter "rocketchat":
 run botswana.admin stop NAME IS mybot AND ADAPTER IS rocketchat

op all active bots except ones whose adapter is "rocketchat":
 run botswana.admin stop ADAPTER ISNT rocketchat

r more complex boolean queries, surround the entire query in quotes to allow the use of parentheses.
op all active bots except ones named "mybot", unless their adapter is "rocketchat":
 run botswana.admin stop "NAME ISNT mybot OR (NAME IS mybot AND ADAPTER IS rocketchat)"

Checking bot logs

To check the logs for a single bot, simply run:
snap run botswana.admin diag
This will show the logs of the first bot process found by BOTSwana.

If multiple bots are active, use precise queries to select the desired bot:

ew logs for bot named "mybot" whose adapter is "rocketchat":
 run botswana.admin diag NAME IS mybot AND ADAPTER IS rocketchat

Piping this command to less may be useful:
snap run botswana.admin diag | less

Command reference for botswana.admin

Usage: snap run botswana.admin <action> [bot_name or PID]
Possible actions are:
list [query] - if [query] is omitted, list all running bots;
               otherwise, list running bots filtered by [query].
diag [query] - If [query] is omitted, show the logs for the first active bot found;
               otherwise, show the logs for the first active bot found via [query].
stop [query] - if [query] is omitted, stop all running bots;
               otherwise, stop running bots filtered by [query].

Query parameters: NAME, ADAPTER
Query connectors: IS, ISNT, AND, OR
Query example: "NAME IS mybot AND ADAPTER IS rocketchat"

Adding scripts

Globally

Using snap run botswana.letloose gives you the ability to choose a scripts directory. E.g.:

Where are guy_chapman's behavior scripts located?
Must point to an existing directory within /home/user.
> /home/user/scripts

Therefore, every bot deployed which uses that directory for its scripts will load the same scripts therein contained.

Using snap run botswana.deploy gives you the same ability by specifying the scripts directory within the configuration section of launch.sh:

 desired, change to a directory where to look for additional scripts
scripts will still be utilized regardless of this setting
pts_dir="/home/user/scripts"

Individually

Using snap run botswana.letloose creates an accessible directory where only this particular bot will look for scripts.

To learn the location of that directory, run:
snap run botswana.admin list

Sample output:

mybot <<<
PID     - 12345
Adapter - rocketchat
URL     - https://mychat.com
Home    - /home/user/snap/botswana/common/mybot/aHR0cHM6Ly9teWNoYXQuY29t
Scripts - /home/user/scripts

Note the bot's Home directory:
[*] Home - /home/user/snap/botswana/common/mybot/aHR0cHM6Ly9teWNoYXQuY29t

That directory will contain a scripts directory where only this bot will look for scripts:
/home/user/snap/botswana/common/mybot/aHR0cHM6Ly9teWNoYXQuY29t/scripts

Using snap run botswana.deploy creates the bot directory at the specified location, such as:
snap run botswana.deploy /home/user/mybot

In that case, the individual scripts directory will simply be:
/home/user/mybot/scripts

Redis

BOTSwana automatically spawns a Redis server, by default only accessible locally, for quick and somewhat persistent storage for all bots.

Configuration

A sample configuration file is included and accessible at:
/var/snap/botswana/current/redis/redis.conf

To modify Redis' configuration, first stop the service by running:
sudo service snap.botswana.redis-server stop

Then, modify /var/snap/botswana/current/redis/redis.conf and start the service:
sudo service snap.botswana.redis-server start

Administration

To check the status of the embedded Redis server:
sudo service snap.botswana.redis-server status

To restart it:
sudo service snap.botswana.redis-server restart

To check its logs (assuming default configuration):
cat /var/snap/botswana/current/redis/redis.log