Installing Ballsdex using Docker

Caution

Ballsdex has dropped support for Docker a while ago. You may still get some support if you are using Docker, but some solutions will most likely tell you to move to WSL instead of using Docker for Windows. This tutorial only exists for archival purposes and for those who want to see the old tutorial.

Credit to El Laggron for creating the original tutorial.

1. Install requirements

You need to install Docker and git on your computer.

When installing git, be sure to choose the option that says "Git from the command line and also for 3rd-party software". Leave the other options to their default values.

2. Create a Discord bot account

You must first setup a Discord bot account. You can follow discord.py's tutorial to create and invite your bot.

For now, don't copy your token, but keep the page open.

Once this is configured, you also need to enable message content intent. Go to the "Bot" tab of your application, scroll down to "Privileged intents" and tick "Message content".

Tip

You can fill the description of your application, it will appear under the "About me" section.

3. Download the bot

1. Open Command Prompt by typing "cmd" in your search bar.

2. Paste the following command:

git clone https://github.com/laggron42/BallsDex-DiscordBot.git

A folder named BallsDex-DiscordBot should have appeared in the directory where you did the command.

4. Installing the bot

1. Run docker compose build. This will also take some time, wait for the build to complete.

2. Run docker compose up bot to generate the default configuration file. Skip this step if you already have a config.yml file. The following text should appear:

The process should exit afterwards. If it doesn't, hit Ctrl+C.

5. Configure the bot

Open the new config.yml file with the editor of your choice. I recommend using Visual Studio Code to get autocompletion and error highlighting. Once installed, you can run code config.yml to open VScode from your terminal.

Note

In YAML files, everything after a # is a comment. Those lines are here to document and help you understand the possible values.

1. Go back to the Discord developer portal and click "Reset Token" to obtain a new one. Copy and paste it right after discord-token: . Make sure that there is a space between discord-token: and your token, otherwise it will not work.

Caution

Do not share your token! It is the password of your bot, and allows anyone full access to its account if shared. Be sure to keep it secure, and immediately reset if you think it leaked.

2. The about section defines a few traits of the /about command. Feel free to change the description and the discord-invite.

3. You can change collectible-name which will replace the word countryball in the bot. For instance if you set "rock", the bot will say "A wild rock spawned!"

4. bot-name is used in various places like /about or /balls completion.

5. The admin section configures the /admin command. This command is only enabled in specific servers for specific roles.

   1. guild-ids is for the servers where you want to enable the /admin command. Copy the IDs of the servers you want, and paste them

   2. root-role-ids is for the roles IDs which will get full access to the /admin command, granting the ability to spawn or give balls and control blacklist.

   3. admin-role-ids is for the role IDs which will get partial access to the /admin command. Their access will be limited to blacklist control and seeing shared servers.

Note

General notice about IDs

To obtain an ID, enable developer mode and right click a server or a role, then select "Copy ID".

If you have just one ID, put it like this (for instance guild IDs)

guild-ids:
  - 1049118743101452329

If you have multiple IDs, they should be placed like this (for instance role IDs here):

root-role-ids:
  - 1049119446372986921
  - 1049119786988212296

There may be other configuration values added over time, look at the comment to understand what they do. If an option is unclear to you, you should leave it to its default value.

Tip

Author of the wiki here, you also have the option to use the config filler website if you are a beginner and don't know what to do.

Here's the config.yml file from Ballsdex if you want to compare and troubleshoot eventual issues:

# yaml-language-server: $schema=json-config-ref.json

# paste the bot token after regenerating it here
discord-token: 

# prefix for old-style text commands, mostly unused
text-prefix: b.

# define the elements given with the /about command
about:

  # define the beginning of the description of /about
  # the other parts is automatically generated
  description: >
    Collect countryballs on Discord, exchange them and battle with friends!

  # override this if you have a fork
  github-link: https://github.com/laggron42/BallsDex-DiscordBot

  # valid invite for a Discord server
  discord-invite: https://discord.gg/INVITE_CODE_HERE

  terms-of-service: https://gist.github.com/ # replace with your own link
  privacy-policy: https://gist.github.com/ # replace with your own link

# WORK IN PROGRESS, DOES NOT FULLY WORK
# override the name "countryball" in the bot
collectible-name: countryball

# WORK IN PROGRESS, DOES NOT FULLY WORK
# override the name "countryballs" in the bot
plural-collectible-name: countryballs

# WORK IN PROGRESS, DOES NOT FULLY WORK
# override the name "BallsDex" in the bot
bot-name: BallsDex

# players group cog command name
# this is /balls by default, but you can change it for /animals or /rocks for example
players-group-cog-name: balls

