* betabot has joined #teatime
<gyng> ~ping
<betabot> pong
<gyng> betabot: remind me about tea in 10 seconds
<betabot> Reminder in 0.0h set for 1970-01-01 00:00:10 UTC (UTC).
<betabot> ๐ -0.0h gyng > gyng: tea
<gyng> ~install https://plugin.example.com/my_plugin/manifest.json save
<betabot> ๐ Plugin pong installed.
<gyng> ~pong
<betabot> peng
betabot is a bot that aims to be protocol agnostic, easy to deploy and simple to develop for.
Features network adapters and plugin framework goodies (database ORM, web hooks, settings, install).
Has full IRC and basic Slack, Discord, and Matrix (unencrypted) support. Some useful plugins are also included. Not all included plugins support Slack, Discord, or Matrix right now.
You can choose either to use or not to use Docker to run betabot.
-
Download or clone this repository
git clone https://github.com/gyng/betabot.git
-
Requirements: Docker, Docker Compose V2
-
Use the prebuilt image, or
-
Build the image from source. You might need to configure the ports used by the webserver and plugins.
docker build . -t betabot
-
Create an admin account (auth level 5) with the wizard
docker-compose run --entrypoint sh bot rake make_user # or with the command docker-compose run --entrypoint sh bot rake make_user_cmd[name,password,auth_level]
-
Start the bot
docker-compose up # or in detached mode docker-compose up -d
-
Install external plugins if wanted
# for example, as an admin ~login user pass ~install https://raw.githubusercontent.com/gyng/betabot-example-plugin/master/manifest.json
-
See commands
# For plugins ~help # For core triggers (admin) ~help core
Settings, accounts, databases, and the public directory are persisted with usage of Docker. The image needs to be rebuilt (easily with docker-compose up --build -d
) when adapters or plugins are changed or added. As of now, the port mappings in docker-compose.yml
must be changed manually when not using default ports.
This launches betabot in docker dev mode: the entire directory is mounted in an alpine container, and the bot is started. Note: restart: always
is enabled, so you need to kill it to stop it.
CURRENT_UID=$(id -u):$(id -g) docker-compose -f docker-compose.dev.yml up --build
CURRENT_UID=$(id -u):$(id -g) docker-compose -f docker-compose.dev.yml up --build --detach
or run the script which runs docker-dev in detached mode
./docker-dev.sh
logs can be followed with docker log -f
, and the ID can be found using docker ps
.
-
Requirements: Ruby version >= 3.1.2, Bundler.
-
Install the gems with Bundler. You might need
sqlite-dev
andimagemagick
packages installed on your system for gem installation.bundle install # or bundle install --path vendor
-
Create an admin account (auth level 5) with the wizard
rake make_user
or the command
rake make_user_cmd[name,password,auth_level]
-
Start the bot
ruby start_bot.rb
For bot settings, betabot will read from bot_settings.user.json
. This file will be automatically created on startup if it does not exist. bot_settings.user.json
is ignored in .gitignore
, which makes it easier to update betabot using git.
cd lib/settings
cp bot_settings.default.json bot_settings.user.json
Settings files that may need changing:
./lib/settings/bot_settings.user.json
(for web server configuration options check below)./lib/settings/adapters/irc.json
(and any per-adapter settings)./lib/settings/adapters/slack.json
(and any per-adapter settings)./lib/settings/adapters/discord.json
(and any per-adapter settings)- (Optional) any plugin settings in
./lib/settings/plugins/
Add the adapters to be run on startup to the autostart key in bot_settings.user.json
. Currently supported adapters are slack
and irc
.
Note that adapter and plugin settings files are generated with default settings on first run for a fresh install as of now. They do not exist before first run.
If using Discord, you will need to invite your bot instance to your server. Use the permissions generator and insert your client ID.
An app can be created at the Discord developer dashboard. api_token
refers to the app bot user's token.
enabled
โ whether the webserver runs on startuplink_url
โ the URL for plugins to use (eg. http://lollipop.hiphop:9999 or http://www.example.org)host
โ the listening host; leave this at0.0.0.0
and it should workport
โ your listening port
Run bot with BETABOT_SSL_NO_VERIFY=1
.
BETABOT_SSL_NO_VERIFY=1 ruby start_bot.rb
BotNickname: command arg1 arg2
or (trigger_shorthand)command arg1 arg2
For example: !ping
, MyBot: ping
- image โ Saves all image links and records data about them in a database. Images are saved in
./public/i
. The image plugin also gives a random image link from the image database if the web server is running. - entitle โ Echos titles of uninformative URLs.
- entitleri โ Uses imginfer search to guess the contents of image URLs.
- shipment โ Tracks packages using Aftership requires setup of API keys
- mpcsync โ Synchronizes playing of video files in MPC. Requires configuration of MPC addresses.
- script/macro โ Script/Macro definition support.
- showtime โ Checks Anilist for anime airing times requires setup of API keys
- unicode โ Search for Unicode characters or emoji by description, and identify Unicode characters
- wolfram โ Queries Wolfram|Alpha. requires setup of API keys
For all plugins, see the plugins and external_plugins directory.
Use ~help core
for help with core commands.
- help
- help [plugin]
- help core
- install [external_plugin_manifest_json_url]
- install [external_plugin_manifest_json_url] save
- update [external_plugin_name]
- update [external_plugin_name] save
- remove [external_plugin_name]
- remove [external_plugin_name] save
- plugin_check_list
- reset_plugin [plugin_name]
- blacklist
- blacklist_adapter [name]
- blacklist_plugin [name]
- blacklist_user [name regex]
- blacklist_content [name regex]
- unblacklist_adapter [name]
- unblacklist_plugin [name]
- unblacklist_user [name regex]
- unblacklist_content [name regex]
- login [nick] [pass]
- logout
- reload # (reloads plugins)
- restart
- shutdown
- useradd [accountname] [password] [authlevel 0-5]
- version
Auth level 4 needed.
- reconnect
- disconnect
- join [channel]
- part [channel]
- nick [nick]
- defaultchan-add [server] [channel]
- defaultchan-rm [server] [channel]
- defaultchan-ls
As an admin account (auth >= 5):
~install <manifest_url>
~install <manifest_url> save
~update <plugin_name>
~remove <plugin_name>
~remove <plugin_name> save
~plugin_check_list
If save
is supplied, the plugin will be added to the list of plugins to be checked for installation/updates on startup. These settings are saved to bot_settings.user.json
.
The plugin might require dependencies. If so, run bundle install
and restart the bot.
rake install_plugin[$MANIFEST_URL]
rake update_plugin[$PLUGIN_NAME]
rake remove_plugin[$PLUGIN_NAME]
These commands do not provide options to update bot_settings.user.json
and are therefore not recommended.
See: Plugin development
Docker: `docker-compose -f docker-compose.test.yml up --build
Tests can be run with bundle exec rspec
. Current test coverage is very limited. Rubocop can be run with bundle exec rubocop
.
The EventMachine reactor has to be set up and torn down for most specs so there is a helper method with_em(&block)
included in spec_helper.rb
.
Tests for plugins are to be placed inside a spec
directory in the plugin directory. See the ping plugin for an example.
The project is linted with Rubocop, and will fail CI if any violations are found.
betabot is licensed under the MIT License.