Setup Guide

Setup Guide

This guide will walk you through installing, configuring, and running JohnnyBot on your Discord server.

Navigation

• ← Back to Home
• Commands Reference →

Table of Contents

1. Prerequisites
2. Installation
3. Discord Bot Token Registration
4. Required Discord Permissions
5. Configuration
6. Running the Bot
7. Troubleshooting

Prerequisites

Before you begin, ensure you have:

• Python 3.7 or higher (tested up to Python 3.13)
• Git for cloning the repository
• A Discord server where you have administrative permissions
• Firewall access to allow inbound connections on TCP port 80 (for message archive hosting)

Installation

Step 1: Clone the Repository

git clone https://github.com/burbsec/johnnybot.git
cd johnnybot

Step 2: Install Dependencies

pip install -r requirements.txt

Note: Consider using a virtual environment to avoid conflicts with other Python packages:

python -m venv johnnybot-env
source johnnybot-env/bin/activate  # On Windows: johnnybot-env\Scripts\activate
pip install -r requirements.txt

Discord Bot Token Registration

Follow these steps to create a Discord bot and get your token:

Step 1: Create a Discord Application

1. Go to the Discord Developer Portal
2. Click "New Application"
3. Give your application a name (e.g., "JohnnyBot")
4. Click "Create"

Step 2: Create a Bot User

1. In your application, navigate to the "Bot" section in the left sidebar
2. Click "Add Bot"
3. Confirm by clicking "Yes, do it!"
4. Under the "Token" section, click "Copy" to copy your bot token
5. Keep this token secure - you'll need it to run the bot

Step 3: Generate Invite Link

1. Navigate to the "OAuth2" section in the left sidebar
2. Click on "URL Generator"
3. In "Scopes", select "bot" and "applications.commands"
4. In "Bot Permissions", select the permissions listed in the Required Discord Permissions section below
5. Copy the generated URL and open it in your browser
6. Select your Discord server and authorize the bot

Required Discord Permissions

JohnnyBot requires specific Discord permissions to function properly. When creating your bot application and generating an invite link, ensure these permissions are selected:

General Permissions

Permission	Required For
Manage Server	Server management features
Manage Roles	Role permission cloning and voice channel safety features
Manage Channels	Channel permission cloning and management
Kick Members	/kick command
Manage Nicknames	Voice channel safety (muting members)
Manage Events	Creating Discord events from calendar feeds
View Channels	Access and monitor channels
Moderate Members	/timeout command

Text Permissions

Permission	Required For
Send Messages	Bot responses and notifications
Manage Messages	Purge commands and protected channel enforcement
Read Message History	Message dump functionality and purge commands
Use Slash Commands	All slash command functionality
Embed Links	Rich embed messages (event notifications)
Attach Files	Log file attachments

Voice Permissions

Permission	Required For
Connect	Monitor voice channels for safety features
Mute Members	Voice channel chaperone functionality
Move Members	Voice channel management

Important Notes

• The bot does NOT require Administrator permissions
• Ensure the bot's role is positioned high enough in the role hierarchy to manage the roles and channels it needs to work with
• For permission cloning commands, the bot cannot clone permissions to/from roles higher than its own highest role

Configuration

Step 1: Configure Bot Settings

Open the config.py file in a text editor and modify the following constants according to your server's setup:

# Required Configuration
MODERATOR_ROLE_NAME = "Moderator"  # Name of the moderator role
PROTECTED_CHANNELS = ["announcements", "rules"]  # Read-only channels
MODERATORS_CHANNEL_NAME = "moderators"  # Channel for bot notifications

Configuration Options

Setting	Description	Example
MODERATOR_ROLE_NAME	Name of the moderator role. Necessary for mods to use bot commands	"Moderator"
PROTECTED_CHANNELS	List of channels you wish to force to read-only when Discord requires them not to be	["announcements", "rules"]
MODERATORS_CHANNEL_NAME	Name of the moderators chat channel for bot notifications	"moderators"
VOICE_CHAPERONE_ENABLED	Default state of the voice chaperone functionality	False
ADULT_ROLE_NAMES	Name of the role assigned to verified adults (used for voice chaperone)	['Dads', 'GrownUps']
CHILD_ROLE_NAMES	Name of the role assigned to children (used for voice chaperone)	['Kids', 'Bambinos', 'Girls']
HOST_IP	IP address of the interface to use for the /message_dump HTTP server	"172.116.0.73"
UPDATE_CHECKING_ENABLED	Default setting for bot to check for updates	True
UPDATE_CHECK_REPO_URL	Repo to check for updates	"https://github.com/BurbSec/JohnnyBot"

Step 2: Set Environment Variable

Add your Discord bot token to an OS environment variable called DISCORD_BOT_TOKEN:

On Linux/macOS:

export DISCORD_BOT_TOKEN="your_bot_token_here"

On Windows (Command Prompt):

set DISCORD_BOT_TOKEN=your_bot_token_here

On Windows (PowerShell):

$env:DISCORD_BOT_TOKEN="your_bot_token_here"

Security Note: For production use, consider using more secure methods like:

• System environment variables
• Docker secrets
• Cloud provider secret management services

Running the Bot

Step 1: Start the Bot

python bot.py

Step 2: Verify Operation

1. The bot should now show as online/active in your Discord server
2. Try using a simple command like /bot_mood to test functionality
3. Check the console output for any error messages

Running as a Service (Recommended)

For production use, consider running the bot as a system service that starts at boot:

Using systemd (Linux):

1. Create a service file:

sudo nano /etc/systemd/system/johnnybot.service

2. Add the following content:

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

[Service]
Type=simple
User=your_username
WorkingDirectory=/path/to/johnnybot
Environment=DISCORD_BOT_TOKEN=your_token_here
ExecStart=/usr/bin/python3 bot.py
Restart=always

[Install]
WantedBy=multi-user.target

3. Enable and start the service:

sudo systemctl enable johnnybot
sudo systemctl start johnnybot

Troubleshooting

Common Issues

Bot Not Responding

• Verify the bot token is correct and properly set as an environment variable
• Check that the bot has the required permissions in your Discord server
• Ensure the bot's role is positioned high enough in the role hierarchy
• Check the console output for error messages

Permission Errors

• Verify the bot has all required permissions listed above
• Check that the bot's role is above the roles it needs to manage
• Ensure the moderator role name in config.py matches your server's role

Commands Not Working

• Verify you have the moderator role (most commands are restricted)
• Check that slash commands are enabled in your server
• Try restarting the bot to refresh command registration

Message Archive Issues

• Ensure your firewall allows inbound connections on TCP port 80
• Check that the bot has "Read Message History" permission
• Verify the user and channel exist and are accessible

Getting Help

If you encounter issues:

1. Check the logs using the /log_tail command
2. Review the console output for error messages
3. Open an issue on the GitHub repository
4. Check existing issues for similar problems and solutions

Log Files

JohnnyBot creates rotating log files in the bot directory. Use the /log_tail command to get recent log entries sent to your DMs for troubleshooting.

---

Next Steps

Once your bot is running successfully:

1. Explore the Commands Reference to learn about all available commands
2. Configure reminders for your server's needs
3. Set up event feeds if you use external calendars
4. Test moderation commands in a safe environment

← Back to Home | Commands Reference →