install-docs

Installation instructions

Welcome to the installation instructions for pajbot!

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

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

Table of Contents generated with DocToc

• Service installation
  • Install system dependencies
  • Set up a system user
  • Install pajbot
  • Install and set up the database server
  • Install Redis
  • Install nginx
  • Install system services
• Single bot setup
  • Create an application with Twitch
  • Create a database schema
  • Create a configuration file
  • Set up the website with nginx
  • Enable and start the service
  • Authenticate the bot
  • Further steps

Service installation

Please note we currently only document how to run pajbot 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

Pajbot 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 git

Now, double-check that you have Python 3.9 or newer installed:

python3 --version

If your system Python version is not 3.9 or above, you must install pyenv following the instructions below.

Installing pyenv

Install the required dependencies to build Python (instructions from here)

sudo apt update
sudo apt install build-essential libssl-dev zlib1g-dev \
libbz2-dev libreadline-dev libsqlite3-dev curl \
libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev

Install pyenv on your system (instructions from here, there are other alternative methods of installations avilable if you want)

curl https://pyenv.run | bash

Set up your bash shell environment for Pyenv (instructions from here)

echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc

Then restart your shell.

Set up a system user

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

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

Install pajbot

Download the latest stable version of pajbot:

sudo -u pajbot git clone https://github.com/pajbot/pajbot.git /opt/pajbot --branch stable

Install pajbot's dependencies like this:

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

If you wanted to use your system version of Python, run the command like this instead:

cd /opt/pajbot
sudo -H -u pajbot SKIP_PYENV=1 ./scripts/venvinstall.sh

Install and set up the database server

pajbot 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 pajbot to use the PostgreSQL database server:

sudo -u postgres createuser pajbot

Note: We have not set a password for pajbot, and this is intentional. Because we created a system user with the name pajbot earlier, applications running under the pajbot system user will be able to log into the database server as the pajbot 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 pajbot 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 pajbot, owned by the pajbot database user:

sudo -u postgres createdb --owner=pajbot pajbot

Install Redis

Pajbot 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 pajbot with the help of systemd. Systemd will take care of:

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

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

sudo cp /opt/pajbot/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 pajbot to (and how to) run in a certain channel. Pajbot running in a single channel, and with its website for that channel, is called an instance of pajbot 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 pajbot.

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 (pajbot, 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 pajbot psql pajbot -c "CREATE SCHEMA pajbot1_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 pajbot cp /opt/pajbot/configs/example.ini /opt/pajbot/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 pajbot editor /opt/pajbot/configs/streamer_name.ini

Set up the website with nginx

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

sudo cp /opt/pajbot/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) pajbot, run:

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

Authenticate the bot

One last step: You need to give your pajbot 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.

The bot will then automatically come online in chat within about 2-3 seconds of you completing the login process.

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 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. The bot will also then be able to change the game and title with the !settitle and !setgame commands. Alternatively the streamer could give the bot the editor permission, this will also allow the bot to change the game and title from chat.

• Add some basic commands:

  Here's some ideas:

  !add command ping --reply $(tb:bot_name) $(tb:version_brief) online for $(tb:bot_uptime)
  !add command commands|help --reply $(tb:bot_name) commands available here: https://$(tb:bot_domain)/commands
  !add command ecount --reply $(1) has been used $(ecount;1) times.
  !add command epm --reply $(1) is currently being used $(epm;1) times per minute.
  !add command uptime|downtime --reply $(broadcaster:name) has been $(tb:stream_status) for $(tb:status_length)
  !add command points|p --reply $(usersource;1:name) has $(usersource;1:points|number_format) points
  !add command lastseen --reply $(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 $(1) per minute record is $(epmrecord;1).
  !add command profile --reply https://$(tb:bot_domain)/user/$(usersource;1:login)
  !add command overlay|clr --reply https://$(tb:bot_domain)/clr/overlay/12345
  !add command playsounds --reply available playsounds are listed here: https://$(tb:bot_domain)/playsounds
  !add command title --reply Current stream title: $(stream:title)
  !add command game --reply Current stream game: $(stream:game)
  !add command timeonline|watchtime --reply $(usersource;1:name) has spent $(usersource;1:minutes_in_chat_online|time_since_minutes) in online chat.
  !add command timeoffline --reply $(usersource;1:name) has spent $(usersource;1:minutes_in_chat_offline|time_since_minutes) in offline chat.
  

• Advanced command arguments can be found here.