Skip to content

INSTALLATION.md

Latest commit

 

History

History
253 lines (168 loc) · 5.59 KB

INSTALLATION.md

File metadata and controls

253 lines (168 loc) · 5.59 KB

Installation Guide

This guide walks you through installing and setting up Bot Shock on your server.

Prerequisites

Before you begin, make sure you have:

  • Python 3.10 or higher (Python 3.11 to 3.13 recommended)
  • A Discord bot account with the necessary permissions
  • An OpenShock or PiShock account with API access
  • A Linux, Windows, or macOS computer or server

Step 1: Install Python

Linux (Ubuntu/Debian)

sudo apt update
sudo apt install python3.11 python3.11-pip python3.11-venv

macOS

brew install python@3.11

Windows

Download Python from python.org and run the installer. Make sure to check "Add Python to PATH" during installation.

Step 2: Download Bot Shock

If you have git installed:

git clone https://github.com/TastelessVoid/Bot-Shock
cd BotShock

Alternatively, download the ZIP file from GitHub, extract it, and navigate to the folder.

Step 3: Create a Virtual Environment

Using a virtual environment keeps the bot's dependencies separate from your system Python. This is recommended but not required.

python3 -m venv venv

Activate the virtual environment:

On Linux or macOS:

source venv/bin/activate

On Windows:

venv\Scripts\activate

Step 4: Install Bot Shock

Install the bot in development mode, which makes updating easier:

pip install -e .

Or install it normally:

pip install .

This installs Bot Shock along with all its dependencies, including disnake for Discord, aiohttp for API communication, python-dotenv for configuration, cryptography for securing API tokens, and aiosqlite for the database.

Step 5: Generate an Encryption Key

Bot Shock encrypts your OpenShock and PiShock API tokens before storing them in the database. Generate an encryption key with:

botshock-keygen

Save the output somewhere secure. You will need it in the next step.

Step 6: Create the Configuration File

Create a file named .env in the project directory:

touch .env

Open it in a text editor and add the following:

# Required
DISCORD_TOKEN=your_discord_bot_token_here
ENCRYPTION_KEY=your_generated_encryption_key_here

# Optional (uncomment to customize)
# DATABASE_PATH=botshock.db
# DATABASE_POOL_SIZE=5
# LOG_LEVEL=INFO
# LOG_DIR=logs
# API_BASE_URL=https://api.openshock.app
# API_TIMEOUT=10
# API_MAX_CONNECTIONS=100
# API_REQUESTS_PER_MINUTE=60

Getting Your Discord Bot Token

  1. Go to the Discord Developer Portal
  2. Click "New Application" and give it a name
  3. Go to the "Bot" section in the left sidebar
  4. Click "Reset Token" and copy the token
  5. Paste it into your .env file

Required Bot Permissions

Your bot needs these Discord permissions to work properly:

  • Send Messages
  • Embed Links
  • Read Message History
  • Use Slash Commands
  • Attach Files

The permission integer for these is 2147600384.

Inviting the Bot to Your Server

Use this URL template, replacing YOUR_CLIENT_ID with your bot's client ID from the Developer Portal:

https://discord.com/api/oauth2/authorize?client_id=YOUR_CLIENT_ID&permissions=2147600384&scope=bot%20applications.commands

Step 7: Start the Bot

botshock

You should see log messages indicating the bot is starting up and connecting to Discord.

Step 8: Verify Everything Works

In your Discord server, run the command:

/openshock setup

or

/pishock setup

If a registration form appears asking for your credentials, the bot is working correctly.

Troubleshooting Installation Issues

"DISCORD_TOKEN not found"

Make sure your .env file is in the same directory where you run the bot. Check for typos and ensure there are no extra spaces around the equals sign.

"ENCRYPTION_KEY not found"

Run botshock-keygen to generate a key and add it to your .env file.

Bot does not respond to commands

Make sure you invited the bot with the correct permissions, including the applications.commands scope. Discord may take a few minutes to register slash commands after the bot first connects.

Import errors

Make sure you installed the package with pip install -e . and that your virtual environment is activated.

Database errors

Check that the bot has write permissions in its directory. If the database file exists, make sure it is not locked by another process.

Updating Bot Shock

If you installed in development mode:

git pull

Then restart the bot. If dependencies have changed, run:

pip install --upgrade -e .

Running as a Background Service

Using systemd (Linux)

Create a file at /etc/systemd/system/botshock.service:

[Unit]
Description=Bot Shock Discord Bot
After=network.target

[Service]
Type=simple
User=your_username
WorkingDirectory=/path/to/BotShock
Environment="PATH=/path/to/BotShock/venv/bin"
ExecStart=/path/to/BotShock/venv/bin/botshock
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Then enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable botshock
sudo systemctl start botshock
sudo systemctl status botshock

Using screen (Simple Alternative)

screen -S botshock
cd /path/to/BotShock
source venv/bin/activate
botshock

Press Ctrl+A then D to detach from the session. Reattach later with screen -r botshock.

Next Steps