Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Capinetta-RP/capinetta-discord-bot/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through getting the complete Capinetta RP Bot System running from scratch: both bots online, all slash commands registered in your Discord server, and the MariaDB database fully initialized through Prisma. By the end you’ll have capinetta-general and capinetta-whitelist running as managed PM2 processes and ready to accept the initial /setup wizard.

​
Prerequisites

Before you begin, make sure the following are available on your host machine:
  • Node.js v18+ — v20 LTS is recommended. Check with node --version.
  • MariaDB or MySQL 8.0+ — running locally or reachable via a connection string.
  • Two Discord bot tokens — one for Bot General and one for Bot Whitelist. Create both at the Discord Developer Portal.
  • PM2 installed globally — used to run both bots as persistent background processes: 
    npm install -g pm2

​
Installation

1

Clone the Repository

Download the source code and navigate into the project directory:
git clone https://github.com/Capinetta-RP/capinetta-discord-bot.git
cd capinetta-discord-bot
2

Configure Environment Variables

Copy the example environment file and open it in your editor:
cp .env.example .env
Fill in at minimum the following required variables (see Configuration for the full reference):
# Bot tokens — from Discord Developer Portal → Bot → Reset Token
GENERAL_TOKEN=your_general_bot_token
WHITELIST_TOKEN=your_whitelist_bot_token

# OAuth2 — from Discord Developer Portal → OAuth2
GENERAL_CLIENT_ID=your_oauth2_client_id
GENERAL_CLIENT_SECRET=your_oauth2_client_secret
DASHBOARD_CALLBACK_URL=http://localhost:3000/auth/discord/callback
SESSION_SECRET=generate_a_secure_random_string_here

# Discord server ID
GENERAL_GUILD_ID=your_main_discord_server_id

# Database — MariaDB/MySQL connection string
DATABASE_URL="mysql://USER:PASSWORD@localhost:3306/DB_NAME"
All eight of these variables are validated at startup by config.js. If any are missing, the bot will log a fatal error listing the absent keys and exit immediately — it cannot start without them.
3

Install Dependencies and Initialize the Database

Install all Node.js packages, generate the Prisma client, and push the schema to your database:
npm install
npx prisma generate
npx prisma db push
If npx prisma db push throws a connection error, your MariaDB service may not be running. Start it with:
# Linux
sudo systemctl start mariadb

# macOS (Homebrew)
brew services start mariadb

# Windows
# Open services.msc, find "MySQL" or "MariaDB", and click Start
4

Deploy Slash Commands to Discord

Register the slash commands for both bots. This sends command definitions to the Discord API for your configured guild:
npm run deploy:general
npm run deploy:whitelist
Both scripts print ✅ Comandos registrados exitosamente on success. You can also run both at once:
npm run deploy
Commands can take up to a few seconds to propagate in Discord. If you type / in your server and don’t see them immediately, wait a moment and retry.
5

Start in Production with PM2

Launch both bots as persistent PM2 processes using the included ecosystem.config.js:
npm run prod
PM2 will start two processes — capinetta-general (runs index-general.js) and capinetta-whitelist (runs index-whitelist.js) — both with NODE_ENV=production. Watch for these confirmation lines in the output:
✅ Bot General iniciado correctamente
✅ Bot Whitelist iniciado correctamente
To check running processes at any time:
pm2 status
pm2 logs capinetta-general
pm2 logs capinetta-whitelist
6

Run Initial Setup in Discord

With both bots online, run the interactive setup wizard inside any channel in your Discord server:
/setup
The wizard guides you through:
  • Setting the welcome channel (where Canvas welcome cards are posted on member join)
  • Configuring the isolation zone (the restricted channel spam offenders are moved to)
  • Defining the verified role given to members who pass the verification button check
Once setup is complete, your server is fully operational. You can inspect or update any setting at any time with /config.
Use npm start during local development — it runs index-general.js directly and streams all logs to your terminal, making it easy to iterate quickly. Reserve npm run prod (PM2) for production deployments where you need automatic restarts, process supervision, and persistent log storage.

​
Troubleshooting

Dependencies were not installed or the installation was interrupted. Run:
npm install
If the error persists, delete the node_modules folder and try again:
rm -rf node_modules
npm install
The MariaDB service is not running, or the credentials in DATABASE_URL are incorrect. First verify the service is active:
# Linux
sudo systemctl status mariadb

# macOS
brew services list | grep mariadb

# Windows — check Services (services.msc) for MySQL/MariaDB
Then confirm you can connect manually:
mysql -u YOUR_USER -p -h localhost
If the service is running but the connection still fails, double-check the host, port, username, and password in your DATABASE_URL.
The bot token in .env is incorrect, has extra whitespace, or has been regenerated since you last copied it.
  1. Open the Discord Developer Portal and navigate to your application’s Bot tab.
  2. Click Reset Token, confirm, and copy the new token.
  3. Paste it into .env as GENERAL_TOKEN or WHITELIST_TOKEN — ensure there are no leading or trailing spaces.
  4. Restart the bot: pm2 restart all (or npm start for development).
Prisma cannot push the schema because the target database hasn’t been created yet. Create it manually in the MariaDB shell, then rerun the push:
CREATE DATABASE capi_netta;
EXIT;

npx prisma db push
Make sure DB_NAME in your DATABASE_URL matches the database name you just created.
The slash commands were not deployed, or they were deployed to a different guild ID. Redeploy and ensure GENERAL_GUILD_ID in .env matches your server’s ID:
npm run deploy:general
npm run deploy:whitelist
Also verify that the bot has the applications.commands OAuth2 scope and Administrator (or at minimum Send Messages + Use Slash Commands) permissions in your server. You can reinvite it with:
https://discord.com/oauth2/authorize?client_id=YOUR_CLIENT_ID&permissions=8&scope=bot+applications.commands

Build docs developers (and LLMs) love

Get started for freeTalk to us