Skip to content

Getting Started

Jump to bottom
Matts edited this page Sep 4, 2022 · 5 revisions

Contents

  1. Discord Developer Portal
  2. Configure the bot .env
  3. Configure the RoleBot menu.json
  4. Running the bot in Docker
  5. Running the bot in Kubernetes
  6. Running the bot locally
  7. Build from source

Discord Developer Portal

One of the first steps to do before you even get started:

  • Login to the Discord Developer Portal.
  • Create an Application.
  • Inside the Application, create a Bot.
  • Save the token.
  • Give your bot a name and profile picture.
  • This bot will require all Privileged Gateway Intents, activate all three:
    • Presence
    • Server Members
    • Message Content
  • Go to the OAuth2 -> URL Generator.
  • Check the box for scopes: bot.
  • Check boxes for the following Bot Permissions:
    • Manage Roles (used by AutoRole and SelfRole)
    • Manage Channels (used by Commands, AutoScale and SelfRole)
    • Read Messages/View Channels (used by Commands and SelfRole)
    • Moderate Members (used by AutoRole and SelfRole)
    • Send Messages (used by Commands)
    • Manage Messages (used by Commands)
    • Embed Links (used by Commands)
    • Attach Files (used by Commands)
    • Read Message History (used by Commands)
    • Mention Everyone (used by Commands, Optional)
  • Copy the Generated URL
  • Go to the URL and assign the bot to your Discord Server.

The endpoint for the bot should now show up in your Discord server as offline.

Configure the bot .env

This bot's configuration is .ENV based. That means every setting is to be configured through environment variables. Doing this enables having a single container image for every installation in the world as the settings are injected from the outside.

Please note, there are two locations that this bot can look at for its configuration. This however, depends on what type of deployment you have chosen.

  1. For Docker: Place the .env file in the top level, next to the docker-compose.yml and Dockerfile. So that's ./.env.
  2. If running the bot locally: Place the .env file in the bot's data folder. So that's ./clanbotjas/data/.env.

An example .env

# General Bot settings
# BOT Login Token
BOT_TOKEN = NjY1OTAyNzgxxjQ0MqQzOTg4.G-LXwZ.ih6o6tU98nFNnFgKX4XxF5j9g9CiTjFG1vbIuE
# ID of your Discord Server/Guild
GUILD_ID = 765804631873189936
# ID of the text channel where the bot sends logs
LOG_CHANNEL = 976204250007162414


# User permission settings
# ID for the role required to execute slash commands (full permissions)
COMMAND_PERMISSION_ROLE = 967855625404444589


# Voice Auto Scaler settings
# Enable or Disable Voice Auto Scaler, true/false
VOICE_SCALER_ENABLE = true
# ID of the category to auto scale voice channels in
VOICE_CHANNEL_CATEGORY = 886364798749848896
# Default name for auto scaling voice channels
VOICE_CHANNEL_DEFAULT_NAME = 'Voice Channel'


# Self-Role text channel subscription settings
# Enable or Disable Self-Role channel subscriptions, true/false
ROLEBOT_ENABLE = true
# ID of the text channel where subscription options should appear
ROLEBOT_SETTINGS_CHANNEL = 885965370068838858


# Auto-Role settings
# Enable or Disable Auto-Role, true/false
AUTO_ROLE_ENABLE = true
# Roles to instantly add to new members joining the server, comma separated
AUTO_ROLES = Enrolled,Fun,tf2


# Poll settings
# Enable or Disable Polls, true/false
POLL_ENABLE = false
# We have supplied the Helvetica font, please provide your own in the data folder if you wish. (TrueType/.ttf only!)
# Font Regular (default = Helvetica.ttf)
POLL_FONT_REGULAR = Helvetica.ttf
# Font Bold (default = Helvetica-Bold-Font.ttf)
POLL_FONT_BOLD = Helvetica-Bold-Font.ttf
# If fonts other than the default are used, scaling might be required. (default = 10)
POLL_FONT_SCALE = 10

Configure the RoleBot menu.json

The bot requires a configuration file (JSON) to know which role is bound to which text-channel. We've supplied an example in ./clanbotjas/data/menu.json.example.

Note, if you are running with the container option, please populate this file in the container's volume before starting the bot.

  • The first level defines the Catergories where text-channels are in.
  • The second level defines the text-channels and their roles within the category.

An example menu.json

