Lantern Discord Bot - Complete Guide

Standalone Discord bot for submitting feature requests and bug reports directly from Discord.

Status: ✅ Production Ready
Location: discord-bot/
Source: bot.js, register-commands.js

Overview
Features
Architecture
Environments
Setup Instructions
Local Testing
Deployment
Usage
GitHub Integration
Troubleshooting
Monitoring & Maintenance

Overview

The Discord bot enables team members and users to submit feature requests and bug reports using Discord slash commands. All submissions automatically:

Create GitHub issues with proper labels
Post to public Discord channels (#features or #bugs)
Notify admin team in private channel
Store data in Firestore for tracking
Integrate with GitHub Projects V2

Core Commands:

/feature - Submit a feature request
/bug - Report a bug
/mystatus - Check status of your submissions

Auto-Features:

Smart auto-prompts for regular messages
Multi-environment support (local, staging, production)
Rate limiting to prevent spam
Full audit trail in Firestore

Features

Smart Auto-Prompts

When users post a regular message in #features or #bugs (without using slash commands), the bot automatically:

Detects the message in submission channels
Replies with a helpful prompt explaining how to use the slash command
Shows benefits of using structured forms
Provides "Got it!" button to dismiss
Auto-deletes after 30 seconds to keep channels clean

Example:

User: "The app crashes when I click the profile button"

Bot: 💡 Quick Tip: Use /bug to submit
Hey @user! To submit a bug report, use the /bug slash command.

Why use slash commands?
✅ Structured form with all required details
✅ Automatic GitHub issue creation
✅ Tracked in our system
✅ You can check status with /mystatus

[Got it! button]

Command Discovery

Users discover commands by:

Typing / in Discord (autocomplete shows available commands)
Reading pinned messages in #features and #bugs
Checking channel topic descriptions

Architecture

Discord User
    ↓
/feature or /bug command
    ↓
Modal Form (Discord native)
    ↓
Bot validates input
    ↓
Creates GitHub issue + Firestore record
    ↓
Posts to #features or #bugs
    ↓
Notifies #admin-monitor
    ↓
User receives confirmation with GitHub link

Key Components:

bot.js - Main bot logic and command handlers
register-commands.js - Slash command registration
Discord.js - Bot framework
Firebase Admin SDK - Firestore integration
Octokit - GitHub API integration

Environments

Environment	Purpose	Guild ID	Database	Location	Config
Local Testing	Dev & feature testing	Test guild (separate)	Dev database	Your machine	`.env.testing`
Dev Deployed	Staging/QA	Dev guild	Dev database	Railway	Railway vars
Production	Live users	Prod guild	Prod database	Railway	Railway vars

Important: Each environment uses a separate Discord bot application and Firestore database.

Setup Instructions

Step 1: Create Discord Application

Go to Discord Developer Portal
Click "New Application"
Name it "Lantern Bot"
Go to "Bot" tab → Click "Add Bot"
Under "Privileged Gateway Intents", enable:
- ✅ Message Content Intent (required for auto-prompts)
- ✅ Server Members Intent
- ✅ Presence Intent
Click "Reset Token" → Copy and save securely

Step 2: Configure OAuth2 Scopes & Permissions

Go to "OAuth2" → "URL Generator"
Select scopes:
- ✅ bot
- ✅ applications.commands
Select bot permissions:
- ✅ Send Messages
- ✅ Embed Links
- ✅ Read Message History
- ✅ Use Slash Commands
- ✅ Manage Messages (for auto-prompts)
Copy generated URL
Open URL in browser → Select your server → Authorize

Step 3: Get Discord IDs

Enable Developer Mode:

Discord → User Settings → Advanced
Enable "Developer Mode"

Get IDs by right-clicking:

Server name → "Copy Server ID" → DISCORD_GUILD_ID
#features channel → "Copy ID" → DISCORD_FEATURE_CHANNEL_ID
#bugs channel → "Copy ID" → DISCORD_BUG_CHANNEL_ID
#admin-monitor channel → "Copy ID" → DISCORD_ADMIN_MONITOR_CHANNEL_ID

Step 4: Install Dependencies

bash

cd discord-bot
npm install

Dependencies:

discord.js - Discord bot framework
firebase-admin - Firestore access
@octokit/rest - GitHub API
dotenv - Environment variable loading

Step 5: Configure Environment Variables

For Local Development:

bash

cp .env.testing .env

Edit .env with your values:

bash

# Discord Configuration
DISCORD_BOT_TOKEN=your_bot_token_here
DISCORD_CLIENT_ID=your_application_id_here
DISCORD_GUILD_ID=your_server_id_here

# Discord Channel IDs
DISCORD_FEATURE_CHANNEL_ID=123456789012345678
DISCORD_BUG_CHANNEL_ID=123456789012345678
DISCORD_ADMIN_MONITOR_CHANNEL_ID=123456789012345678

# Firebase
FIREBASE_PROJECT_ID=lantern-app-dev

# GitHub
GITHUB_TOKEN=ghp_your_github_personal_access_token
GITHUB_REPO=cattreedev/lantern_app

# GitHub Project V2 (Optional - defaults provided)
GITHUB_PROJECT_NAME=Lantern App
GITHUB_MILESTONE_NAME=Prototype

Step 6: Firebase Service Account Setup (Choose One Method)

Method 1: File Path (Recommended for Local)

Go to Firebase Console → lantern-app-dev project
Project Settings → Service Accounts → "Generate New Private Key"
Save to ~/repos/secrets/firebase/lantern-app-dev-firebase-adminsdk-*.json

Add to .env:

bash

FIREBASE_SERVICE_ACCOUNT_PATH=~/repos/secrets/firebase/lantern-app-dev-firebase-adminsdk-*.json

Method 2: JSON String (Recommended for Deployment)

Get service account JSON (same as above)

Add to environment variables:

bash

FIREBASE_SERVICE_ACCOUNT_KEY='{"type":"service_account","project_id":"lantern-app-dev",...}'

The bot uses FIREBASE_SERVICE_ACCOUNT_KEY if available, otherwise falls back to file path.

⚠️ Never commit these files to Git! They're in .gitignore.

Step 7: Register Slash Commands

⚠️ Critical: Must be done BEFORE commands work in Discord (one-time setup).

bash

npm run register

Expected output:

Registering commands...
Successfully registered 3 application commands.

After this, /feature, /bug, and /mystatus will appear in Discord.

Local Testing

Testing Setup

For testing features locally without affecting production:

Create a separate test Discord server (or use existing test server)
Invite the bot to your test server
Create test channels (#features, #bugs, #admin-monitor)
Get test channel IDs and update .env.testing
Run locally with isolated test configuration

Testing Workflow

bash

cd discord-bot

# Use test configuration
cp .env.testing .env

# Install dependencies (if first time)
npm install

# Register slash commands (one-time)
npm run register

# Run bot locally
npm start

# In a separate terminal, test by running Discord commands
# When done, stop with Ctrl+C

What Happens During Local Testing

✅ Bot connects to test Discord guild (separate server)
✅ Issues created in GitHub go to Lantern App Testing project
✅ All data uses dev Firebase database (no production data touched)
✅ Milestones tagged with Testing label
✅ Production bot and guilds completely unaffected

Testing Checklist

After deployment, test:

Slash Commands
- Type / in any channel
- See /feature, /bug, /mystatus
- Run /feature and fill out modal
- Submit
Verify Results
- ✅ Message posted in #features channel
- ✅ Notification in #admin-monitor channel
- ✅ GitHub issue created with correct labels
- ✅ Firestore document created
Test Auto-Prompts
- Post a regular message in #features or #bugs
- Bot should reply with helpful prompt
- Click "Got it!" or wait 30 seconds
- Message should auto-delete
Test /mystatus
- Run /mystatus command
- Should show your submission history

Deployment

Option A: Local Testing (Quick Start)

bash

npm start

✅ Immediate, no cost, easy debugging
❌ Must keep computer on, not production-ready

Option B: Railway (Recommended for Production)

Railway is a platform-as-a-service with generous free tier.

Setup Steps

Create Account
- Go to https://railway.app
- Sign up with GitHub
Create New Project
- Click "New Project" → "Empty Project"
- Name it "lantern-discord-bot"
Deploy from GitHub
- In Railway project → "New" → "GitHub Repo"
- Select cattreedev/lantern_app
- Set root directory: discord-bot

Add Environment Variables In Railway dashboard → Variables:

DISCORD_BOT_TOKEN=your_token
DISCORD_CLIENT_ID=your_client_id
DISCORD_GUILD_ID=your_guild_id
DISCORD_FEATURE_CHANNEL_ID=123...
DISCORD_BUG_CHANNEL_ID=123...
DISCORD_ADMIN_MONITOR_CHANNEL_ID=123...
FIREBASE_PROJECT_ID=lantern-app-dev
FIREBASE_SERVICE_ACCOUNT_PATH=/app/service-account.json
GITHUB_TOKEN=ghp_...
GITHUB_REPO=cattreedev/lantern_app
GITHUB_PROJECT_NAME=Lantern App
GITHUB_MILESTONE_NAME=Prototype

Upload Service Account
- Railway → Settings → Add Secret File
- Name: service-account.json
- Upload Firebase service account JSON
- Path: /app/service-account.json
Deploy
- Railway auto-deploys. Monitor logs in dashboard.

Cost: Free tier gives 500 hours/month (sufficient for 24/7 bot). After: ~$5/month.

Option C: Self-Hosted Server (Advanced)

If you have a VPS or cloud VM:

bash

# On your server
git clone https://github.com/cattreedev/lantern_app.git
cd lantern_app/discord-bot
npm install

# Copy service account
scp ~/repos/secrets/firebase/lantern-app-dev-service-account.json \
    user@server:/path/to/lantern_app/discord-bot/

# Create .env file
nano .env  # paste environment variables

# Run with PM2 (keeps bot alive)
npm install -g pm2
pm2 start bot.js --name lantern-bot
pm2 save
pm2 startup  # enables autostart on reboot

Option D: Heroku (Alternative)

bash

heroku create lantern-discord-bot
heroku config:set DISCORD_BOT_TOKEN=xxx
heroku config:set FIREBASE_PROJECT_ID=lantern-app-dev
# ... set all other vars
git push heroku main

Note: Heroku no longer offers free tier. Railway or self-hosting recommended.

Usage

Submit a Feature Request

/feature

Modal fields:

Title (required, max 100 chars)
Description (required, max 1000 chars)
Use Case (optional, max 500 chars)
Priority (low/medium/high/critical)
Impact (individual/small-group/all-users)

Report a Bug

/bug

Same modal as feature requests, posted to #bugs channel instead.

Check Your Submissions

/mystatus

Shows your recent submissions with current status and GitHub links.

What Happens When You Submit

Modal submission → Bot validates input
GitHub issue created → Automatically formatted with labels
Public channel post → Appears in #features or #bugs
Admin notification → Posted to #admin-monitor (private)
User confirmation → You receive:
- Direct link to your submission
- Link to browse all issues
- Tip about using /mystatus

Channel Setup Guidance

#features Channel

Topic:

💡 Submit feature ideas using /feature command

Pinned message:

Welcome to #features! 🌟

Have an idea to improve Lantern? Submit it here!

**How to submit:**
1. Type `/feature` anywhere in this channel
2. Fill out the form that appears
3. Your request will be posted here and tracked on GitHub

**Need help?** Type `/mystatus` to see your submissions

#bugs Channel

Topic:

🐛 Report bugs using /bug command

Pinned message:

Welcome to #bugs! 🔧

Found a problem? Let us know!

**How to report:**
1. Type `/bug` anywhere in this channel
2. Describe the issue in the form
3. Your report will be posted here and tracked on GitHub

**Track your reports:** Use `/mystatus` command

GitHub Integration

GitHub Issue Format

Issues created with:

Labels: enhancement (for features) or bug, discord-submission
Milestone: Automatically added to "Prototype" milestone (configurable)
GitHub Project: Automatically added to "Lantern App" project (configurable)
Priority: Set in GitHub Projects V2 as P0 (critical), P1 (high), P2 (medium), or P3 (low)
Body: Discord username, type, priority, impact, description, Firestore ID

GitHub Projects V2 Integration

The bot integrates with GitHub Projects V2 to:

Add issues to project - Each new issue automatically added to configured project
Set priority field - Maps Discord priority to GitHub project priority (P0-P3)
Attach milestone - Adds issues to "Prototype" milestone by default

Requirements:

GitHub Project V2 must exist with name matching GITHUB_PROJECT_NAME (default: "Lantern App")
Project must have "Priority" single-select field with options: P0, P1, P2, P3
Milestone named GITHUB_MILESTONE_NAME (default: "Prototype") must exist in repository

Configuration:

bash

# Optional: Change project name (defaults to "Lantern App")
GITHUB_PROJECT_NAME=My Project

# Optional: Change milestone name (defaults to "Prototype")  
GITHUB_MILESTONE_NAME=MVP

GitHub Access for Users

Current Setup: Private Repository with Team Access

The repository is private, so users need to be added to the GitHub organization with "Read" access.

What users CAN do (with Read access):

✅ View all issues
✅ Browse code (read-only)
✅ See issue status and comments
✅ Comment on issues

What users CANNOT do:

❌ Push code changes (requires Write permissions)
❌ Merge pull requests
❌ Modify repository settings

Setting Up Team Access:

Add employees to your GitHub organization
Grant "Read" access to the repository
Non-technical staff can safely view but cannot modify code

Troubleshooting

Bot doesn't respond to commands

Check:

Bot is online (npm start running or Railway shows "running")
Slash commands are registered (npm run register)
Bot has permission to view and send messages in channels
DISCORD_GUILD_ID matches your server
Bot is in the server and has proper role permissions

Fix:

bash

# Re-register commands
npm run register

# Restart bot
npm start  # local
# or Railway: redeploy

"Invalid interaction application command" error

Re-run npm run register
Wait a few minutes for Discord to propagate changes
Restart bot

Slash commands don't appear in Discord

Verify bot has applications.commands scope (see OAuth2 setup)
Run npm run register again
Wait up to 1 hour for global propagation
Check bot has permission in channels

"Missing Access" error

Verify bot has permissions in channels
Check channel IDs in .env are correct
Ensure bot role is above channel permission overrides

GitHub issue creation fails

Verify GITHUB_TOKEN is valid:
- Go to GitHub → Settings → Developer settings → Tokens
- Ensure token has repo scope for private repositories
- Check token hasn't expired
Check GITHUB_REPO format: owner/repo (e.g., cattreedev/lantern_app)
Verify rate limits: https://api.github.com/rate_limit

Firebase errors

Verify service account JSON path is correct
Check service account has Firestore permissions
Ensure FIREBASE_PROJECT_ID matches your project
If using file path, check file exists at path

Auto-prompts don't work

Enable "Message Content Intent" in Discord Developer Portal
Bot needs permission to "Manage Messages" in channels
Verify auto-prompt code is not disabled in bot.js

Bot goes offline

Check Railway dashboard for errors
Verify all environment variables are set correctly
Check GitHub Actions workflows for deployment status
Monitor PM2 logs: pm2 logs lantern-bot

Monitoring & Maintenance

Checking Bot Status

Local:

Check terminal output where npm start is running

Railway:

Dashboard → Logs tab shows real-time logs
Deployments tab shows deployment history

PM2 (Self-hosted):

bash

pm2 status
pm2 logs lantern-bot
pm2 restart lantern-bot

Regular Maintenance

Monthly:

Verify Discord bot token is still valid
Check GitHub token hasn't expired
Review Firebase quotas and costs

On Channel Changes:

Update channel IDs in environment variables
Restart bot or redeploy

Updating the Bot:

Local:

bash

git pull
npm install
npm run register
npm start

Railway:

bash

git push  # Auto-deploys

PM2:

bash

cd discord-bot
git pull
npm install
npm run register
pm2 restart lantern-bot

Backup & Recovery

Firestore automatically stores all submissions. No additional backup needed for Discord bot. However:

Keep .env file safe (in .gitignore, never committed)
Store Firebase service account JSON in secure location
Keep GitHub token in secure location

Analytics & Monitoring

Track submissions via Firestore:

Collection: discord_submissions
Document: One per submission with timestamp, user, type, status
Query: Filter by date, type, priority, status

Security Checklist

✅ .env file is in .gitignore (never committed)
✅ Discord bot token kept secure
✅ GitHub token has minimal scope (repo only)
✅ Firebase service account JSON protected
✅ Admin channel is private (only team members can view)
✅ Rate limiting enabled (prevents spam)
✅ Input validation on all fields
✅ User submissions tracked by Discord ID

FAQ

Q: Do I need to deploy to both dev and prod?
A: Yes, if you want separate environments. Use different .env files pointing to lantern-app-dev and lantern-app-prod Firebase projects.

Q: Can I use one bot for both environments?
A: No. Create separate bot applications for dev and prod to avoid mixing data.

Q: How much does Railway cost?
A: Free tier gives 500 hours/month. After that, ~$5/month for 24/7 uptime.

Q: What happens if the bot goes offline?
A: Users cannot use slash commands temporarily. When bot comes back online, commands resume. Firestore still stores any submissions made through web forms.

Q: How do I update slash commands?
A: Edit register-commands.js, then run npm run register again.

Q: Can I add more commands?
A: Yes, add to register-commands.js and bot.js, then run npm run register.

Q: What if I have more than 3 channels?
A: The bot currently supports 3 channels (features, bugs, admin-monitor). To add more, modify bot.js and add corresponding environment variables.

Files

discord-bot/
├── bot.js                    # Main bot implementation
├── register-commands.js      # Slash command registration
├── package.json             # Dependencies
├── .env.example             # Environment template
├── .env.testing             # Test environment template
├── .gitignore              # Git ignore patterns
└── README.md               # Quick reference

Summary Checklist

After deploying, you should have:

✅ Bot online in Discord (green dot)
✅ Slash commands /feature, /bug, /mystatus available
✅ Auto-prompts working for regular messages
✅ GitHub issues created with correct labels
✅ Priorities mapped to P0-P3 for GitHub Projects
✅ Submissions posted to #features and #bugs channels
✅ Admin notifications in #admin-monitor channel
✅ Firestore storing all submissions
✅ End-to-end tested

Total setup time: ~40 minutes

For additional help, contact the development team.

Lantern Discord Bot - Complete Guide ​

Table of Contents ​

Overview ​

Features ​

Smart Auto-Prompts ​

Command Discovery ​

Architecture ​

Environments ​

Setup Instructions ​

Step 1: Create Discord Application ​

Step 2: Configure OAuth2 Scopes & Permissions ​

Step 3: Get Discord IDs ​

Step 4: Install Dependencies ​

Step 5: Configure Environment Variables ​

Step 6: Firebase Service Account Setup (Choose One Method) ​

Step 7: Register Slash Commands ​

Local Testing ​

Testing Setup ​

Testing Workflow ​

What Happens During Local Testing ​

Testing Checklist ​

Deployment ​

Option A: Local Testing (Quick Start) ​

Option B: Railway (Recommended for Production) ​

Setup Steps ​

Option C: Self-Hosted Server (Advanced) ​

Option D: Heroku (Alternative) ​

Usage ​

Submit a Feature Request ​

Report a Bug ​

Check Your Submissions ​

What Happens When You Submit ​

Channel Setup Guidance ​

GitHub Integration ​

GitHub Issue Format ​

GitHub Projects V2 Integration ​

GitHub Access for Users ​

Troubleshooting ​

Bot doesn't respond to commands ​

"Invalid interaction application command" error ​

Slash commands don't appear in Discord ​

"Missing Access" error ​

GitHub issue creation fails ​

Firebase errors ​

Auto-prompts don't work ​

Bot goes offline ​

Monitoring & Maintenance ​

Checking Bot Status ​

Regular Maintenance ​

Backup & Recovery ​

Analytics & Monitoring ​

Security Checklist ​

FAQ ​

Related Documentation ​

Files ​

Summary Checklist ​

Lantern Discord Bot - Complete Guide

Table of Contents

Overview

Features

Smart Auto-Prompts

Command Discovery

Architecture

Environments

Setup Instructions

Step 1: Create Discord Application

Step 2: Configure OAuth2 Scopes & Permissions

Step 3: Get Discord IDs

Step 4: Install Dependencies

Step 5: Configure Environment Variables

Step 6: Firebase Service Account Setup (Choose One Method)

Step 7: Register Slash Commands

Local Testing

Testing Setup

Testing Workflow

What Happens During Local Testing

Testing Checklist

Deployment

Option A: Local Testing (Quick Start)

Option B: Railway (Recommended for Production)

Setup Steps

Option C: Self-Hosted Server (Advanced)

Option D: Heroku (Alternative)

Usage

Submit a Feature Request

Report a Bug

Check Your Submissions

What Happens When You Submit

Channel Setup Guidance

GitHub Integration

GitHub Issue Format

GitHub Projects V2 Integration

GitHub Access for Users

Troubleshooting

Bot doesn't respond to commands

"Invalid interaction application command" error

Slash commands don't appear in Discord

"Missing Access" error

GitHub issue creation fails

Firebase errors

Auto-prompts don't work

Bot goes offline

Monitoring & Maintenance

Checking Bot Status

Regular Maintenance

Backup & Recovery

Analytics & Monitoring

Security Checklist

FAQ

Related Documentation

Files

Summary Checklist