-
Notifications
You must be signed in to change notification settings - Fork 1
Installing HedgeBot
So you've decided to install HedgeBot on your channel. That's great, but the install procedure isn't that simple, and it will require to follow some steps described below. Take your time to read that, as doing a mistake can be easily made.
Here is some general info about HedgeBot that is useful to know before beginning the installation of it. This bot is written in a programming language called PHP which has the particularity to be an interpreted script language. That means you don't get an executable program nice and ready to launch, but you get to download the bot's source code on your computer and then install an interpreter that understands this code to run it.
This is a little less convenient than a nice .exe to launch, but this solution allows the programming to be way more easier and flexible (that means you can upgrade and extend the bot more easily than if it was a compiled program).
Also, this means that we'll have to install the PHP interpreter before installing the bot, but this step is quite easy to do thankfully.
I recommend installing the bot on a Linux system, as it has been developed on one, and so it'll work best on it (especially regarding future features that may require non standard PHP extensions).
Before installing the bot, we need to install its interpreter, the PHP interpreter (that I'll call "PHP" from now on). But the instructions on how to do that aren't the same on Linux than on Windows. So refer to the good section to find the proper way to install PHP on your system.
Installing PHP on Linux is pretty simple for most cases : you just need to install it with your favorite package manager. You'll also need to install the PHP command line (PHP-CLI) to be able to launch the bot directly from the command line.
On Debian-based systems, it goes like this (the PHP runtime is installed as a dependency of PHP-CLI) :
apt-get install php7.0-cli
Note: If the package php7.0-cli isn't found, that could mean that your system only has PHP 5. You can then try installing the package php5-cli.
On Red Hat based systems, it looks like that (like Debian, the runtime is installed as a dependency) :
yum install php-cli
Note: If you don't have a package manager, you'll have to compile PHP yourself. But in that case, you probably know how to do that.
After doing that, you can test that your PHP is correctly installed by typing php -v in a console, it should give you something like this :
$ php -v
PHP 7.0.16-3 (cli) (built: Feb 22 2017 10:03:06) ( NTS )
Copyright (c) 1997-2017 The PHP Group
Zend Engine v3.0.0, Copyright (c) 1998-2017 Zend Technologies
with Zend OPcache v7.0.16-3, Copyright (c) 1999-2017, by Zend Technologies
Note: This part has been written using Windows 10 as example.
Installing HedgeBot on Windows is a bit more complicated. First you have to download manually the last version of PHP from the Windows binaries section from the PHP website. The minimal required version is 5.6, the recommended one is 7.0 or later because it's much faster. You can take the 32-bit or 64-bit variant as you want (Just remember you can't use the 64-bit version on a 32-bit Windows, but the opposite is possible). Take the non-thread safe version as we won't use threads here. Don't download the Debug Pack, just the Zip archive.
When PHP has been downloaded, extract it to a directory on your hard drive (for this tutorial, I will use C:\php\, I recommend you to do the same, and I don't recommend at all to install it on a removable media such as an USB drive). Then, go into the folder you extracted, and locate the file named php.ini-development, and rename it to just php.ini (if you can't see the extension, go into your View menu to enable them, or into Folder Options if you're on Windows 7) and open it with your favorite text editor.
Note: If you don't have a good text editor installed and you can only open it in MS Notepad, I strongly advise you to download an alternative, more powerful text editor (even more if you want to develop your own functions into the bot). A good free candidate for this is Notepad++.
In this file, search for the date.timezone setting, uncomment it (by removing the semicolon on the beginning of the line) and write as its value your nearest time zone (a list of timezones is available on the PHP Manual). Then, search for the extension_dir parameter, and uncomment the one that has the value "ext". Next, search for the line extension=php_sockets.dll, and uncomment it too. Now your PHP is configured.
The last step is to put it into your system PATH environment variable, which will allow us to launch PHP without the need to type in its complete path on the drive. To do that, go into Control Panel > System and Security > System > Advanced system settings (on the left links). Then go into "Environment variables..." and modify the Path system variable to add your PHP folder location (for this example, C:\php\) to the list, and apply the changes.
Now, test that PHP is correctly installed by opening a command line window and entering the command php -v, and you should have this showing :
C:\Users\user>php -v
PHP 7.0.5 (cli) (built: Mar 30 2016 10:15:34) ( NTS )
Copyright (c) 1997-2016 The PHP Group
Zend Engine v3.0.0, Copyright (c) 1998-2016 Zend Technologies
Note: If when executing the command there is a window opening saying that "VCREDISTXX.dll" isn't installed, you'll need to install Microsoft Visual C++ Redistributable pack. Refer to the left of the PHP Downloads page for more instructions.
Now that we have installed PHP, we can go to the next step : install HedgeBot. For that, you'll need to download the current source code to your computer. To do this, go to this link (this is the link available on the "Download ZIP" button on the project's home GitHub page), or better, if you know how to use a Git client, just clone the project in whatever folder you want to.
Once it is downloaded (and if you downloaded the archive), extract the archive into a folder, and name this folder conveniently (for example, "HedgeBot", that's how i'll reference this folder from now on).
Go into the bot's folder and then go into the "conf" folder. Here you'll see a "config.ini.sample" file, copy that and rename it as "config.ini", and open it in your favorite text editor.
Before going into editing, here is some info on how this configuration file works. This configuration file is written in the INI format, which is like the one PHP uses. It's a very simple format, where basically you have settings in the form of "<setting name> = <setting value>". String values are surrounded by double quotes and comments are prefixed by a semicolon. Also, settings are divided in sections, which are enclosed in square brackets, for example [general]. An addition to the original INI format, an improvement has been made to the sections by using periods in sections names to be able to have multiple nested levels of settings. Now that we've got this going, let's start configuring.
When opening the file, you'll be confronted with something like this :
[storage.config]
type = file
basepath = conf
backups = true
[storage.data]
type = json
path = datafile.json
backups = false
[general]
verbosity = 1
pluginsDirectory = Plugins
plugins = Currency
[tikal]
enabled = true
address = 127.0.0.1
port = 8081
token =
tokenless = false
[twitch.auth]
clientId =
clientSecret =
[servers.twitch]
address = irc.twitch.tv
port = 6667
name =
channels =
password =
[plugin.Currency]
currencyName = HedgebotCoin
currencyNamePlural = HedgebotCoins
statusCommand = money
statusMessage = Hey @name, you have @total @currency !
initialAmount = 100
[plugin.Twitter]
consumerApiKey=
consumerSecretKey=
oauthCallbackUrl=
deleteSentTweets=false
resetSentDelay=3600
You can clearly see the 6 main sections and 2 plugin sections defined in this configuration file.
-
[storage.config]and[storage.data]sections It defines how configuration and persistent data (which need to be kept between bot restarts) is stored. There will be a dedicated page to explain how the storage system works. For this first setup, we will keep the default provided configuration. It saves the settings on files located in the "conf" folder, relative to the folder where you start the bot from, and it saves the data in memory, so all data will be erased when you restart the bot (but it's good for testing, you can go to file storage afterwards when you're ready to go live).
Note: You'll see when you will start the bot that it will rewrite all the configuration into separated files and folders. This is to allow better separation of configuration sections. You can disable this rewriting by appending the configuration setting
readonly = trueinto the confiug storage section. But this will prevent the bot from creating the default settings for each plugin you choose to enable. You could still copy them from the plugins' definition INI file, but it's easier to let the bot do this by itself.
-
[general]section
It defines general settings about the bot. First you have the verbosity, which allows to set how many messages the bot will show about its status on the console. Basically, 1 and zero shows only important messages, while 2 and over will enable the verbose mode, thus showing all the messages exchanged between the bot and the server(s), along with additionnal debug messages for various events occuring on the bot.
Next variable is pluginsDirectory, and it allows you to set the directory from which the plugins will be loaded. It's better to keep it at default if you don't plan to have multiple plugin versions running between multiple bot instances or other complicated things like that.
The last parameter for this section is the plugins parameter, which is the main parameter you'll use in this section. It allows you to set what plugins the bot will load. Just enter the plugins you want to be loaded as a comma-separated list for this parameter (you can use spaces after the commas if you want to be clearer). To get the names of the plugins that can be loaded, you just have to go into the plugins directory, and check the folder names. Each folder represents a plugin, and the folder's name is what you have to use.
-
[tikal]section
Tikal is an HTTP server and an API JSON server. It provide an API to interact with HedgeBot. Hedgebot-admin use this API to control this bot. Basically, you can enable or disable it, change its address and port to call it and use a token system to enhance connections security.
-
[twitch.auth]section
This section define client id and secret to connect HedgeBot to Twitch API (diffent than interact with Twitch chat, see below). It is used for a lot of things : get channels status and data, use Twitch admin channel features, ... To have your own clientId and secret, you must generate it by following those instructions.
-
[servers.twitch]section
It is divided in subsections, one for each server the bot will connect to. One sub-section has been put for example, pre-configured for Twitch's IRC servers (which are used to interact with Twitch chat). On server settings section, you have basically 5 parameters :
address : This is the address of the IRC server your bot will connect to. Usually it uses a domain starting with "irc.".
port : The port of the address the bot will connect to. Usually for IRC, this port ranges from 6667 to 6669, with 6667 being the default.
name : This is the name the bot will use on this server. It's not automatically the name/login of your Twitch account, it depends how you want to use it. But it's an required field for IRC Protocol.
channels : This is the channel list the bot will connect to at launch, separated by commas, like the plugin list. Like for the plugins list, you can use spaces after the commas to be more clear.
password : This will be the OAuth token the bot will use to connect to the server. You can get this token by going onto the Twitchapps TMI tool and generating a new token by logging in. The token is the string that begins with "oauth:".
To finish, don't forget to install dependencies with Composer :
composer install
@TODO
@see Mercure Hub install and Mercure Hub config
Now, if you entered everything correctly (minimal settings to enter to allow it to start from the sample config is name, channels and password for the Twitch server), your bot should be ready to start. To start it, open a console (Command Prompt under Windows), go into the bot's folder, and run this command :
php console bot:start
If everything goes correctly, there should be some messages showing into the console :
$ php console bot:start
04/11/2016 12:23:48 AM -- Notice -- Starting HedgeBot...
04/11/2016 12:23:48 AM -- Notice -- Bootstrapping storage...
04/11/2016 12:23:48 AM -- Notice -- Loading main storages...
04/11/2016 12:23:48 AM -- Notice -- Loading plugins...
04/11/2016 12:23:48 AM -- Notice -- Loading plugins : Currency
04/11/2016 12:23:48 AM -- Notice -- Loading plugin Currency
04/11/2016 12:23:48 AM -- Notice -- Autoloading events for Currency...
04/11/2016 12:23:48 AM -- Notice -- Loaded plugin Currency
04/11/2016 12:23:48 AM -- Notice -- Loading servers...
04/11/2016 12:23:48 AM -- Notice -- Loading server twitch
04/11/2016 12:23:48 AM -- Notice -- Loaded servers.
Now you can test that your bot is correctly launched by going into the channel you plugged it to, and trying to execute a command. For the sample configuration provided, the only activated plugin is the Currency plugin, so one available command is the !coins command, which is the default one set to get the amount of money you have. If your bot replies, then well done, your bot is configured !
If the output seems incorrect to you and testing a command on the channel doesn't give a result, you should try to read carefully this tutorial again and check there isn't any mistakes in what you have done, and if there isn't any, feel free to report it on the issues page.
If you want to launch HedgeBot like a Linux service, we recommand you to use systemd. The bot can work with it if you create your own service.
It can be useful if your server crashed and relaunched automatically, relaunching defined services too, for example.
Here a simple configured service :
[Unit]
Description=Hedgebot, PHP Twitch bot
Wants=network-online.target
After=network-online.target
StartLimitIntervalSec=0
[Service]
Type=simple
Restart=on-failure
RestartSec=1
User=allowed_user
WorkingDirectory=/absolute/path/to/HedgeBot
ExecStart=/usr/bin/env php /absolute/path/to/HedgeBot/console bot:start
[Install]
WantedBy=multi-user.target
WantedBy=network-online.target
Recent systemd versions can use relative paths but some Linux-based OS didn't use those recent systemd versions (soon, we hope ...). So, with absolute path, it will work for old and recent systemd versions.