Discord Linked Roles Bot

A Discord bot that manages linked roles with a dynamic admin panel. Users can be assigned custom role requirements that automatically grant Discord server roles when they verify. Built for self-hosting.

Features

• Dynamic Role Management: Create, edit, and delete role requirements through the admin panel
• Admin Interface: Web-based panel for managing users and roles (restricted to users with "Manage Server" permission)
• Automatic Discord Sync: Role definitions automatically sync with Discord API
• User Authentication: OAuth2 flow for users to verify and claim assigned roles
• Flexible Assignment: Assign multiple roles to users, roles grant automatically when verified
• Session Management: Secure admin sessions with 1-hour expiry and logout functionality
• Reverse Proxy Ready: Works seamlessly behind Caddyserver, Nginx, or other proxies
• File-Based Storage: Simple JSON file storage for roles and user data

Prerequisites

• Node.js 18 or higher
• A Discord application with bot token
• Discord guild (server) ID
• Reverse proxy with HTTPS (recommended: Caddyserver)

Setup

1. Clone and Install

git clone https://github.com/ComputerEndProgram/LR-Bot.git
cd LR-Bot
npm install

2. Configure Discord Application

In the Discord Developer Portal:

1. Create a new application
2. Go to OAuth2 → Redirects and add BOTH of these redirect URIs:
   • https://yourdomain.com/discord-oauth-callback (for user verification)
   • https://yourdomain.com/admin-oauth-callback (for admin login)
3. Note down your:
   • Application ID (Client ID)
   • Client Secret
   • Public Key
4. Go to Bot section and copy your Bot Token
5. Under Linked Roles, set the verification URL to: https://yourdomain.com/verified-role

3. Environment Configuration

Create a .env file based on example.env:

cp example.env .env

Required fields:

• DISCORD_TOKEN - Your Discord bot token
• DISCORD_CLIENT_ID - Your Discord application client ID
• DISCORD_CLIENT_SECRET - Your Discord application client secret
• DISCORD_PUBLIC_KEY - Your Discord application public key
• DISCORD_REDIRECT_URI - https://yourdomain.com/discord-oauth-callback
• VERIFICATION_URL - https://yourdomain.com/verified-role
• COOKIE_SECRET - Random 32+ character string for cookie signing
• GUILD_ID - Your Discord server ID
• PORT - Port for the server (default: 3000)
• STORAGE_DIR - Data directory (default: ./data)

4. Build and Initialize

# Build the project
npm run build

# Start the server
npm start

5. Configure Discord Server Roles

1. Go to your Discord Server Settings → Roles
2. Create or edit a role (e.g., "Admin")
3. Click Links → Add a requirement
4. Select your bot application
5. Set requirement: "Admin must be true" (or whatever role you defined)
6. Repeat for other roles (Moderator, etc.)

Admin Panel Usage

Access

Navigate to https://yourdomain.com/admin and authenticate with Discord. You must have "Manage Server" permission.

Manage Roles Tab

• Add roles: Enter a display name and description, key is auto-generated
• Delete roles: Remove role definitions (syncs with Discord immediately)
• Examples: Admin, Moderator, VIP, Supporter, etc.

Manage Users Tab

• Add users: Enter Discord User ID, check which roles they can claim
• Edit users: Click Edit to modify assigned roles
• Delete users: Remove user and revoke their access

Logout

Click the red "Logout" button in the top-right. Sessions auto-expire after 1 hour.

User Verification Flow

1. Users visit https://yourdomain.com/verified-role
2. They authenticate with Discord (OAuth2)
3. Bot checks what roles you assigned them
4. Bot pushes role data to Discord
5. Discord automatically grants the corresponding server roles
6. User sees confirmation showing which roles they received

Available Scripts

npm run build          # Build TypeScript to JavaScript
npm start              # Start the production server
npm run dev            # Start development server with auto-reload

# Utility scripts
node ./build/src/tools/init-default-roles.js   # Register default roles with Discord
node ./build/src/tools/clear-commands.js       # Remove slash commands (if any exist)

Reverse Proxy Configuration

The bot runs on localhost:3000 and should be accessed through HTTPS reverse proxy.

Caddyfile Example:

lrb.yourdomain.com {
    reverse_proxy localhost:3000
}

Nginx Example:

server {
    listen 443 ssl http2;
    server_name lrb.yourdomain.com;
    
    # SSL configuration here
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Production Deployment

Use PM2 for process management:

npm install -g pm2
pm2 start npm --name "lr-bot" -- start
pm2 save
pm2 startup

This ensures:

• Auto-restart on crashes
• Start on system boot
• Easy log management with pm2 logs lr-bot

Data Storage

Data is stored in JSON files in the ./data directory (or STORAGE_DIR):

• role-definitions - Role definitions synced with Discord
• user-roles-{userId} - User role assignments
• discord-{userId} - OAuth tokens for users

Important: Back up the data directory regularly!

Troubleshooting

Slash commands still showing

node ./build/src/tools/clear-commands.js

Wait 1-5 minutes and restart Discord.

Cookie/session issues

• Ensure COOKIE_SECRET is set and remains constant
• Check that your reverse proxy forwards HTTPS correctly
• Admin sessions expire after 1 hour - re-authenticate

Roles not syncing

• Check bot has proper permissions in Discord server
• Verify GUILD_ID is correct
• Check admin panel "Manage Roles" tab shows your roles
• Ensure role definitions exist before assigning to users

License