Setup Guide

Complete installation and configuration guide

Setup Guide

Complete installation, configuration, and deployment guide for the Discord Game Management Bot.

Table of Contents

Prerequisites

Before you begin, ensure you have:

  • Node.js 18 or higher (Download)
  • npm (comes with Node.js)
  • Git (for cloning the repository)
  • A Discord account
  • Administrator access to a Discord server for testing

Verify Prerequisites

node --version  # Should be v18.0.0 or higher
npm --version   # Should be 8.0.0 or higher

Creating a Discord Bot

1. Create a Discord Application

  1. Go to the Discord Developer Portal
  2. Click "New Application"
  3. Enter a name for your bot (e.g., "Game Management Bot")
  4. Click "Create"

2. Create a Bot User

  1. Navigate to the "Bot" tab in the left sidebar
  2. Click "Add Bot"
  3. Confirm by clicking "Yes, do it!"
  4. Important: Under "Privileged Gateway Intents", enable:
    • ✅ Server Members Intent
    • ✅ Message Content Intent (optional, for future features)

3. Get Your Bot Token

  1. In the Bot tab, click "Reset Token"
  2. Copy the token and save it securely
  3. Never share this token publicly

4. Get Your Application ID

  1. Navigate to the "General Information" tab
  2. Copy the "Application ID" (also called Client ID)
  3. Save this for the .env file

5. Generate Bot Invite Link

Use this URL template to invite your bot to a server:

https://discord.com/api/oauth2/authorize?client_id=YOUR_CLIENT_ID&permissions=8&scope=bot%20applications.commands

Replace YOUR_CLIENT_ID with your Application ID from step 4.

Permissions Breakdown:

  • permissions=8 = Administrator (recommended for initial setup)
  • scope=bot%20applications.commands = Bot + Slash Commands

Alternative (Minimal Permissions):

For production, use specific permissions instead of Administrator:

https://discord.com/api/oauth2/authorize?client_id=YOUR_CLIENT_ID&permissions=268445718&scope=bot%20applications.commands

This grants:

  • Manage Roles
  • Manage Channels
  • Send Messages
  • Manage Messages
  • Embed Links
  • Read Message History

Local Development Setup

1. Clone the Repository

git clone <repository-url>
cd discord-game-management-bot

2. Install Dependencies

npm install

This will install:

  • discord.js - Discord API wrapper
  • @prisma/client - Database ORM
  • dotenv - Environment variables
  • Development dependencies (ESLint, Prisma CLI)

3. Create Environment File

# Copy the template
cp .env.example .env

# On Windows:
copy .env.example .env

4. Configure Environment Variables

Edit the .env file with your actual values:

# Required: Your bot's token from Discord Developer Portal
DISCORD_TOKEN=your_actual_bot_token_here

# Required: Your bot's application/client ID
DISCORD_CLIENT_ID=your_actual_client_id_here

# Database (SQLite for development)
DATABASE_URL="file:./dev.db"

# Optional: Logging level (debug, info, warn, error)
LOG_LEVEL=info

# Optional: Set after running /setupdashboard
DASHBOARD_CHANNEL_ID=

Database Setup

1. Generate Prisma Client

npm run db:generate

This generates the Prisma client based on your schema.

2. Run Database Migrations

npm run db:migrate

This creates the SQLite database file and applies all migrations.

You should see output like:

✔ Generated Prisma Client
✔ Applied migration 20240101000000_init

3. Verify Database (Optional)

Open Prisma Studio to inspect your database:

npm run db:studio

This opens a web interface at http://localhost:5555 where you can view and edit database records.

Running the Bot

Development Mode (with hot-reload)

npm run dev

This starts the bot with Node.js's watch mode. The bot will automatically restart when you make code changes.

Expected Output:

[INFO] Loading configuration...
[INFO] Connecting to database...
[INFO] Database connected
[INFO] Initializing Discord client...
[INFO] Loading modules...
[INFO] Loaded module: game-management
[INFO] Registering 6 commands...
[INFO] Bot is ready! Logged in as YourBot#1234
[INFO] Connected to 1 guild(s)

Production Mode

npm start

This starts the bot without hot-reload for production environments.

Verify Bot is Running

  1. Check Discord - your bot should appear Online
  2. In your Discord server, type / and you should see the bot's commands:
    • /setupdashboard
    • /addgame
    • /removegame
    • /joingame
    • /leavegame
    • /gameplus

