InstallGuide

This guide is concerned with getting the latest rbot version up and running. For help migrating an existing instance of rbot to the latest version consider the migration guide.

Dependencies

Rbot and its built-in (but optional) plugins require the following external packages and libraries. Note that some of the ruby packages can either be installed using your systems package manager (like apt, zypper, ...) or using rubygems. If you are familiar with ruby software you might also want to use RVM, gemsets and/or bundler (a Gemfile is included in Rbot) to make the installation of ruby and other dependencies easier.

• Ruby, supported are versions 2.5 and up, see this ruby Table of versions.

Most modern Linux distributions should come equipped with ruby already. Debian ships ruby 2.5.1 since 10.3 (buster) to install it on debian:

sudo apt-get install ruby ruby-dev

• Tokyocabinet, technically there are other key value stores supported as well, but TC is recommended.

You'll need the system development package (in debian: libtokyocabinet-dev) of tokyocabinet, aswell as the rubygem (tokyocabinet). To install on a debian system:

sudo apt-get install libtokyocabinet-dev
# the rubygem further requires zlib and bz2 headers:
sudo apt-get install zlib1g-dev libbz2-dev
# system wide install of the ruby package:
sudo gem install tokyocabinet

• Mechanize

To install it system wide:

# the nokogiri dependency (automatically installed by gem) might [require](http://www.nokogiri.org/tutorials/installing_nokogiri.html) additional headers:
sudo apt-get install libxml2-dev libxslt1-dev
sudo gem install mechanize

• (Optional) For Twitter: oauth, oauth2 (sudo gem install oauth auth2)
• (Optional) For Shorturl: shorturl (sudo gem install shorturl)
• (Optional) For Time: tzinfo (sudo gem install tzinfo)

Getting Rbot

Right now there is no current release of rbot so the best way to get it is through git, checkout the ruby-rbot/rbot (master) repository on github. Using git you can download this repository locally and easily keep it up-to-date.

The current development version is pretty stable, solves lots of issues which are present in the last releases 0.9.15 and 0.9.10, also providing lots of new exciting features. Download a copy of the repository with

git clone https://github.com/ruby-rbot/rbot.git

To update your copy at a later date run

git pull

from the rbot directory.

If you are for some reason unable to use git directly you can also download a snapshot of the repository as a zip archive.

Running Rbot

To run rbot you can use the launch_here.rb ruby script. If you have used rvm or bundle to install dependencies you might need to run rvm <version> do ruby or bundle exec ruby instead of just ruby.

% ruby launch_here.rb --help
[...]
usage: rbot [options] [config directory]
  -h, --help         this message
  -v, --version      version information
  -d, --debug        enable debug messages
  -l, --loglevel     sets the log level verbosity
  -b, --background   background (daemonize) the bot
  -p, --pidfile      write the bot pid to file
config directory defaults to ~/.rbot

The config directory is the place RBot stores configuration, logfiles and other persistent files that are specific to a particular instance of rbot. You can run multiple instances of rbot simultaneously by running them in different config directories, if the config directory doesn't exist it is created and a configuration wizard is started.

The wizard is pretty self explanatory but I take you through it nonetheless. Just make sure to select "tc" as a database backend.

% ruby launch_here.rb ~/.rbot
[...]
Password for the bot owner
auth.password [d1CoW3vE]: 

Select a password for the owner user that is automatically created, think of it like an administrator or root account that you should keep private. Please note that owners can do pretty much anything like running shell commands by default.

List of irc servers rbot should try to connect to. Use comma to separate values. Servers are in format 'server.doma.in:port'. If port is not specified, default value (6667) is used.
server.list [irc://localhost]: irc://chat.freenode.net:7000

Specify the IRC server to connect to, in this case Freenode with port 7000 (SSL).

Use SSL to connect to this server?
server.ssl [false]: true

Enable SSL/TLS, make sure that you selected a SSL-enabled host/port of your irc network.

Verify the SSL connection?
server.ssl_verify [false]: true

Enables SSL/TLS verification.

The CA file used to verify the SSL connection.
server.ssl_ca_file [/etc/ssl/certs/ca-certificates.crt]: 

Path to your systems trusted CAs, or a file of your own.

Alternativly a directory that includes CA PEM files used to verify the SSL connection.
server.ssl_ca_path [/etc/ssl/certs]: 

(Optional) Directory with trusted CA files.

Where the bot should look for plugins. List multiple directories using commas to separate. Use '(default)' for default prepackaged plugins collection, '(default)/contrib' for prepackaged unsupported plugins collection
plugins.path [(default), (default)/games, (default)/contrib]: 

Plugins are single ruby (.rb) files that are loaded upon starting or rescanning (!rescan reloads all plugins) from the directories configured here. (default) equals ~/rbot/data/rbot/plugins and contains all plugins rbot ships with.

You might want to create a separate directory for your own plugins or third-party ones. In which case its best to add it later on using <user> config add /home/user/my-rbot-plugins to plugins.path.

DB adaptor to use for storing the plugin data/registries. Options: daybreak, dbm, tc
core.db [tc]: 
configured core.db => tc

Select the database adapter, used for persistent storage. It is strongly recommended that you use tc, for more information about the different supported storage adapters read the migration guide.

After that the bot should startup and connect to the IRC network. You can change any configuration by editing ~/.rbot/conf.yaml manually (if the bot is not running or not connecting) or use the config command to change while running.