🌟 Lumina

Lumina is a modular Discord bot built using Hikari and Lightbulb.

I'm building this bot in my free time as a hobby, though I will try to keep the code clean and nice.

🚀 Features

• Modular, you will be able to easily disable specific plugins.
• Easy to configure via lumina_config.toml and .env.

🔌 Plugins

Lumina is currently W.I.P

• Basic: a simple plugin that includes a command group with ping and latencies.
• Moderation: a plugin (W.I.P) for moderation commands, event listeners, and utilities.

📦 Requirements

• Python 3.10+
• Postgresql
• A Discord Bot Token acquired from the discord developer portal.

🔧 Running

Downloading

First, clone the repository (recommended) or download and extract it

In order to clone the repository, we need to ensure that we have Git installed and then we'll run the following in our preferred directory.

# Go to your directory of choice e.g., ~/Documents/Projects
cd my/preferred/directory

# Clone the lumina repository
git clone https://github.com/Forbidden-A/Lumina.git 

# Move to the cloned repository
cd Lumina

Now you have Lumina downloaded.

Setting the bot up

In order to set up the bot, we need to set up some variables and configuration options.

The config file

In order to provide our bot with its configuration options we will need to modify or create a file, lumina_config.toml.

Below is a list of available config options.

⚠️ Warning: Required values MUST be set for the bot to run.

💡 Note: You can make a configuration option pull its value from an envrionment variable, to do so, check out confspec syntax.

Variable	Description	Default/Required
app.log	The logging level to use. [DEBUG, INFO, WARN, ERROR]	WARN
discord.token	The token to login to discord with	Required
postgresql.user	The user to login as to the db	user
postgresql.password	The database password	Optional
postgresql.database	The database to login to and use	lumina
postgresql.host	The host to use to connect to the database	localhost
postgresql.port	The port with which to connect to the database	5432

For example

lumina_config.toml

[app]
log="INFO"

[discord]
token = "${DISCORD_TOKEN~}"

[postgresql]
user="user"
database="potato"
host="my.cool.host"
port=5432

or

app = { log = "INFO" }
discord = { token = "${DISCORD_TOKEN~}" }
postgresql = { user = "user", database = "potato", host = "my.cool.host", port = 5432 }

Environment variables

We can either set the environment variables manually or create a dotenv file.

Creating a dotenv file

While we're still inside the Lumina directory, we'll create a new file called .env using our preferred method.

For example

touch .env

next we'll open the file using our editor of choice

For example

code .env

then we'll set variables as follows

DISCORD_TOKEN=MY_VERY_SECRET_TOKEN
DATABASE_PASSWORD=MY_SECRET_DATABASE_PASSWORD

Installing dependencies and running the bot

Now that we've set our environment variables and configured Lumina, and assuming we have python and our package manager of choice installed we just need to install the dependencies before running the bot.

Create a virtual environment (recommended) and install dependencies

For example (venv + pip)

Windows

1. Create the venv

python -m venv .venv

2. Enter the venv

.\.venv\Scripts\activate

3. Install the dependencies

python -m pip install .

Linux/macOS

1. Create the venv

python3 -m venv .venv

2. Enter the venv

source .venv/bin/activate

3. install dependencies

python3 -m pip install .

Running the bot

4. Now whenever we want to run the bot we enter the venv and then run the following

# Windows
python -m lumina
# Or Linux/macOS
python3 -m lumina

using uv it's much simpler, we can just run the following

uv run python -m lumina

this should install all of the dependencies and then run the bot.

📝 TODO

Below is a list of planned and in-progress features for Lumina:

• ✨ Add more plugins (e.g., Fun, Utility, Music)
  • Finish moderation plugin
  • Start work on other plugins
• 🛠️ Implement plugin loading/unloading system
• 🧪 Write unit tests
• 💾 Add database migration support
• 🔒 Add proper error handling and logging config
• 🌐 Create web dashboard (optional/future)
• 📚 Write full user and developer documentation
• 🧰 Add CI (e.g., test, lint, typecheck workflows) ?
• 🐳 Add Dockerfile and docker-compose setup