First-Time Server Setup

1. Set Up the Dashboard

In your Discord server, run:

/setupdashboard

This creates an interactive control panel in the current channel.

What it does:

  • Creates a persistent embed message
  • Adds interactive buttons (Add Game, Remove Game, View Games, Refresh)
  • Saves the channel and message IDs to the database

Recommendation: Create a dedicated channel like #bot-dashboard or #game-management.

2. Add Your First Game

Option A: Using the Dashboard (Recommended)

  1. Click the "Add Game" button on the dashboard
  2. Fill out the modal form:
    • Game Name: The name of the game (e.g., "Valorant")
    • Setup Mode: Choose simple or advanced
    • Emoji: Optional emoji for the game (e.g., 🎮)
    • Enable Plus: yes or no (Advanced mode only)
    • Voice Channels: Number of voice channels (Advanced mode only, default: 2)

Option B: Using Slash Command

/addgame

Then fill out the same modal form.

3. Test the Game Structure

After adding a game, verify:

  • ✅ Roles created: 🎮 GameName Admin, 🎮 GameName
  • ✅ Category created: 🎮 GameName
  • ✅ Channels created under the category
  • ✅ Permissions set correctly (@everyone can't see channels)

4. Assign Yourself Roles

/joingame game:GameName

You should now see the game's channels.

To test Plus access (Advanced mode):

/gameplus user:@YourName game:GameName

Production Deployment

Option 1: VPS/Cloud Server (Recommended)

Prerequisites

  • Ubuntu 20.04+ or similar Linux distribution
  • Root or sudo access
  • Node.js 18+ installed
  • PM2 or systemd for process management
  • PostgreSQL (for production database)

Step 1: Server Setup

# Update system
sudo apt update && sudo apt upgrade -y

# Install Node.js 18
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs

# Install PostgreSQL
sudo apt install -y postgresql postgresql-contrib

# Install PM2 (process manager)
sudo npm install -g pm2

Step 2: Database Setup (PostgreSQL)

# Create database and user
sudo -u postgres psql

In PostgreSQL shell:

CREATE DATABASE discordbot;
CREATE USER botuser WITH ENCRYPTED PASSWORD 'your_secure_password';
GRANT ALL PRIVILEGES ON DATABASE discordbot TO botuser;
\q

Step 3: Deploy Bot

# Clone repository
cd /opt
sudo git clone <repository-url> discord-bot
cd discord-bot
sudo chown -R $USER:$USER .

# Install dependencies
npm install --production

# Create .env file
nano .env

Edit .env for production:

DISCORD_TOKEN=your_production_token
DISCORD_CLIENT_ID=your_client_id

# PostgreSQL connection
DATABASE_URL="postgresql://botuser:your_secure_password@localhost:5432/discordbot"

LOG_LEVEL=info
DASHBOARD_CHANNEL_ID=your_dashboard_channel_id

Step 4: Run Migrations

# Generate Prisma client
npm run db:generate

# Run PostgreSQL migrations (automatically switches to postgresql provider)
npm run db:migrate:prod

Important: The db:migrate:prod script automatically switches the Prisma schema to use PostgreSQL before running migrations. All migration files have been updated with PostgreSQL-compatible syntax.

Step 5: Start with PM2

# Start the bot
pm2 start src/index.js --name discord-bot

# Save PM2 config
pm2 save

# Set up auto-start on boot
pm2 startup
# Follow the instructions printed by the command above

Step 6: Monitor

# View logs
pm2 logs discord-bot

# Monitor status
pm2 status

# Restart bot
pm2 restart discord-bot

Option 2: Docker (Alternative)

Create a Dockerfile:

FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
RUN npm install --production

COPY . .

RUN npx prisma generate

CMD ["node", "src/index.js"]

Create docker-compose.yml:

version: '3.8'

services:
  bot:
    build: .
    restart: unless-stopped
    environment:
      - DISCORD_TOKEN=${DISCORD_TOKEN}
      - DISCORD_CLIENT_ID=${DISCORD_CLIENT_ID}
      - DATABASE_URL=postgresql://botuser:password@db:5432/discordbot
      - LOG_LEVEL=info
    depends_on:
      - db
    volumes:
      - ./logs:/app/logs

  db:
    image: postgres:15-alpine
    restart: unless-stopped
    environment:
      - POSTGRES_USER=botuser
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=discordbot
    volumes:
      - db_data:/var/lib/postgresql/data

volumes:
  db_data:

Deploy:

docker-compose up -d

Option 3: Railway / Heroku

Railway

  1. Create account at railway.app
  2. Click "New Project" → "Deploy from GitHub"
  3. Select your repository
  4. Add PostgreSQL database service
  5. Set environment variables in Railway dashboard
  6. Deploy

Heroku

# Install Heroku CLI
npm install -g heroku

# Login
heroku login

# Create app
heroku create your-bot-name

# Add PostgreSQL
heroku addons:create heroku-postgresql:hobby-dev

# Set environment variables
heroku config:set DISCORD_TOKEN=your_token
heroku config:set DISCORD_CLIENT_ID=your_client_id

# Deploy
git push heroku main

Troubleshooting

Bot Won't Start

Error: "Invalid token"

  • Check that DISCORD_TOKEN in .env is correct
  • Ensure no extra spaces or quotes around the token
  • Regenerate token in Discord Developer Portal if needed

Error: "Missing Access"

  • Reinvite bot with correct permissions
  • Ensure bot role is above game roles in server settings

Database Issues

Error: "Can't reach database server"

  • For SQLite: Check file permissions on dev.db
  • For PostgreSQL: Verify connection string in DATABASE_URL
  • Run npm run db:generate after changing schema

Error: "Migrations failed"

  • Delete database file (dev.db) and run npm run db:migrate again
  • For PostgreSQL: Drop and recreate database

Error: "Migration ... failed to apply"

  • Ensure you're using the correct database provider for your environment
  • For development (SQLite): npm run db:migrate
  • For production (PostgreSQL): npm run db:migrate:prod
  • The migration scripts automatically switch the database provider before running

Fresh PostgreSQL Installation:

For a fresh PostgreSQL database setup:

# 1. Set up .env.production with PostgreSQL connection string
# DATABASE_URL="postgresql://username:password@localhost:5432/dbk_gaming?schema=public"

# 2. Generate Prisma client
npm run db:generate

# 3. Run migrations for PostgreSQL
npm run db:migrate:prod

Note: All migrations have been updated to use PostgreSQL-compatible syntax (TIMESTAMP instead of DATETIME, proper PRIMARY KEY constraints). The migration lock file specifies PostgreSQL as the provider.

Commands Not Appearing

Slash commands not showing:

  • Wait up to 1 hour for global commands to update
  • For instant updates, use guild-specific commands (modify client.js)
  • Check bot has applications.commands scope

Game Creation Fails

Error: "Missing Permissions"

  • Verify bot has Manage Roles and Manage Channels permissions
  • Ensure bot's role is higher than roles it's trying to create
  • Check channel permission overwrites

Rollback occurs:

  • Check logs for specific error message
  • Verify Discord API isn't rate limiting
  • Ensure all required fields in modal were filled correctly

Performance Issues

Bot is slow:

  • Check database connection (PostgreSQL recommended for production)
  • Monitor memory usage with pm2 monit
  • Review logs for repeated errors

Rate limit warnings:

  • Reduce frequency of operations
  • Implement caching (future feature)
  • Contact Discord for rate limit increase if legitimate use

Maintenance

Updating the Bot

# Pull latest changes
git pull origin main

# Install new dependencies
npm install

# Run new migrations
npm run db:migrate

# Restart bot
pm2 restart discord-bot  # or npm run dev

Backup Database

SQLite:

cp dev.db dev.db.backup

PostgreSQL:

pg_dump -U botuser discordbot > backup.sql

View Audit Logs

Use Prisma Studio:

npm run db:studio

Navigate to the AuditLog table to see all game operations.

Security Best Practices

  1. Never commit .env to Git (already in .gitignore)
  2. Use strong database passwords in production
  3. Rotate bot token if compromised
  4. Limit bot permissions to only what's needed
  5. Monitor audit logs for suspicious activity
  6. Keep dependencies updated: npm audit fix

Support

For issues or questions:

  1. Check this documentation
  2. Review logs: pm2 logs discord-bot or check console output
  3. Search existing issues on GitHub
  4. Create a new issue with:
    • Bot version
    • Error messages
    • Steps to reproduce

Next Steps