# emoji used to represent a favorited collectible
favorited-collectible-emoji: ❤️

# maximum amount of favorites that are allowed
max-favorites: 50

# the highest/lowest possible attack bonus, do not leave empty
# this cannot be smaller than 0, enter a positive number
max-attack-bonus: 20

# the highest/lowest possible health bonus, do not leave empty
# this cannot be smaller than 0, enter a positive number
max-health-bonus: 20

# enables the /admin command
admin-command:

  # all items here are list of IDs. example on how to write IDs in a list:
  # guild-ids:
  #   - 1049118743101452329
  #   - 1078701108500897923

  # list of guild IDs where /admin should be registered
  guild-ids:
    - 1049118743101452329

  # list of role IDs having full access to /admin
  root-role-ids:
    - 1078701108500897923

  # list of role IDs having partial access to /admin
  admin-role-ids:
    - 1078701108500897923

# log channel for moderation actions
log-channel:

# manage bot ownership
owners:
  # if enabled and the application is under a team, all team members will be considered as owners
  team-members-are-owners: false

  # a list of IDs that must be considered owners in addition to the application/team owner
  co-owners:
   - 1029173167115218954


# Admin panel related settings
admin-panel:

    # to enable Discord OAuth2 login, fill this
    # client ID of the Discord application (not the bot's user ID)
    client-id: 
    # client secret of the Discord application (this is not the bot token)
    client-secret: 

    # to get admin notifications from the admin panel, create a Discord webhook and paste the url
    webhook-url: 

    # this will provide some hyperlinks to the admin panel when using /admin commands
    # set to an empty string to disable those links entirely
    url: http://localhost:8000

# list of packages that will be loaded
packages:
  - ballsdex.packages.dexscript
  - ballsdex.packages.admin
  - ballsdex.packages.balls
  - ballsdex.packages.config
  - ballsdex.packages.countryballs
  - ballsdex.packages.info
  - ballsdex.packages.players
  - ballsdex.packages.trade

# prometheus metrics collection, leave disabled if you don't know what this is
prometheus:
  enabled: false
  host: "0.0.0.0"
  port: 15260 

# spawn chance range
# with the default spawn manager, this is *approximately* the min/max number of minutes
# until spawning a countryball, before processing activity
spawn-chance-range: [40, 55] 

spawn-manager: ballsdex.packages.countryballs.spawn.SpawnManager

# sentry details, leave empty if you don't know what this is
# https://sentry.io/ for error tracking
sentry:
    dsn: ""
    environment: "production"

catch:
  # Add any number of messages to each of these categories. The bot will select a random
  # one each time.
  # {user} is mention. {collectible} is collectible name. {ball} is ball name, and 
  # {collectibles} is collectible plural.

  # the label shown on the catch button
  catch_button_label: "Catch me!"

  # the message that appears when a user catches a ball 
  caught_msgs:
    - "{user} You caught **{ball}**!"

  # the message that appears when a user gets the name wrong
  # here and only here, you can use {wrong} to show the wrong name that was entered
  # note that a user can put whatever they want into that field, so be careful
  wrong_msgs:
    # - {user} Wrong name! You put: {wrong}
    - "{user} Wrong name!"

  # the message that appears above the spawn art
  # {user} is not available here, because who would it ping?
  spawn_msgs:
    - "A wild {collectible} has appeared!"

  # the message that appears when a user is to slow to catch a ball
  slow_msgs:
    - "{user} Sorry, this {collectible} was caught already!"

Now we should be ready for the next part.

6. Run the bot

To start the bot, simply run docker compose up. This will both start the bot and the admin panel, while showing you the live logs. Wait until the line "Ballsdex bot is now ready" shows up, and the bot should be online!

To shut down the bot, use Ctrl+C.

Detached mode

You will notice that the command above blocks your terminal. You can also run the bot in detached mode with docker compose up -d which allows you to keep using the terminal afterwards.

In this mode, you can use docker compose logs -f to view the live logs (Ctrl+C to exit). You can also specify containers to filter which logs you want to see, like docker compose logs -f bot or docker compose logs -f admin-panel.

To shut down the bot in this mode, run docker compose down.

7. Updating the bot

1. Run git pull and wait for the changes to be pulled.
   • If you encounter an error, which may happen when you're editing the source files, run git reset --hard HEAD to reset all changes done, then run git pull again. Note that it will reset any changes you may have.
2. Fully shut down the bot with docker compose down (even if you used Ctrl+C before!)
3. Rebuild the bot with docker compose build
4. Start again with docker compose up (or docker compose up -d in detached)
5. Verify that no error happens while the bot starts!