In the example we have two categories, Games and Chatrooms. Each category has two channels joined by a role. If any of these channels and/or roles don't exist when the bot is started, they will be automatically created. Further administration can be done from within Discord and will be saved to menu.json by the bot.

Please keep in mind that these names must follow the same rules as the Discord client follows, so no spaces for titles/role names and no upper-case for titles. Roles can use upper-case. Category titles can use both upper- and lower-case and will be converted by the Discord client to all upper-case, however, the backend is still case-sensitive based on the actual input!

[
    {
        "title": "Games",
        "channels": [
            {
                "title": "team-fortress-2",
                "role": "tf2"
            },
            {
                "title": "pubg",
                "role": "pubg"
            }
        ]
    },
    {
        "title": "Chatrooms",
        "channels": [
            {
                "title": "announcements",
                "role": "announcements"
            },
            {
                "title": "general",
                "role": "general"
            },
            {
                "title": "offtopic",
                "role": "offtopic"
            }
        ]
    }
]

Running the bot in Docker

We've chosen to use Docker Compose to manage the settings and runtime of the container. All you really need to get started and run the bot are the following files from the repository:

  • docker-compose.yml
  • .env.example
  • files inside clanbotjas/data/
  1. Edit the docker-compose.yml file and make sure to replace /opt/discord/ClanBotJas/clanbotjas/data:/clanbotjas/data with /your/path/to/data:clanbotjas/data
  2. Rename .env.example to .env and keep it in the same folder as the docker-compose.yml
  3. Configure the bot with your values in the .env file.

If you are having trouble finding ID's of all objects, enable Developer mode in Discord. This will allow you to right click -> Copy ID on all objects.

  1. Rename menu.json.example to menu.json.
  2. Replace the sample entries with your own categories, channels and roles.
  3. Copy/Move the eveything from the clanbotjas/data folder into the path you configured in step 1.
  4. Run docker-compose up -d from the commandline in the same folder your docker-compose.yml and .env reside.
  5. The bot should now be online in your Discord server!

Running the bot in Kubernetes

If you are running a Kubernetes cluster, we've supplied some example files in the repository under the folder kubernetes. You will need te following files from the repo to deploy to Kubernetes:

  • files inside the kubernetes folder
  • files inside clanbotjas/data/
  1. Go into the Kubernetes folder, you will find 4 yaml files.
  2. Open clanbotjas-env.yaml.
  3. This file creates the configMap for the application, replace all values and save.

If you are having trouble finding ID's of all objects, enable Developer mode in Discord. This will allow you to right click -> Copy ID on all objects.

  1. Open clanbotjas-pv.yaml.
  2. In the example, we use an NFS server for persistent storage. Please replace this with your own storage provider if necessary.
  • If you are using NFS, replace the path: /mnt/path/to/clanbotjas with your own NFS folder mount location.
  • Also make sure to enter your NFS server address.
  1. Go to the clanbotjas/data/ folder and rename menu.json.example to menu.json.
  2. Replace the sample entries with your own categories, channels and roles.
  3. Copy all files from the clanbotjas/data folder into the Kubernetes volume location.
  4. (Optional) create a new namespace if you want to. kubectl create namespace <name>
  5. Apply the kubernetes folder. kubectl apply -f kubernetes -n yournamespace
  6. The bot should now be online in your Discord server!

Running the bot locally

It's also possible to run the bot as a standalone Python application on your computer. Make sure you have Python 3.9 or later installed.

  1. Run git clone https://github.com/ClanBadJas/ClanBotJas.git from the location you want to run the bot.
  2. cd into the clanbotjas folder and run pip install -r requirements.txt to install the dependencies.
  3. Configure the bot settings in clanbotjas/data/.env, you can copy the .env.example to .env to make it easy.

If you are having trouble finding ID's of all objects, enable Developer mode in Discord. This will allow you to right click -> Copy ID on all objects.

  1. Rename menu.json.example to menu.json in the same folder.
  2. Replace the sample entries with your own categories, channels and roles.
  3. Start the bot using python cogmanager.py
  4. The bot should now be online in your Discord server!

Build the container from source

If you want to build the container from source, follow these steps:

  1. Run git clone https://github.com/ClanBadJas/ClanBotJas.git to download the repository.
  2. Make sure you are in the root of the project.
  3. Run docker build -t <username>/<repository>:[version] . to build the container, dont'forget the trailing dot.
  4. The image is now ready to be pushed or used locally.

Clone this wiki locally