Installing Ballsdex

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.

Important

If you cannot install Docker, keep reading, you can run the bot without it but it's not recommended.

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

Windows

1. Right-click in the place where you want to install the bot, for instance your desktop, and select "Git bash here".

2. Paste the following command:

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

A folder named BallsDex-DiscordBot should have appeared. If not, right-click and hit "Refresh".

macOS/Linux

1. Open the terminal app and navigate to the folder where you want to install the bot using the cd command. For instance, if you want to install the bot in your desktop, type cd Desktop.

2. Paste the following command:

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

A folder named BallsDex-DiscordBot should have appeared.

4. Installing the bot

With Docker (recommended)

1. Open a command prompt and navigate to the bot's folder

   • Windows: Open the folder, then in the explorer's navigation bar, write "powershell"
   • macOS/Linux: Open the terminal and use cd <folder> to navigate (for instance cd Desktop/BallsDex-DiscordBot)

2. Make sure the bot is running by entering the docker ps command. If there is an error such as "Cannot connect to the Docker daemon", start Docker.

3. Run docker compose pull. This will download a lot of components and may take some time, wait until it is done.

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

5. 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.

Without Docker

1. Install PostgreSQL and turn the server on.

   • You must create a user and a database. You can use the command line tools or use a GUI like pgAdmin.

2. Install Python 3.13 at least

3. Install poetry

4. Open a command prompt and navigate to the bot's folder

   • Windows: Open the folder, then in the explorer's navigation bar, write "powershell"
   • macOS/Linux: Open the terminal and use cd <folder> to navigate (for instance cd Desktop/BallsDex-DiscordBot)

5. Run poetry install

6. To generate the configuration file, run poetry run python3 -m ballsdex --reset-settings. The following text should appear, and the process will exit:

   

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.

Tip

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.

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: INSERT_TOKEN_HERE

# 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/ballsdex  # BallsDex official server

  terms-of-service: https://gist.github.com/laggron42/52ae099c55c6ee1320a260b0a3ecac4e
  privacy-policy: https://gist.github.com/laggron42/1eaa122013120cdfcc6d27f9485fe0bf

# override the name "countryballs" in the bot
collectible-name: countryball

# 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

# 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:
    - 1049119446372986921
    - 1049119786988212296
    - 1095015474846248970

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

packages:
  - 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: true
  host: "0.0.0.0"
  port: 15260


# 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: true

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

Now we should be ready for the next part.

6. Run the bot

With Docker

1. Open a command prompt and navigate to the bot's folder
   • Windows: Open the folder, then in the explorer's navigation bar, write "powershell"
   • macOS/Linux: Open the terminal and use cd <folder> to navigate (for instance cd Desktop/BallsDex-DiscordBot)
2. Run docker compose up. This will start all services and show the logs live in the console. If you close the console, the bot will be shut down.
   • If you run docker compose up -d, you will be running in detached mode. You can close the window safely, and the bot will continue running. You can use docker compose logs -f to view the logs.

Shutdown or restart the bot

1. Open a command prompt and navigate to the bot's folder
   • Windows: Open the folder, then in the explorer's navigation bar, write "powershell"
   • macOS/Linux: Open the terminal and use cd <folder> to navigate (for instance cd Desktop/BallsDex-DiscordBot)
2. Type docker compose down and wait for all services to go down.
3. If you're restarting, simply type docker compose up --build. Do not use docker compose restart as it does not reload some elements.

Without Docker

1. Open a command prompt and navigate to the bot's folder
   • Windows: Open the folder, then in the explorer's navigation bar, write "powershell"
   • macOS/Linux: Open the terminal and use cd <folder> to navigate (for instance cd Desktop/BallsDex-DiscordBot)
2. Run poetry shell
3. Export the BALLSDEXBOT_DB_URL environment var so that it points to your PostgreSQL server in this format: postgres://user:password@localhost:5432/database
   • On PowerShell, run $Env.BALLSDEXBOT_DB_URL = 'postgres://user:password@localhost:5432/database'
   • On Linux/macOS/WSL, run export BALLSDEXBOT_DB_URL='postgres://user:password@localhost:5432/database'
4. Start the bot with python3 -m ballsdex.
   • You can look for additional starting options by running python3 -m ballsdex -h, there's a full CLI available!
5. In another terminal, repeat steps 1 to 3 and start the admin panel with python3 -m uvicorn ballsdex.core.admin:_app

Shutdown or restart the bot

Just hit Ctrl+C and run the last command again.

7. Updating the bot

Note: this only works for git installs. If you installed using a downloaded zip file, migrate to a git install now.

1. Open a command prompt and navigate to the bot's folder
   • Windows: Open the folder, then in the explorer's navigation bar, write "powershell"
   • macOS/Linux: Open the terminal and use cd <folder> to navigate (for instance cd Desktop/BallsDex-DiscordBot)
2. 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, if you do run git reset - it will reset any changes you may have. Be cautious of this.

Next, build the bot and restart it following your case:

With Docker

1. Reboot with docker compose down then docker compose up --build

Warning

It is important that you use the --build option to properly download any new requirement.

Without Docker

1. Check for new requirements by running poetry install
2. Shut down the bot with Ctrl+C, and restart the same way as usual