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.

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 build. This will download a lot of components and may take some time, wait until it is done.

Without Docker

1. Install PostgreSQL and turn the server on.
2. Install Redis server and turn it on.
3. Install poetry
4. Install Python 3.10 at least
5. 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)
6. Run poetry install

5. Configure the bot

Generate the configuration file

We will need to run the bot at least once to make the bot create the configuration file template.

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 build. This will take a while

3. Type docker compose up bot. This may also take a while the first time.

4. Wait for the bot to start until this appears

   

5. Exit by hitting Ctrl+C

6. Make sure the bot is fully shut down by typing docker compose down

Filling the values

Open the config.yml file with the editor of your choice. Notepad and TextEdit are good enough native solutions.

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.

   Warning: 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.

   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

Unless you know about Prometheus and Grafana, you can leave the other stuff as they are.

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

# 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

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

# 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

# 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

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

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

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 again. 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 (for instance postgres://ballsdex:password@localhost:5432/ballsdex)
4. Export the BALLSDEXBOT_REDIS_URL environment var so that it points to your Redis server (for instance redis://127.0.0.1)
5. Export the environment vars defined in the .env file. Do it manually or check this post.
6. 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!
7. Start the admin panel with python3 -m uvicorn ballsdex.core.admin:_app

Shutdown or restart the bot

Just hit Ctrl+C.

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. Build the code with docker compose build
2. Reboot with docker compose down then docker compose up

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