docs: Create Discord Bot Admin Panel guide + update Subscription Automation Guide
CREATED: docs/guides/discord-bot-admin-panel.md (new comprehensive guide) - Complete implementation guide for web-based admin panel - Architecture section (credits Gemini for design decisions) - Security-first approach (dedicated firefrost-bot user, Discord OAuth2) - Zero-downtime config updates (in-memory + atomic disk writes) - Holly's usage guide (how to update role IDs via web interface) - Full troubleshooting section - Maintenance procedures Key Features Documented: - Discord OAuth2 authentication (no passwords) - Whitelist authorization (Holly + Michael only) - Role ID validation (regex + Discord API verification) - Atomic file writes with backup strategy - In-memory config updates (no bot restart needed) - Audit logging to Discord channel - HTTPS via Nginx + Let's Encrypt Status: Awaiting backend/frontend code from Gemini UPDATED: docs/guides/subscription-automation-guide.md - Task 9 rewritten to reference new admin panel guide - Added Option A (admin panel) vs Option B (manual SSH) paths - Removed SSH instructions for Holly (she won't have access) - Removed bot token from credentials file (security) - Updated Holly's tasks section with admin panel option - Preserved manual method as fallback Why These Changes: - Admin panel gives Holly independence (no waiting for Michael) - Cleaner separation of concerns (setup vs usage) - Security improvement (no SSH access needed for Holly) - Better documentation structure (1000+ line guide split logically) Architecture Credit: Gemini (Google AI) consultation on March 23, 2026 Chronicler #40
This commit is contained in:
Claude
930
docs/guides/discord-bot-admin-panel.md
Normal file
930
docs/guides/discord-bot-admin-panel.md
Normal file
@@ -0,0 +1,930 @@
|
||||
# Discord Bot Admin Panel - Implementation Guide
|
||||
|
||||
**Version:** 1.0
|
||||
**Date:** March 23, 2026
|
||||
**Author:** Chronicler #40 (with architecture by Gemini/Google AI)
|
||||
**Audience:** Michael (setup) + Holly (usage)
|
||||
**Purpose:** Web-based admin panel for managing Discord bot role mappings
|
||||
|
||||
---
|
||||
|
||||
## 📋 TABLE OF CONTENTS
|
||||
|
||||
1. [Overview](#overview)
|
||||
2. [Architecture](#architecture)
|
||||
3. [Why We Built This](#why-we-built-this)
|
||||
4. [Part 1: Prerequisites](#part-1-prerequisites)
|
||||
5. [Part 2: Create Dedicated Bot User](#part-2-create-dedicated-bot-user)
|
||||
6. [Part 3: Set Up Discord OAuth2 Application](#part-3-set-up-discord-oauth2-application)
|
||||
7. [Part 4: Deploy Backend Code](#part-4-deploy-backend-code)
|
||||
8. [Part 5: Deploy Frontend Code](#part-5-deploy-frontend-code)
|
||||
9. [Part 6: Configure Nginx & SSL](#part-6-configure-nginx-ssl)
|
||||
10. [Part 7: Holly's Usage Guide](#part-7-hollys-usage-guide)
|
||||
11. [Testing & Verification](#testing-verification)
|
||||
12. [Troubleshooting](#troubleshooting)
|
||||
13. [Maintenance](#maintenance)
|
||||
|
||||
---
|
||||
|
||||
## 🎯 OVERVIEW
|
||||
|
||||
### What Is This?
|
||||
|
||||
A secure web-based admin panel at `https://discord-bot.firefrostgaming.com/admin` where Holly can:
|
||||
- Log in using her Discord account (no passwords to remember)
|
||||
- Update Discord role mappings for all 10 subscription tiers
|
||||
- View bot status and recent webhook events
|
||||
- Save changes instantly (no SSH access needed)
|
||||
|
||||
### The Problem We Solved
|
||||
|
||||
**Before:**
|
||||
- Discord bot role mappings were hardcoded in `bot.js`
|
||||
- Holly had to give Michael the role IDs via Discord/email
|
||||
- Michael had to SSH into Command Center to update the file
|
||||
- Michael had to restart the bot manually
|
||||
- Holly waited for Michael's availability
|
||||
|
||||
**After:**
|
||||
- Holly logs into web panel with Discord OAuth
|
||||
- Holly updates role IDs in a simple form
|
||||
- Changes save instantly (in-memory update, no restart)
|
||||
- Config written atomically to disk with backup
|
||||
- Role IDs validated against Discord API before saving
|
||||
- Audit log posted to Discord channel
|
||||
|
||||
**Result:** Holly is independent, Michael isn't the bottleneck.
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ ARCHITECTURE
|
||||
|
||||
### Design Principles (Thanks to Gemini)
|
||||
|
||||
This architecture was designed in consultation with Gemini (Google AI) and follows production best practices:
|
||||
|
||||
**1. Security First**
|
||||
- Dedicated Linux user (`firefrost-bot`) - NOT root
|
||||
- Discord OAuth2 authentication (no password management)
|
||||
- Whitelist authorization (only Holly + Michael's Discord IDs)
|
||||
- HTTPS via Nginx + Let's Encrypt
|
||||
- CSRF protection on admin forms
|
||||
|
||||
**2. Zero Downtime**
|
||||
- Configuration loaded into memory on startup
|
||||
- Updates modify in-memory config immediately
|
||||
- No bot restart required
|
||||
- Atomic disk writes (no corruption)
|
||||
- Backup of last-known-good config
|
||||
|
||||
**3. Simplicity**
|
||||
- Single Node.js/Express app (webhook + admin in one)
|
||||
- JSON config file (no database needed for 10 key-value pairs)
|
||||
- Validation: Regex check + Discord API verification
|
||||
- In-memory webhook logs (last 50 events, rotating)
|
||||
|
||||
**4. Auditability**
|
||||
- Discord `#bot-audit-logs` channel for config changes
|
||||
- Backup config file for disaster recovery
|
||||
- Systemd journal logs everything
|
||||
|
||||
### Tech Stack
|
||||
|
||||
**Backend:**
|
||||
- Node.js 18+
|
||||
- Express.js (web server)
|
||||
- discord.js (Discord API)
|
||||
- Passport.js (Discord OAuth2)
|
||||
- write-file-atomic (safe config saves)
|
||||
|
||||
**Frontend:**
|
||||
- Simple HTML/CSS/JavaScript
|
||||
- Vanilla JS with `fetch()` API
|
||||
- No frameworks (keep it simple for Holly)
|
||||
- Fire/Frost branding
|
||||
|
||||
**Infrastructure:**
|
||||
- Command Center (63.143.34.217)
|
||||
- Nginx reverse proxy
|
||||
- Let's Encrypt SSL
|
||||
- Systemd service
|
||||
|
||||
---
|
||||
|
||||
## 🤔 WHY WE BUILT THIS
|
||||
|
||||
### Holly's Perspective
|
||||
|
||||
**Before:**
|
||||
- "I created Discord roles, now I need to wait for Michael to update the bot."
|
||||
- "I want to test if the role IDs work, but I can't update them myself."
|
||||
- "If I make a typo in the role ID I give Michael, we have to repeat the whole process."
|
||||
|
||||
**After:**
|
||||
- "I created Discord roles, I'll paste the IDs into the admin panel."
|
||||
- "I can test immediately - if a role ID is wrong, the panel tells me before saving."
|
||||
- "I'm independent - I can iterate and test without waiting."
|
||||
|
||||
### Michael's Perspective
|
||||
|
||||
**Before:**
|
||||
- "Holly needs role IDs updated. I have to stop what I'm doing, SSH in, edit the file, restart the bot."
|
||||
- "If I make a typo, Holly has to tell me, and I have to repeat the process."
|
||||
- "I'm the single point of failure for a 5-minute task."
|
||||
|
||||
**After:**
|
||||
- "Holly handles her own role mappings. I only get involved if something breaks."
|
||||
- "The admin panel validates role IDs before saving, so typos get caught automatically."
|
||||
- "I set this up once, Holly uses it forever."
|
||||
|
||||
---
|
||||
|
||||
## ✅ PART 1: PREREQUISITES
|
||||
|
||||
### Before You Start
|
||||
|
||||
**On Command Center (63.143.34.217):**
|
||||
- [ ] Discord bot already running (from Subscription Automation Guide Part 1)
|
||||
- [ ] Bot accessible at `https://webhook.firefrostgaming.com/webhook/paymenter`
|
||||
- [ ] Node.js 18+ installed
|
||||
- [ ] Nginx installed and configured
|
||||
- [ ] SSL certificate (Let's Encrypt)
|
||||
|
||||
**Discord Requirements:**
|
||||
- [ ] Discord bot application exists
|
||||
- [ ] Bot is in Firefrost Gaming Discord server
|
||||
- [ ] You have bot token
|
||||
- [ ] You have Guild ID (server ID)
|
||||
- [ ] You have Holly's Discord user ID
|
||||
- [ ] You have Michael's Discord user ID
|
||||
|
||||
**DNS Configuration:**
|
||||
- [ ] `discord-bot.firefrostgaming.com` A record → 63.143.34.217
|
||||
- [ ] Cloudflare proxy: OFF (orange cloud = OFF)
|
||||
|
||||
---
|
||||
|
||||
## 🔧 PART 2: CREATE DEDICATED BOT USER
|
||||
|
||||
**CRITICAL SECURITY FIX: Do NOT run the bot as root.**
|
||||
|
||||
Running Node.js as root is a major security risk. If any npm package has a vulnerability, an attacker gets full control of Command Center.
|
||||
|
||||
### Step 1: Create System User
|
||||
|
||||
SSH to Command Center:
|
||||
|
||||
```bash
|
||||
ssh root@63.143.34.217
|
||||
```
|
||||
|
||||
Create dedicated user:
|
||||
|
||||
```bash
|
||||
# Create system user (no login shell, no home directory login)
|
||||
sudo useradd -r -s /bin/false firefrost-bot
|
||||
|
||||
# Verify user was created
|
||||
id firefrost-bot
|
||||
# Should show: uid=... gid=... groups=...
|
||||
```
|
||||
|
||||
### Step 2: Transfer Ownership
|
||||
|
||||
Transfer bot directory to new user:
|
||||
|
||||
```bash
|
||||
# Change ownership of bot directory
|
||||
sudo chown -R firefrost-bot:firefrost-bot /opt/firefrost-discord-bot
|
||||
|
||||
# Verify permissions
|
||||
ls -la /opt/firefrost-discord-bot
|
||||
# Should show: drwxr-xr-x ... firefrost-bot firefrost-bot
|
||||
```
|
||||
|
||||
### Step 3: Update Systemd Service
|
||||
|
||||
Edit the service file:
|
||||
|
||||
```bash
|
||||
sudo nano /etc/systemd/system/firefrost-discord-bot.service
|
||||
```
|
||||
|
||||
Update these lines:
|
||||
|
||||
```ini
|
||||
[Service]
|
||||
User=firefrost-bot
|
||||
Group=firefrost-bot
|
||||
WorkingDirectory=/opt/firefrost-discord-bot
|
||||
ExecStart=/usr/bin/node /opt/firefrost-discord-bot/bot.js
|
||||
Restart=always
|
||||
RestartSec=10
|
||||
|
||||
# Environment
|
||||
Environment=NODE_ENV=production
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
Reload and restart:
|
||||
|
||||
```bash
|
||||
# Reload systemd
|
||||
sudo systemctl daemon-reload
|
||||
|
||||
# Restart bot with new user
|
||||
sudo systemctl restart firefrost-discord-bot
|
||||
|
||||
# Verify it's running
|
||||
sudo systemctl status firefrost-discord-bot
|
||||
# Should show: Active: active (running)
|
||||
|
||||
# Check logs
|
||||
sudo journalctl -u firefrost-discord-bot -n 50
|
||||
# Should show no permission errors
|
||||
```
|
||||
|
||||
**If you see permission errors:** Fix file permissions and retry.
|
||||
|
||||
---
|
||||
|
||||
## 🔐 PART 3: SET UP DISCORD OAUTH2 APPLICATION
|
||||
|
||||
### Step 1: Discord Developer Portal
|
||||
|
||||
1. Go to: https://discord.com/developers/applications
|
||||
2. Select your **Firefrost Subscription Manager** bot application
|
||||
3. Click **OAuth2** in left sidebar
|
||||
|
||||
### Step 2: Add Redirect URLs
|
||||
|
||||
Under **Redirects**, add:
|
||||
|
||||
**For local testing (optional):**
|
||||
```
|
||||
http://localhost:3100/auth/discord/callback
|
||||
```
|
||||
|
||||
**For production (required):**
|
||||
```
|
||||
https://discord-bot.firefrostgaming.com/auth/discord/callback
|
||||
```
|
||||
|
||||
Click **Save Changes**.
|
||||
|
||||
### Step 3: Copy Credentials
|
||||
|
||||
**Copy these values (you'll need them for .env file):**
|
||||
|
||||
- **Client ID:** (18-digit number under OAuth2 General)
|
||||
- **Client Secret:** Click "Reset Secret" → Copy the new secret
|
||||
|
||||
**⚠️ IMPORTANT:** The Client Secret only shows once. Copy it immediately and save to Vaultwarden.
|
||||
|
||||
### Step 4: Get Discord User IDs
|
||||
|
||||
**Holly's Discord ID:**
|
||||
1. In Discord, right-click Holly's username
|
||||
2. Click "Copy User ID"
|
||||
3. Paste somewhere safe (e.g., `123456789012345678`)
|
||||
|
||||
**Michael's Discord ID:**
|
||||
1. Same process for Michael's account
|
||||
2. Paste somewhere safe
|
||||
|
||||
**Note:** If "Copy User ID" doesn't appear, enable Developer Mode:
|
||||
- Discord Settings → Advanced → Developer Mode (toggle ON)
|
||||
|
||||
---
|
||||
|
||||
## 💻 PART 4: DEPLOY BACKEND CODE
|
||||
|
||||
### Step 1: Install Dependencies
|
||||
|
||||
SSH to Command Center:
|
||||
|
||||
```bash
|
||||
ssh root@63.143.34.217
|
||||
cd /opt/firefrost-discord-bot
|
||||
```
|
||||
|
||||
Install required npm packages:
|
||||
|
||||
```bash
|
||||
npm install express express-session passport passport-discord write-file-atomic dotenv
|
||||
```
|
||||
|
||||
### Step 2: Create .env File
|
||||
|
||||
Create environment variables file:
|
||||
|
||||
```bash
|
||||
nano /opt/firefrost-discord-bot/.env
|
||||
```
|
||||
|
||||
Add these values (replace with your actual credentials):
|
||||
|
||||
```env
|
||||
# Discord Bot
|
||||
DISCORD_TOKEN=your_bot_token_here
|
||||
DISCORD_CLIENT_ID=your_oauth_client_id_here
|
||||
DISCORD_CLIENT_SECRET=your_oauth_client_secret_here
|
||||
GUILD_ID=your_discord_server_id_here
|
||||
|
||||
# OAuth2
|
||||
CALLBACK_URL=https://discord-bot.firefrostgaming.com/auth/discord/callback
|
||||
|
||||
# Session
|
||||
SESSION_SECRET=generate_a_very_long_random_string_here
|
||||
|
||||
# Authorization
|
||||
ALLOWED_ADMINS=HOLLYS_DISCORD_ID,MICHAELS_DISCORD_ID
|
||||
|
||||
# Environment
|
||||
NODE_ENV=production
|
||||
```
|
||||
|
||||
**Generate SESSION_SECRET:**
|
||||
|
||||
```bash
|
||||
# Generate random 64-character string
|
||||
openssl rand -base64 48
|
||||
```
|
||||
|
||||
Copy the output and use it for `SESSION_SECRET`.
|
||||
|
||||
**Save and exit:** `Ctrl+X`, `Y`, `Enter`
|
||||
|
||||
**Set file permissions:**
|
||||
|
||||
```bash
|
||||
# .env file should only be readable by firefrost-bot user
|
||||
chmod 600 /opt/firefrost-discord-bot/.env
|
||||
chown firefrost-bot:firefrost-bot /opt/firefrost-discord-bot/.env
|
||||
```
|
||||
|
||||
### Step 3: Backend Code Implementation
|
||||
|
||||
**⚠️ WAITING ON GEMINI:** The complete backend code is being provided by Gemini (Google AI).
|
||||
|
||||
**Once received, the backend code will include:**
|
||||
- Express server setup
|
||||
- Discord OAuth2 authentication
|
||||
- In-memory config management
|
||||
- Atomic file writes with backup
|
||||
- Role ID validation (regex + Discord API)
|
||||
- Admin API endpoints
|
||||
- Webhook logging
|
||||
|
||||
**File will be:** `/opt/firefrost-discord-bot/bot.js` (replaces existing file)
|
||||
|
||||
**Status:** Awaiting Gemini's response with complete backend implementation.
|
||||
|
||||
---
|
||||
|
||||
## 🎨 PART 5: DEPLOY FRONTEND CODE
|
||||
|
||||
**⚠️ WAITING ON GEMINI:** The frontend HTML/CSS/JS is being written by Gemini (Google AI).
|
||||
|
||||
**Once received, the frontend will include:**
|
||||
- Discord OAuth login flow
|
||||
- Role mapping management form (10 product → role ID pairs)
|
||||
- Save functionality with validation feedback
|
||||
- Bot status display
|
||||
- Recent webhook logs table
|
||||
- Logout button
|
||||
- Fire/Frost branding
|
||||
|
||||
**Files will be created in:** `/opt/firefrost-discord-bot/public/`
|
||||
|
||||
**Status:** Awaiting Gemini's response with complete frontend implementation.
|
||||
|
||||
---
|
||||
|
||||
## 🌐 PART 6: CONFIGURE NGINX & SSL
|
||||
|
||||
### Step 1: Create Nginx Configuration
|
||||
|
||||
Create new site config:
|
||||
|
||||
```bash
|
||||
sudo nano /etc/nginx/sites-available/discord-bot-admin
|
||||
```
|
||||
|
||||
Add this configuration:
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 80;
|
||||
server_name discord-bot.firefrostgaming.com;
|
||||
|
||||
# Redirect HTTP to HTTPS
|
||||
return 301 https://$server_name$request_uri;
|
||||
}
|
||||
|
||||
server {
|
||||
listen 443 ssl http2;
|
||||
server_name discord-bot.firefrostgaming.com;
|
||||
|
||||
# SSL Configuration (Let's Encrypt)
|
||||
ssl_certificate /etc/letsencrypt/live/discord-bot.firefrostgaming.com/fullchain.pem;
|
||||
ssl_certificate_key /etc/letsencrypt/live/discord-bot.firefrostgaming.com/privkey.pem;
|
||||
include /etc/letsencrypt/options-ssl-nginx.conf;
|
||||
ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
|
||||
|
||||
# Security Headers
|
||||
add_header X-Frame-Options "SAMEORIGIN" always;
|
||||
add_header X-Content-Type-Options "nosniff" always;
|
||||
add_header X-XSS-Protection "1; mode=block" always;
|
||||
|
||||
# Proxy to Node.js app
|
||||
location / {
|
||||
proxy_pass http://localhost:3100;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection 'upgrade';
|
||||
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;
|
||||
proxy_cache_bypass $http_upgrade;
|
||||
|
||||
# Timeouts
|
||||
proxy_connect_timeout 60s;
|
||||
proxy_send_timeout 60s;
|
||||
proxy_read_timeout 60s;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Save and exit.
|
||||
|
||||
### Step 2: Enable Site
|
||||
|
||||
```bash
|
||||
# Create symlink to enable site
|
||||
sudo ln -s /etc/nginx/sites-available/discord-bot-admin /etc/nginx/sites-enabled/
|
||||
|
||||
# Test Nginx configuration
|
||||
sudo nginx -t
|
||||
# Should show: syntax is okay, test is successful
|
||||
|
||||
# Reload Nginx
|
||||
sudo systemctl reload nginx
|
||||
```
|
||||
|
||||
### Step 3: Obtain SSL Certificate
|
||||
|
||||
```bash
|
||||
# Install certbot if not already installed
|
||||
sudo apt install certbot python3-certbot-nginx -y
|
||||
|
||||
# Obtain certificate
|
||||
sudo certbot --nginx -d discord-bot.firefrostgaming.com
|
||||
|
||||
# Follow prompts:
|
||||
# - Enter email address
|
||||
# - Agree to Terms of Service
|
||||
# - Choose: Redirect HTTP to HTTPS (option 2)
|
||||
```
|
||||
|
||||
**Certbot will automatically:**
|
||||
- Obtain SSL certificate
|
||||
- Configure Nginx SSL settings
|
||||
- Set up auto-renewal
|
||||
|
||||
### Step 4: Verify SSL
|
||||
|
||||
Test in browser:
|
||||
|
||||
```
|
||||
https://discord-bot.firefrostgaming.com
|
||||
```
|
||||
|
||||
Should show valid SSL certificate (green lock icon).
|
||||
|
||||
---
|
||||
|
||||
## 👥 PART 7: HOLLY'S USAGE GUIDE
|
||||
|
||||
**This section is for Holly - how to use the admin panel.**
|
||||
|
||||
### When You Need This
|
||||
|
||||
Use the admin panel when:
|
||||
- ✅ You've created new Discord roles
|
||||
- ✅ You need to update role IDs in the bot
|
||||
- ✅ You want to test if role IDs are correct
|
||||
- ✅ You need to change a role mapping
|
||||
|
||||
### Step 1: Log In
|
||||
|
||||
1. Open browser (Chrome, Firefox, Edge)
|
||||
2. Go to: `https://discord-bot.firefrostgaming.com/admin`
|
||||
3. Click **"Login with Discord"** button
|
||||
4. Discord OAuth page appears
|
||||
5. Click **"Authorize"**
|
||||
6. You're redirected back to admin panel
|
||||
|
||||
**Note:** You only need to log in once - browser remembers you via session cookie.
|
||||
|
||||
### Step 2: View Current Mappings
|
||||
|
||||
Admin panel shows current role mappings:
|
||||
|
||||
```
|
||||
Product 2 (The Awakened): [123456789012345678]
|
||||
Product 3 (Fire Elemental): [234567890123456789]
|
||||
Product 4 (Frost Elemental): [345678901234567890]
|
||||
...
|
||||
```
|
||||
|
||||
These are the Discord role IDs currently in use.
|
||||
|
||||
### Step 3: Update Role IDs
|
||||
|
||||
**When you create Discord roles:**
|
||||
|
||||
1. In Discord, go to Server Settings → Roles
|
||||
2. Right-click a role → Copy ID
|
||||
3. Paste into appropriate field in admin panel
|
||||
4. Repeat for all 10 roles
|
||||
|
||||
**Example:**
|
||||
|
||||
You created "🔥 Fire Elemental" role in Discord:
|
||||
1. Right-click role → Copy ID → `987654321098765432`
|
||||
2. In admin panel, find "Product 3 (Fire Elemental)" field
|
||||
3. Paste: `987654321098765432`
|
||||
|
||||
### Step 4: Save Changes
|
||||
|
||||
1. Click **"Save All Changes"** button
|
||||
2. Panel validates each role ID:
|
||||
- ✅ Checks format (must be 18-19 digit number)
|
||||
- ✅ Verifies role exists in Discord server
|
||||
3. If validation passes:
|
||||
- ✅ Config saved to disk
|
||||
- ✅ In-memory config updated (instant effect)
|
||||
- ✅ Audit log posted to Discord `#bot-audit-logs`
|
||||
- ✅ Success message appears: "All role mappings updated!"
|
||||
4. If validation fails:
|
||||
- ❌ Error message shows which role ID is invalid
|
||||
- ❌ Config NOT saved (prevents bot from breaking)
|
||||
- ❌ Fix the invalid role ID and try again
|
||||
|
||||
### Step 5: Test Webhook
|
||||
|
||||
After saving role mappings:
|
||||
|
||||
1. Go to Paymenter test page (ask Michael for URL)
|
||||
2. Create test purchase for $5 Fire Elemental tier
|
||||
3. Check Discord - does bot assign "🔥 Fire Elemental" role?
|
||||
4. If yes: ✅ Role mapping works!
|
||||
5. If no: ❌ Check bot logs or ask Michael
|
||||
|
||||
### Step 6: Logout (Optional)
|
||||
|
||||
Click **"Logout"** button when done.
|
||||
|
||||
**Note:** You can stay logged in - session expires after 24 hours.
|
||||
|
||||
---
|
||||
|
||||
## ✅ TESTING & VERIFICATION
|
||||
|
||||
### Test Checklist
|
||||
|
||||
After deployment, verify:
|
||||
|
||||
#### 1. Bot User Running Correctly
|
||||
|
||||
```bash
|
||||
# Check service status
|
||||
sudo systemctl status firefrost-discord-bot
|
||||
|
||||
# Should show:
|
||||
# - Active: active (running)
|
||||
# - User: firefrost-bot (NOT root)
|
||||
```
|
||||
|
||||
#### 2. OAuth Login Works
|
||||
|
||||
1. Open `https://discord-bot.firefrostgaming.com/admin`
|
||||
2. Click "Login with Discord"
|
||||
3. Authorize
|
||||
4. Should redirect to admin panel
|
||||
5. Should see current role mappings
|
||||
|
||||
#### 3. Role ID Validation Works
|
||||
|
||||
**Test invalid role ID:**
|
||||
1. Enter `123` (too short) in any field
|
||||
2. Click "Save All Changes"
|
||||
3. Should show error: "Invalid Discord Role ID format"
|
||||
|
||||
**Test non-existent role ID:**
|
||||
1. Enter `999999999999999999` (valid format, but role doesn't exist)
|
||||
2. Click "Save All Changes"
|
||||
3. Should show error: "Role does not exist in Discord server"
|
||||
|
||||
**Test valid role ID:**
|
||||
1. Create test role in Discord
|
||||
2. Copy role ID
|
||||
3. Paste in admin panel
|
||||
4. Click "Save All Changes"
|
||||
5. Should show: "All role mappings updated successfully!"
|
||||
|
||||
#### 4. Config Persists After Restart
|
||||
|
||||
```bash
|
||||
# Restart bot
|
||||
sudo systemctl restart firefrost-discord-bot
|
||||
|
||||
# Reload admin panel in browser
|
||||
# Should still show saved role mappings (loaded from config.json)
|
||||
```
|
||||
|
||||
#### 5. Backup File Created
|
||||
|
||||
```bash
|
||||
# Check for backup
|
||||
ls -la /opt/firefrost-discord-bot/config.json.backup
|
||||
|
||||
# Should exist after first save
|
||||
```
|
||||
|
||||
#### 6. Audit Logs Appear in Discord
|
||||
|
||||
1. Make a config change in admin panel
|
||||
2. Check Discord `#bot-audit-logs` channel
|
||||
3. Should see embed with:
|
||||
- Author: Holly (or Michael)
|
||||
- Action: Updated Role Mappings
|
||||
- Changes: Product X: old_id → new_id
|
||||
|
||||
---
|
||||
|
||||
## 🔧 TROUBLESHOOTING
|
||||
|
||||
### Problem: "Unauthorized" Error When Accessing Admin Panel
|
||||
|
||||
**Symptoms:** Can't access `/admin`, get 401 error.
|
||||
|
||||
**Causes:**
|
||||
1. Not logged in via Discord OAuth
|
||||
2. Your Discord ID isn't in `ALLOWED_ADMINS` list
|
||||
|
||||
**Solutions:**
|
||||
|
||||
**Check if logged in:**
|
||||
- Clear browser cookies
|
||||
- Try logging in again via "Login with Discord"
|
||||
|
||||
**Check whitelist:**
|
||||
|
||||
```bash
|
||||
# On Command Center
|
||||
cat /opt/firefrost-discord-bot/.env | grep ALLOWED_ADMINS
|
||||
```
|
||||
|
||||
Should show Holly's and Michael's Discord IDs separated by comma.
|
||||
|
||||
**If your ID is missing:**
|
||||
|
||||
```bash
|
||||
# Edit .env
|
||||
sudo nano /opt/firefrost-discord-bot/.env
|
||||
|
||||
# Add your Discord ID to ALLOWED_ADMINS
|
||||
ALLOWED_ADMINS=HOLLYS_ID,MICHAELS_ID,YOUR_ID
|
||||
|
||||
# Save and restart bot
|
||||
sudo systemctl restart firefrost-discord-bot
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Problem: "Role does not exist in Discord server" Error
|
||||
|
||||
**Symptoms:** Valid-looking role ID rejected during save.
|
||||
|
||||
**Causes:**
|
||||
1. Role ID is from wrong Discord server
|
||||
2. Role was deleted after you copied ID
|
||||
3. Bot doesn't have permission to see roles
|
||||
|
||||
**Solutions:**
|
||||
|
||||
**Verify role exists:**
|
||||
1. Go to Discord Server Settings → Roles
|
||||
2. Find the role
|
||||
3. Right-click → Copy ID again
|
||||
4. Paste fresh ID into admin panel
|
||||
|
||||
**Check bot permissions:**
|
||||
1. Discord Server Settings → Roles
|
||||
2. Find "Firefrost Subscription Manager" bot role
|
||||
3. Ensure it has "Manage Roles" permission
|
||||
4. Ensure bot role is ABOVE the roles it needs to assign
|
||||
|
||||
---
|
||||
|
||||
### Problem: Admin Panel Shows Old Role Mappings
|
||||
|
||||
**Symptoms:** You saved new IDs, but admin panel shows old ones after refresh.
|
||||
|
||||
**Causes:**
|
||||
1. Browser cache
|
||||
2. Config file didn't save
|
||||
3. In-memory config didn't update
|
||||
|
||||
**Solutions:**
|
||||
|
||||
**Hard refresh browser:**
|
||||
- Windows: `Ctrl + Shift + R`
|
||||
- Mac: `Cmd + Shift + R`
|
||||
|
||||
**Check config file:**
|
||||
|
||||
```bash
|
||||
# On Command Center
|
||||
cat /opt/firefrost-discord-bot/config.json
|
||||
```
|
||||
|
||||
Should show your latest role IDs.
|
||||
|
||||
**If config.json is outdated:**
|
||||
|
||||
```bash
|
||||
# Restart bot
|
||||
sudo systemctl restart firefrost-discord-bot
|
||||
|
||||
# Try saving again in admin panel
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Problem: OAuth Login Redirects to "Cannot GET /auth/discord/callback"
|
||||
|
||||
**Symptoms:** After clicking "Authorize" in Discord, get error page.
|
||||
|
||||
**Causes:**
|
||||
1. Callback URL mismatch in Discord Developer Portal
|
||||
2. Backend route not set up correctly
|
||||
|
||||
**Solutions:**
|
||||
|
||||
**Check Discord Developer Portal:**
|
||||
1. Go to: https://discord.com/developers/applications
|
||||
2. Select your bot app → OAuth2
|
||||
3. Under Redirects, verify you have:
|
||||
`https://discord-bot.firefrostgaming.com/auth/discord/callback`
|
||||
4. Save changes if missing
|
||||
|
||||
**Check .env file:**
|
||||
|
||||
```bash
|
||||
cat /opt/firefrost-discord-bot/.env | grep CALLBACK_URL
|
||||
```
|
||||
|
||||
Should match Discord Developer Portal exactly.
|
||||
|
||||
**Restart bot:**
|
||||
|
||||
```bash
|
||||
sudo systemctl restart firefrost-discord-bot
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Problem: Bot Assigns Wrong Role After Config Update
|
||||
|
||||
**Symptoms:** Config saved successfully, but webhook assigns incorrect role.
|
||||
|
||||
**Causes:**
|
||||
1. Product ID → Role ID mapping is wrong
|
||||
2. In-memory config didn't update
|
||||
|
||||
**Solutions:**
|
||||
|
||||
**Verify mapping in admin panel:**
|
||||
|
||||
Product 3 should map to Fire Elemental role ID, not Frost Elemental.
|
||||
|
||||
**Check config.json:**
|
||||
|
||||
```bash
|
||||
cat /opt/firefrost-discord-bot/config.json
|
||||
```
|
||||
|
||||
Should show correct mappings.
|
||||
|
||||
**Restart bot (force reload):**
|
||||
|
||||
```bash
|
||||
sudo systemctl restart firefrost-discord-bot
|
||||
```
|
||||
|
||||
**Test webhook again.**
|
||||
|
||||
---
|
||||
|
||||
## 🔄 MAINTENANCE
|
||||
|
||||
### Regular Tasks
|
||||
|
||||
**Weekly:**
|
||||
- Check bot logs for errors: `sudo journalctl -u firefrost-discord-bot -n 100`
|
||||
- Verify SSL certificate is valid (auto-renewed by certbot)
|
||||
|
||||
**Monthly:**
|
||||
- Review audit logs in Discord `#bot-audit-logs`
|
||||
- Verify backup config exists: `ls -la /opt/firefrost-discord-bot/config.json.backup`
|
||||
|
||||
**As Needed:**
|
||||
- Update role mappings when creating new Discord roles
|
||||
- Add/remove admin users from `ALLOWED_ADMINS` in `.env`
|
||||
|
||||
### Backup Strategy
|
||||
|
||||
**Config is backed up automatically:**
|
||||
- Every save creates `config.json.backup`
|
||||
- Contains last-known-good configuration
|
||||
|
||||
**To restore from backup:**
|
||||
|
||||
```bash
|
||||
# SSH to Command Center
|
||||
cd /opt/firefrost-discord-bot
|
||||
|
||||
# Copy backup to active config
|
||||
cp config.json.backup config.json
|
||||
|
||||
# Restart bot
|
||||
sudo systemctl restart firefrost-discord-bot
|
||||
```
|
||||
|
||||
### Updating Backend Code
|
||||
|
||||
If Gemini provides code updates:
|
||||
|
||||
```bash
|
||||
# SSH to Command Center
|
||||
cd /opt/firefrost-discord-bot
|
||||
|
||||
# Backup current code
|
||||
cp bot.js bot.js.backup
|
||||
|
||||
# Edit bot.js with new code
|
||||
sudo nano bot.js
|
||||
|
||||
# Test syntax (optional)
|
||||
node --check bot.js
|
||||
|
||||
# Restart bot
|
||||
sudo systemctl restart firefrost-discord-bot
|
||||
|
||||
# Check logs
|
||||
sudo journalctl -u firefrost-discord-bot -n 50
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 RELATED DOCUMENTATION
|
||||
|
||||
**See also:**
|
||||
- `docs/guides/subscription-automation-guide.md` - Full subscription workflow
|
||||
- `docs/guides/server-side-mod-deployment-guide.md` - LuckPerms configuration
|
||||
|
||||
---
|
||||
|
||||
## 🙏 CREDITS
|
||||
|
||||
**Architecture Design:** Gemini (Google AI)
|
||||
**Implementation:** Chronicler #40 (Claude) + Michael
|
||||
**Testing:** Holly + Michael
|
||||
**Consultation Date:** March 23, 2026
|
||||
|
||||
**Key Architectural Decisions by Gemini:**
|
||||
- Run as dedicated `firefrost-bot` user (NOT root) - critical security fix
|
||||
- In-memory config updates (no restart needed) - zero downtime
|
||||
- Discord OAuth2 (no password management) - better security
|
||||
- Atomic file writes with backup (prevents corruption) - reliability
|
||||
- Discord API validation (verify roles exist) - prevents errors
|
||||
|
||||
**Thank you, Gemini, for the excellent architectural guidance.** 🙏
|
||||
|
||||
---
|
||||
|
||||
**Fire + Frost + Foundation = Where Love Builds Legacy** 🔥❄️
|
||||
|
||||
**Status:** Backend and Frontend code pending from Gemini
|
||||
**Last Updated:** March 23, 2026
|
||||
**Next Update:** When Gemini provides implementation code
|
||||
|
||||
---
|
||||
|
||||
**END OF GUIDE**
|
||||
@@ -555,34 +555,70 @@ curl https://webhook.firefrostgaming.com/health
|
||||
{"status":"healthy","bot":"Firefrost Subscription Manager#1234","uptime":123.456}
|
||||
```
|
||||
|
||||
### Task 9: Prepare Information for Holly
|
||||
### Task 9: Set Up Discord Bot Admin Panel
|
||||
|
||||
**Create a file with all the info Holly needs:**
|
||||
**PURPOSE:** Deploy web interface so Holly can manage Discord role mappings herself (no SSH access needed).
|
||||
|
||||
**⚠️ IMPORTANT:** Complete admin panel setup is documented in a separate guide.
|
||||
|
||||
**See:** `docs/guides/discord-bot-admin-panel.md`
|
||||
|
||||
**Quick Overview:**
|
||||
|
||||
The admin panel allows Holly to:
|
||||
- Log in via Discord OAuth (no passwords)
|
||||
- Update all 10 product → Discord role ID mappings
|
||||
- Save changes instantly (no bot restart needed)
|
||||
- View bot status and recent webhooks
|
||||
|
||||
**Setup Steps (High-Level):**
|
||||
|
||||
1. Create dedicated `firefrost-bot` Linux user (security - don't run as root)
|
||||
2. Set up Discord OAuth2 application
|
||||
3. Deploy backend code (provided by Gemini/Google AI)
|
||||
4. Deploy frontend code (provided by Gemini/Google AI)
|
||||
5. Configure Nginx reverse proxy + SSL
|
||||
6. Give Holly admin panel URL and walk through usage
|
||||
|
||||
**Time Required:** 2-3 hours (one-time setup)
|
||||
|
||||
**Once Complete:**
|
||||
|
||||
Holly will access admin panel at:
|
||||
```
|
||||
https://discord-bot.firefrostgaming.com/admin
|
||||
```
|
||||
|
||||
**Status:** Full implementation guide available at `docs/guides/discord-bot-admin-panel.md`
|
||||
|
||||
**For now, continue with manual method below (Holly gives you role IDs, you update bot.js). We'll migrate to admin panel later.**
|
||||
|
||||
---
|
||||
|
||||
### Task 9 (ALTERNATIVE - MANUAL METHOD)
|
||||
|
||||
**If admin panel isn't set up yet, use this manual approach:**
|
||||
|
||||
Create a credentials file for Holly:
|
||||
|
||||
```bash
|
||||
cat > /root/holly-bot-credentials.txt << EOF
|
||||
Firefrost Discord Bot - Credentials for Holly
|
||||
|
||||
Bot Name: Firefrost Subscription Manager
|
||||
Bot Token: $(grep "const DISCORD_TOKEN" /opt/firefrost-discord-bot/bot.js | cut -d"'" -f2)
|
||||
Guild ID: $(grep "const GUILD_ID" /opt/firefrost-discord-bot/bot.js | cut -d"'" -f2)
|
||||
|
||||
Webhook URL: https://webhook.firefrostgaming.com/webhook/paymenter
|
||||
|
||||
Bot is installed on: Command Center (63.143.34.217)
|
||||
Bot directory: /opt/firefrost-discord-bot/
|
||||
Service name: firefrost-discord-bot
|
||||
|
||||
Commands for Holly:
|
||||
- View logs: journalctl -u firefrost-discord-bot -f
|
||||
- Restart bot: systemctl restart firefrost-discord-bot
|
||||
- Edit bot code: nano /opt/firefrost-discord-bot/bot.js
|
||||
|
||||
Next Steps:
|
||||
1. Holly creates Discord roles (Part 2 of guide)
|
||||
2. Holly gets role IDs and updates bot.js PRODUCT_ROLE_MAP
|
||||
3. Holly restarts bot: systemctl restart firefrost-discord-bot
|
||||
4. Test webhook flow
|
||||
2. Holly gets role IDs and sends them to Michael
|
||||
3. Michael updates bot.js PRODUCT_ROLE_MAP with role IDs
|
||||
4. Michael restarts bot: systemctl restart firefrost-discord-bot
|
||||
5. Test webhook flow
|
||||
|
||||
NOTE: Once admin panel is deployed, Holly can update role IDs herself.
|
||||
See: docs/guides/discord-bot-admin-panel.md
|
||||
|
||||
---
|
||||
Generated: $(date)
|
||||
@@ -624,9 +660,17 @@ cat /root/holly-bot-credentials.txt
|
||||
|
||||
**Holly, you now need to:**
|
||||
1. Create Discord roles (Part 2)
|
||||
2. Update bot code with role IDs
|
||||
3. Configure LuckPerms
|
||||
4. Test the complete flow
|
||||
2. **EITHER:**
|
||||
- **Option A (Recommended):** Use Discord Bot Admin Panel at `discord-bot.firefrostgaming.com/admin` to update role IDs
|
||||
- **Option B (Manual):** Give role IDs to Michael, he updates bot.js via SSH
|
||||
3. Configure LuckPerms groups and permissions (Part 3)
|
||||
4. Set up LuckPerms Discord integration (Part 4)
|
||||
5. Configure Paymenter webhooks (Part 5)
|
||||
6. Test the complete flow
|
||||
|
||||
**Note:** If admin panel is set up (Option A), you can update role mappings yourself anytime. If not (Option B), you'll need Michael's help each time roles change.
|
||||
|
||||
**Admin panel documentation:** `docs/guides/discord-bot-admin-panel.md`
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user