Skip to content

Installing Ballsdex without Docker

The recommended way to run Ballsdex is using Docker, but you may have reasons to run it without this dependency.

This install method is supported but only recommended for the advanced users, there are a lot of additional steps and dependencies to manage yourself.

Info

Few commands will be given, but online guides are given instead. This is because instructions differ between operating systems, so you have to use what's best for you.

1. Setting up the database

Install PostgreSQL and start it. Create a database by following this guide.

You must then have a link to connect to the database in the following format: postgres://username:password@localhost:5432/database_name

Test that your database is up with the following command: psql -c "\l" postgres://username:password@localhost:5432/database_name
Check that your database appears in the list and that your user is the owner.

2. Requirements

git

Git is needed to download and update the source code.

uv

You will need our package manager uv to install the dependencies, manage Python versions and virtual environments.

Follow the instructions here to install uv on your system.

Tip

Ballsdex requires Python 3.14 at least.

If you don't have it installed, uv will install it for you, but you can make the installation lighter by installing Python 3.14 with your system's package manager.

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

Info

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

3. Download the source code

Type the following command to download the latest version of the bot:

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

Then you can use the command cd to change directory and open the folder you just downloaded:

cd BallsDex-DiscordBot

4. Installing the bot

  1. Download the bot's dependencies and install them in a virtual environment.

    uv sync

    Info

    If you don't have Python 3.14, it will also be downloaded for your virtual environment.

  2. Open the virtual environment where your dependencies are

    source .venv/bin/activate

    . .\.venv\Scripts\activate.ps1

  3. Export the BALLSDEXBOT_DB_URL environment variable with the link to Postgres you tested earlier.

    export BALLSDEXBOT_DB_URL=postgres://username:password@localhost:5432/database_name

    $Env.BALLSDEXBOT_DB_URL = 'postgres://username:password@localhost:5432/database_name'

  4. Check that the bot loads successfully. This should print the version number and exit. 

    python3 -m ballsdex --version

  5. Open the admin_panel folder for the next steps 

    cd admin_panel

  6. Initialize the database 

    python3 manage.py migrate

  7. Initialize the admin panel 

    python3 manage.py collectstatic --no-input

  8. Start the admin panel to configure the settings 

    DJANGO_SETTINGS_MODULE="admin_panel.settings.dev" uvicorn admin_panel.asgi:application

5. Configure the bot

Follow this section from the main tutorial to fill the base settings.

6. Run the bot

Go back to the previous folder with cd .., then, run python3 -m ballsdex to start the bot! To shut it down, type Ctrl+C.

Tip

There are multiple options available when running the bot, do python3 -m ballsdex -h to view them.

Running the admin panel

  1. Open another shell with the virtualenv and the environment variables exported

    source .venv/bin/activate
export BALLSDEXBOT_DB_URL=postgres://username:password@localhost:5432/database_name
export DJANGO_SETTINGS_MODULE="admin_panel.settings.dev"

    . .\.venv\Scripts\activate.ps1
$Env.BALLSDEXBOT_DB_URL = 'postgres://username:password@localhost:5432/database_name'
$Env.DJANGO_SETTINGS_MODULE = 'admin_panel.settings.dev'

  2. Start the admin panel 

    cd admin_panel && uvicorn admin_panel.asgi:application

  3. Follow this guide afterwards

Warning

This tutorial shows you how to run the dev configuration, which serves static files. The default configuration does not handle static files and should be handled by you. Ballsdex includes an nginx file showing you how you may configure static files on your own.

If you intend to expose this website online, it's super important that you come up with a solution and don't keep the developer configuration

Summary

Before running any command, do these:

# open the bot's directory
cd BallsDex-DiscordBot

# activate the virtual environment
source .venv/bin/activate

# export the database env var
export BALLSDEXBOT_DB_URL=postgres://username:password@localhost:5432/database_name
export DJANGO_SETTINGS_MODULE="admin_panel.settings.dev"

# open the bot's directory
cd BallsDex-DiscordBot

# activate the virtual environment
. .\.venv\Scripts\activate.ps1

# export the database env var
$Env.BALLSDEXBOT_DB_URL = 'postgres://username:password@localhost:5432/database_name'
$Env.DJANGO_SETTINGS_MODULE = 'admin_panel.settings.dev'

Then

  • Start the bot: 
    python3 -m ballsdex
  • Start the admin panel: 
    cd admin_panel && uvicorn admin_panel.asgi:application

Updating the bot

  1. Pull the new files. 
    git pull
  2. Update dependencies 
    uv sync
  3. Open the admin panel folder 
    cd admin_panel
  4. Update the database schemas 
    python3 manage.py migrate
  5. Update the admin panel static files 
    python3 manage.py collectstatic --no-input
  6. Restart the bot and admin panel