Setup Instructions

Setup Instructions

This is a more in-depth guide on how to set up your Python environment for the Discord bots hosted here. The guide will cover installing Python, installing dependencies via pip, how to create keys on Discord, and optionally, using the Racket supervisor package superv to host multiple bots at a time.

Installing Python

Python can be installed any number of ways:

• Windows users: grabbing the installer file from Python.org
• Linux users: grabbing the source from Python.org, compiling from scratch, or deferring the work to your package manager (this project uses Python 3.6 currently, so your package manager may use a much older, more stable version)

Windows users can also look towards using the Anaconda Python suite which comes with an array of libraries and other tools for Python. This will set up the PATH variable on your Windows environment.

Cloning discord-bots and Installing Dependencies

To get the source code, you must clone the repository or download the code as a ZIP file and extract it's contents into a directory. Make sure you have Git installed to clone the repository.

git clone https://github.com/sleibrock/discord-bots
cd discord-bots

Now before we can run the bots, you need to install the dependencies from the requirements.txt file at the root of the project. This can be done manually via pip, or you can use make setup.

pip install -r requirements.txt # manual
make setup # must have GNU/Make installed for this

If you don't want to install these dependencies globally, you can use virtualenv to create a virtual Python package environment and install packages through that. This step is relatively easy on both Windows and Linux.

pip install virtualenv
virtualenv dev
source dev/bin/activate # dev/Scripts/activate.bat on Windows
make setup

To use packages inside the virtual environment you have to execute the activation script. Virtual environments can be exited with deactivate. The benefit to virtual environments is that you don't need root access to install packages, and deleting packages is as easy as deleting the entire virtualenv you created.

Setting Up Discord Bot Accounts and Access Tokens

Discord has a developer program that allows you to create applications to use on Discord servers. These are called Discord Bot accounts, and are different from user accounts in a few minor ways, one being that they don't need normal login credentials like e-mail and password, and instead rely upon access tokens that the user must set up.

To do this, you must go to the Developer portal for Discord and create new applications under your account. From there, you can convert applications into Bot accounts, where you can then create tokens for bots. To use this token, we store it as files in our project directory. Create a keys folder and place these tokens stored as plaintext in files with a name like yourbottoken.key. If you create a bot named yourbottoken, he will load this file automatically from the keys/ folder.

The fastest way to save these files is to copy/paste the token into your terminal and save the string to a file.

echo <your access token text goes here> > keys/bot.key

If you create a new bot application and create a key file called dumb-bot.key, you are now ready to run the Dumb Bot.

python bots/dumb-bot.py

Setting Up the Supervisor (optional)

discord-bots uses a third-party package I wrote in Racket called superv. A Python version of superv was planned but scrapped since the Racket implementation was easier to execute and design. This is entirely optional if you do not want to run multiple bots at the same time and have them be supervised, but if you wish to have your bots occasionally restarted and supervised for when they crash, the superv program can be handy to utilize.

First install Racket and make sure your Racket is at least version 6.7. Racket can be installed via your package manager (Linux), compiled from source, or the installer can be grabbed from Racket's website.

superv can be installed from Racket's internal tool raco. It can be installed one of two ways:

raco pkg install superv
make setup # Make based installer

The make setup defined includes installing Python packages as well. So if you have both Python and Racket installed, running make setup will do the setup work for you.

The superv project requires a config.json format in order to run programs. If you created a bot named silly-bot.py and have a key in the keys/ folder, you can create a JSON file that looks like:

{
	"programs": [
		{
			"name": "Silly Bot",
			"program": "python",
			"args": [
				"bots/silly-bot.py"
			]
		}
	]
}

The idea is that we have a list of "processes" to run with a varied list of arguments. The arguments get suplied to each individual process, and the processes are monitored under the superv program. Additional arguments can be configured to determine the number of sleep cycles, sleep delay times and other variables, but you can check out the superv Github for more info on superv. Feel free to look at the config.json at the root of the project to see what parameters used here.

Hosting on Linux with GNU Screen

Depending on how you're hosting, you might want to host it on hardware that isn't your main desktop, such as a remote server. This allows your bots to run without fear of being interrupted by your desktop activities like rebooting or memory leaks.

The tool screen provides a way of multiplexing shell sessions into one window that you can disconnect from. Disconnecting from the screen does not interfere with the processes running, and you can reconnect to the screen to monitor the programs as you see fit.

So once you log in to your server, you can start up a new screen session and boot into the discord-bots project as follows:

screen -S discord
cd discord-bots
make run

Once the bots are running, you can disconnect from the session with C-a-d and resume your normal activities. The bots will continue to run. To reconnect to the session, you can do that with screen -r discord.