Skip to content

Latest commit

 

History

History
 
 

install-docs

README.md

Installation instructions

Welcome to the installation instructions for troybot!

Below is the index for a full list of installation instructions for troybot.

These installation instructions will install troybot in a way that allows you to run troybot for multiple streamers at once without too much duplication. For this reason, these installation instructions are split into two big parts: Installation of troybot, and creating a troybot instance for a single channel (which you can repeat as needed, should you want to run troybot in multiple channels, for different streamers for example).

Table of Contents generated with DocToc

Service installation

Please note we currently only document how to run troybot on GNU/Linux systems. The following instructions should work without any changes on Debian and Ubuntu. If you are running another distribution of GNU/Linux, you might have to make some changes to the commands, file locations, etc. below.

Install system dependencies

troybot is written in python, so we need to install some basic python packages:

sudo apt update
sudo apt install python3 python3-dev python3-pip python3-venv

We also need the following libraries and build tools:

sudo apt install libssl-dev libpq-dev build-essential

Set up a system user

For security reasons, you shouldn't run troybot as the root user on your server. You can create a low-privilege "system" user for troybot like this:

sudo adduser --system --group troybot --home /opt/troybot

Install troybot

Download the latest stable version of troybot:

sudo -u troybot git clone https://github.com/TroyDota/troybot.git /opt/troybot --branch master

Install troybot's dependencies like this:

cd /opt/troybot
sudo -H -u troybot ./scripts/venvinstall.sh

Install and set up the database server

troybot uses PostgreSQL as its database server. If you don't already have PostgreSQL running on your server, you can install it with:

sudo apt install postgresql

Now that you have PostgreSQL installed, we will create a user to allow troybot to use the PostgreSQL database server:

sudo -u postgres createuser troybot

Note: We have not set a password for troybot, and this is intentional. Because we created a system user with the name troybot earlier, applications running under the troybot system user will be able to log into the database server as the troybot database user automatically, without having to enter a password.

We have run createuser as postgres for the same reason: postgres is a pre-defined PostgreSQL database superuser, and by using sudo, we are executing createuser troybot as the postgres system (and database) user.

This is a default setting present on Debian-like systems, and is defined via the configuration file pg_hba.conf.

We will now create a database named troybot, owned by the troybot database user:

sudo -u postgres createdb --owner=troybot troybot

Install Redis

troybot also needs an instance of Redis to run. The redis database server does not need any manual setup - all you have to do is install redis:

sudo apt install redis-server

The redis server is automatically started after installation. You can verify your installation works like this:

redis-cli PING

You should get PONG as the response output. That means your redis server is working fine.

Install nginx

Nginx is a reverse proxy - it accepts all incoming HTTP requests to your server, and forwards the request to the correct backend service. It also applies encryption for HTTPS, can set headers, rewrite URLs, and so on.

All you need to do for this step is to install nginx:

sudo apt install nginx

We will configure nginx later.

Note: You can find a basic nginx configuration setup including HTTP -> HTTPS redirect, recommended SSL configuration parameters, etc. over here. If you don't already have a basic nginx setup, we strongly recommend you follow the linked guideline now.

Install system services

We recommend you run troybot with the help of systemd. Systemd will take care of:

  • starting and stopping troybot,
  • capturing and storing the output of the service as logs,
  • starting troybot automatically on system startup (and starting it in the correct order, after other services it needs),
  • restarting troybot on failure,
  • and running multiple instances if you run troybot for multiple streamers

To start using systemd for troybot, install the pre-packaged unit files like this:

sudo cp /opt/troybot/install-docs/*.service /etc/systemd/system/

Then tell systemd to reload changes:

sudo systemctl daemon-reload

Single bot setup

Now that you have the basics installed, we need to tell troybot to (and how to) run in a certain channel. troybot running in a single channel, and with its website for that channel, is called an instance of troybot from now on.

Create an application with Twitch

The first thing you need to do is to create an application for the bot instance. Registering an application gives you three important bits of data the bot needs to be able to access the Twitch API and allow users to log in to the website using their Twitch account: A client ID, The client secret, and the authentication redirect URI.

To create an application with Twitch, visit https://dev.twitch.tv/console/apps/create.

  • Under Name, enter the name you want users to see when they log into the website and have to confirm they want to grant you access to their account.
  • Under OAuth Redirect URL, enter the full URL users should be redirected to after they complete the log in procedure with Twitch. This should be https://pleb-domain.com/login/authorized (adjust domain name of course).
  • Under Category, you should pick Chat Bot, as it is the most appropriate option for troybot.

After you click "Create", you are given access to the Client ID. After clicking New Secret, you can also access your Client Secret. You will need these values in the next step - when you create the configuration file for your instance.

Create a database schema

Each instance's data lives in the same database (troybot, we created this earlier), but we separate the data by putting each instance into its own schema. To create a new schema for your instance, run:

sudo -u troybot psql troybot -c "CREATE SCHEMA troybot_streamername"

Remember the name of the schema you created! You'll need to enter it into the configuration file, which you will create and edit in the next step:

Create a configuration file

There is an example config file available for you to copy:

sudo -u troybot cp /opt/troybot/configs/example.ini /opt/troybot/configs/streamer_name.ini

The example config contains comments about what values you need to enter in what places. Edit the config with a text editor to adjust the values.

sudo -u troybot editor /opt/troybot/configs/streamer_name.ini

Set up the website with nginx

troybot comes with pre-set nginx configuration files you only need to copy and edit lightly to reflect your installation.

sudo cp /opt/troybot/install-docs/nginx-example.conf /etc/nginx/sites-available/streamer_name.your-domain.com.conf
sudo ln -s /etc/nginx/sites-available/streamer_name.your-domain.com.conf /etc/nginx/sites-enabled/

You have to then edit the file, at the very least you will have to insert the correct streamer name instead of the example streamer name.

The example configuration sets your website up over HTTPS, for which you need a certificate (ssl_certificate and ssl_certificate_key). There are many possible ways to get a certificate, which is why we can't offer a definitive guide that will work for everybody's setup. However, if you need help for this step, you can find a guide here if you have set up your domain with CloudFlare DNS.

Once you're done with your changes, test that the configuration has no errors:

sudo nginx -t

If this check is OK, you can now reload nginx:

sudo systemctl reload nginx

Enable and start the service

To start and enable (i.e. run it on boot) troybot, run:

sudo systemctl enable --now troybot@streamer_name troybot-web@streamer_name

Authenticate the bot

One last step: You need to give your troybot instance access to use your bot account! For this purpose, visit the URL https://streamer_name.your-domain.com/bot_login and complete the login procedure to authorize the bot.

Then, to finally make the bot come online in chat, run:

sudo systemctl restart troybot@streamer_name

Further steps

Congratulations! Your bot should be running by now, but there are some extra steps you may want to complete:

  • Ask the streamer to give your bot the editor permission. You can then use !settitle and !setgame commands to change title and game from chat.

  • Ask the streamer to log in once by going to https://streamer_name.your-domain.com/streamer_login - If the streamer does this, the bot will be able to fetch who's a subscriber and keep the database up-to-date regularly

  • Add some basic commands:

    Here's some ideas:

    !add command ping --reply @$(source:name), $(tb:bot_name) $(tb:version_brief) online for $(tb:bot_uptime)
!add command commands|help --reply @$(source:name), $(tb:bot_name) commands available here: https://$(tb:bot_domain)/commands
!add command ecount --reply @$(source:name), $(1) has been used $(ecount;1) times.
!add command epm --reply @$(source:name), $(1) is currently being used $(epm;1) times per minute.
!add command uptime|downtime --reply @$(source:name), $(tb:broadcaster) has been $(tb:stream_status) for $(tb:status_length)
!add command points|p --reply @$(source:name), $(usersource;1:name) has $(usersource;1:points|number_format) points
!add command lastseen --reply @$(source:name), $(user;1:name) was last seen $(user;1:last_seen|time_since_dt) ago, and last active $(user;1:last_active|time_since_dt) ago.
!add command epmrecord --reply @$(source:name), $(1) per minute record is $(epmrecord;1).
!add command profile --reply @$(source:name) https://$(tb:bot_domain)/user/$(usersource;1:username)
!add command playsounds --reply @$(source:name), available playsounds are listed here: https://$(tb:bot_domain)/playsounds