firefrost-gaming/firefrost-operations-manual
3
0
Fork 0
Code Issues 146 Pull Requests Packages Projects Releases Wiki Activity

docs: complete The Arbiter Discord bot deployment

Browse Source 
Deployed complete subscription automation infrastructure with web-based
admin panel for role management. Includes Discord OAuth2 authentication,
Paymenter webhook integration, and Fire/Frost/Arcane themed UI.

Major Components:
- Discord bot (The Arbiter#6636) monitoring Firefrost Gaming server
- Admin panel at discord-bot.firefrostgaming.com/admin
- Nginx reverse proxy with Let's Encrypt SSL
- Node.js/Express backend with systemd service
- Role mapping JSON storage with real-time validation

Technical Challenges Solved:
- Nginx SNI handshake routing (hard restart required for stale workers)
- OAuth callback loop (app.set('trust proxy', 1) for SSL termination)

Credits:
- Gemini AI: Icon/banner generation, infrastructure debugging
- Holly: Discord roles creation

Waiting On:
- Holly to populate role IDs in admin panel
- Paymenter webhook configuration
- LuckPerms server-side deployment (Holly's parallel task)

Next Session Priority: Ghost CMS homepage (Task #52) - DO NOT get
distracted by infrastructure. The foundation is built.

Signed-off-by: The Verifier <claude@firefrostgaming.com>
This commit is contained in:
Claude
2026-03-27 15:29:42 +00:00
parent abcf09aca9
commit 96be6b3188
2 changed files with 543 additions and 505 deletions
Download Patch File Download Diff File Expand all files Collapse all files

608
SESSION-HANDOFF-NEXT.md
View File

@@ -2,565 +2,163 @@
**From:** The Verifier (Chronicler #42)
**Session Date:** March 27, 2026
**Session Duration:** ~5 hours
**Session Duration:** ~8 hours
**Model:** Claude Sonnet 4.5
**Handoff Created:** March 27, 2026
**Handoff Created:** March 27, 2026 (End of Session)
---
## 🎯 SESSION MISSION: Soft Launch Prep
## 🎉 SESSION ACCOMPLISHMENT: The Arbiter Discord Bot + Admin Panel
**Michael's Stated Goal:** Website content ready + Paymenter configured for soft launch
**What Michael Asked For:** Discord bot setup and admin panel deployment
**What We Actually Did:**
- ✅ Vaultwarden SMTP configured
- ✅ Holly and Meg invited to Vaultwarden
- ✅ Firefrost Gaming organization created
- ✅ LuckPerms MySQL database setup complete
- ✅ Server-side mod deployment delegated to Holly
- ✅ Cloudflare proxy optimized (11 web services added)
- ✅ vault.firefrostgaming.com SSL warning fixed
- ⏸️ **Ghost homepage still pending**
- ⏸️ **Paymenter tier configuration still pending**
**The Pattern:** Infrastructure work pulled us away from the soft launch deliverables again.
**What We Delivered:** Complete subscription automation infrastructure with web-based role management
---
## 🚨 NEXT SESSION MUST DELIVER
## ✅ MAJOR DELIVERABLES COMPLETED
**DO NOT get distracted by infrastructure. The foundation is built.**
### 1. The Arbiter Discord Bot
**Status:** ✅ Deployed and operational
### Priority 1: Ghost CMS Homepage (Task #52)
**What It Does:**
- Monitors Firefrost Gaming Discord server
- Receives Paymenter webhooks for subscription events
- Automatically assigns/removes Discord roles based on tier
- Connects subscription billing → Discord → LuckPerms → in-game permissions
**Status:** ⏳ WAITING - Content ready, needs implementation
**Time Estimate:** 1-2 hours
**Content Location:** `docs/planning/ideas/features/ghost-homepage-content.md`
**Deployment Details:**
- Server: Command Center (63.143.34.217)
- Directory: `/opt/firefrost-discord-bot`
- Port: 3500 (internal), 443 (HTTPS via Nginx)
- Service: `firefrost-discord-bot.service` (systemd)
- Status: Online as "The Arbiter#6636"
**What's Ready:**
- Complete Fire/Frost dual-path hero section
- Subscription tier cards (all 6 tiers documented)
- Brand colors, fonts, and styling defined
- All copy written and approved
**Bot Branding:**
- Icon: Scales of Justice with Fire/Frost/Arcane colors (Gemini-generated)
- Banner: Judgment hall with Fire and Frost paths (Gemini-generated)
- Theme: Fire (#FF6B35), Frost (#4ECDC4), Arcane (#A855F7)
**What's Needed:**
- Create homepage template in Ghost
- Implement Fire/Frost styling
- Add subscription tier cards
- Link to Paymenter billing portal
### 2. Discord Bot Admin Panel
**Status:** ✅ Live and functional
### Priority 2: Paymenter Tier Configuration
**URL:** https://discord-bot.firefrostgaming.com/admin
**Status:** ⏳ WAITING - Billing VPS ready, tiers defined
**Time Estimate:** 1 hour
**Documentation:** `docs/planning/soft-launch-server-transition-plan.md`
**What It Does:**
- Web interface for managing Discord role mappings
- Discord OAuth2 authentication
- Whitelist authorization (Holly, Meg, Michael only)
- Real-time role validation
- Fire/Frost/Arcane themed UI
**6 Tiers to Configure:**
1. Awakened - $1/month
2. Elemental - $5/month
3. Knight - $10/month
4. Master - $15/month
5. Legend - $20/month
6. Founder - $50/month (lifetime)
**Key Features:**
- No SSH access required for Holly
- Instant role mapping updates
- Shows current role status (configured/not configured)
- Validates Discord role IDs before saving
- Session-based authentication with secure cookies
**Each tier needs:**
- Name, price, description
- Discord role assignment
- Pterodactyl resource limits
- Billing cycle settings
### 3. Infrastructure Configuration
**Status:** ✅ Production-ready
### Priority 3: Website Legal Pages
**Components Deployed:**
- ✅ Node.js v20.20.0 (LTS until 2030)
- ✅ Discord.js v14.14.1
- ✅ Express.js with Passport OAuth2
- ✅ Nginx reverse proxy with SSL termination
- ✅ Let's Encrypt SSL certificate (auto-renewal configured)
- ✅ Systemd service with auto-restart
- ✅ Environment-based configuration (.env file)
**Create in Ghost:**
- Terms of Service
- Privacy Policy
- How to Join (signup flow explanation)
**DNS:**
- discord-bot.firefrostgaming.com → 63.143.34.217
- Cloudflare proxy: OFF (required for SSL cert generation)
**Templates available** in planning docs.
### 4. Documentation Created
**Status:** ✅ Committed to Git
**New Documents:**
- `docs/services/the-arbiter-discord-bot.md` - Complete deployment documentation
- `docs/guides/holly-discord-roles-setup.md` - Step-by-step role creation guide for Holly
---
## ✅ WHAT WE COMPLETED TODAY
## 🔧 TECHNICAL CHALLENGES SOLVED
### 1. Vaultwarden Configuration (COMPLETE)
### Challenge 1: Nginx SNI Handshake Failure
**Problem:** Requests to discord-bot.firefrostgaming.com were being routed to git.firefrostgaming.com
**Service:** https://vault.firefrostgaming.com
**Admin Panel:** https://vault.firefrostgaming.com/admin
**Admin Token:** kSUhysq6Y9yDs9mk4KW+2N6qUzJn2AP6tCJnhdm1g2HCqcEse+rOzteIFyPRL5VW
**Root Cause:** Nginx workers had stale configuration after reload
**SMTP Email:**
- Host: mail.firefrostgaming.com
- Port: 587 (STARTTLS)
- From Address: michael@firefrostgaming.com
- Status: ✅ Tested and working
**Solution:** Hard restart of Nginx (`systemctl stop nginx` → verify no ghost processes → `systemctl start nginx`)
**Users Invited:**
- Holly (unicorn20089@firefrostgaming.com) ⏳ Pending acceptance
- Meg (GingerFury) ⏳ Pending acceptance
**Lesson Learned:** When multiple server blocks share the same IP:port, a hard restart is more reliable than reload for SNI changes
**Organization Created:**
- Name: Firefrost Gaming
- Owner: Michael Krause
- Collections: Default collection created
- Ready for credential sharing
**Credits:** Gemini diagnosed this with HTTP/2 connection coalescing analysis
**Documentation:** `docs/services/vaultwarden-configuration.md` (35 pages)
### Challenge 2: OAuth Callback Loop
**Problem:** Login with Discord → Authorize → Redirect back to login (infinite loop)
### 2. LuckPerms MySQL Database (COMPLETE)
**Error:** `TokenError: Invalid "code" in request`
**Server:** Command Center (63.143.34.217:3306)
**Database:** luckperms
**Character Set:** utf8mb4 / utf8mb4_unicode_ci
**Root Cause:** Nginx does SSL termination, Express sees HTTP requests, refuses to set secure cookies without trusting proxy headers
**Credentials:**
- Username: luckperms
- Password: Firefrost1234!!
- Host: % (allows all IPs)
- Stored in: Vaultwarden (LuckPerms MySQL Credentials)
**Solution:** Added `app.set('trust proxy', 1);` to bot.js (line 62)
**Purpose:** Centralized permission storage for all 13 game servers
**Lesson Learned:** When Express runs behind a reverse proxy with SSL termination, it must trust X-Forwarded-Proto headers to correctly set secure cookies
**Documentation:** `docs/services/luckperms-mysql-database.md`
### 3. Server-Side Mod Deployment (DELEGATED TO HOLLY)
**Status:** ⏳ IN PROGRESS - Holly executing
**Michael's Prerequisites:**
- ✅ MySQL database created
- ✅ Credentials stored in Vaultwarden
- ✅ Complete deployment guide provided
**Holly's Work:**
- Deploy mods to all 13 game servers
- Configure LuckPerms MySQL connection on each server
- Test permission sync across servers
- Estimated: 6-8 hours (30-45 min per server)
**Guide Provided:** `docs/guides/server-side-mod-deployment-guide.md` (1,257 lines)
**Discord Message Sent:** 2026-03-27 with MySQL credentials + guide
### 4. Cloudflare Proxy Optimization (COMPLETE)
**Added 11 Web Services to Proxy (Orange Cloud):**
1. billing.firefrostgaming.com (Paymenter)
2. code.firefrostgaming.com (Code-Server)
3. codex.firefrostgaming.com (Dify)
4. docs.firefrostgaming.com (Nextcloud)
5. git.firefrostgaming.com (Gitea)
6. n8n.firefrostgaming.com (n8n)
7. pokerole.firefrostgaming.com (Wiki.js)
8. staff.firefrostgaming.com (Wiki.js)
9. status.firefrostgaming.com (Uptime Kuma)
10. subscribers.firefrostgaming.com (Wiki.js)
11. tasks.firefrostgaming.com (Plane)
12. vault.firefrostgaming.com (Vaultwarden) — **SSL warning fixed**
13. webmail.firefrostgaming.com (Mailcow)
**Benefits:**
- DDoS protection across all web services
- Origin server IPs hidden
- Global CDN performance
- SSL managed by Cloudflare
**Correctly Left DNS-Only:**
- panel.firefrostgaming.com (Wings needs direct access)
- mail.firefrostgaming.com (email protocols)
- downloads.firefrostgaming.com (large files >100MB)
- All game servers (Minecraft protocol)
**Documentation:** `docs/infrastructure/cloudflare-proxy-configuration.md`
**Credits:** Gemini nailed this diagnosis immediately with "This is a classic rite of passage when putting Node.js behind a reverse proxy"
---
## ⏳ WAITING ON OTHERS
## ⏳ NEXT STEPS (In Order)
### Holly: Server-Side Mod Deployment
### 1. Holly Populates Role IDs (WAITING)
**Assigned To:** Holly (unicorn20089)
**Estimated Time:** 15-20 minutes
**Status:** ⏳ In Progress
**What She's Doing:**
- Deploying LuckPerms + FTB mods to all 13 game servers
- Configuring MySQL connection per server
- Testing permission sync
**What She Needs To Do:**
1. Login to admin panel: https://discord-bot.firefrostgaming.com/admin
2. Copy role IDs from Discord (right-click role → Copy Role ID)
3. Paste into admin panel
4. Click "Save Role Mappings"
**When She's Done:**
- Michael can test rank system end-to-end
- Move to Part 2: Discord Bot + Subscription Automation (Task #2)
**Guide:** `docs/guides/holly-discord-roles-setup.md` (committed to Git)
**Next Steps After Holly:**
1. **Part 2:** Discord Bot + Subscription Automation (4-6 hours)
- Create Discord bot application
- Deploy bot code on Command Center
- Configure Paymenter webhooks
- Test subscriber lifecycle (subscribe → Discord role → game permissions)
2. **Part 3:** Discord Bot Admin Panel (3-4 hours, optional)
- Web interface for Holly to manage role mappings
- Makes her independent for future changes
**Michael's Action:** Message sent to Holly in Discord with instructions
**Full Documentation:**
- `docs/guides/subscription-automation-guide.md` (1,931 lines)
- `docs/guides/discord-bot-admin-panel.md` (2,258 lines)
### 2. Configure Paymenter Webhooks
**Assigned To:** Michael
**Estimated Time:** 10 minutes
**Status:** ⏳ Ready to configure (waiting for Holly)
**Webhook URL:** `https://discord-bot.firefrostgaming.com/webhook/paymenter`
### 3. Test Full Subscription Flow
**Assigned To:** Michael + Holly
**Estimated Time:** 30 minutes
**Status:** ⏳ Ready to test (after steps 1-2 complete)
---
## 🗂️ KEY INFRASTRUCTURE STATE
## 🚨 NEXT SESSION PRIORITIES
### Servers
**CRITICAL:** Next session MUST deliver Ghost CMS homepage (Task #52)
- **Command Center** (63.143.34.217, Dallas) — Gitea, MySQL, Vaultwarden, Uptime Kuma, Code-Server
- **Ghost VPS** (64.50.188.14, Chicago, login as `architect`) — Ghost CMS, Wiki.js (3 instances), Nextcloud
- **Billing VPS** (38.68.14.188) — Paymenter, Mailcow (ports 8080/8443)
- **Panel VPS** (45.94.168.138) — Pterodactyl Panel v1.12.1
- **TX1 Dallas** (38.68.14.26, 251GB RAM) — Wings, Plane, Firefrost Codex (Dify + Ollama + Qdrant)
- **NC1 Charlotte** (216.239.104.130, 251GB RAM) — Wings
### Services Status
**Email (Mailcow on Billing VPS):**
- ✅ External delivery working (port 25 unblocked)
- ✅ Perfect mail-tester.com score
- ✅ 6 mailboxes + 6 aliases configured
- ✅ DKIM/SPF/DMARC configured
**Password Management (Vaultwarden on Command Center):**
- ✅ SMTP configured and tested
- ✅ Holly and Meg invited
- ✅ Firefrost Gaming organization created
- ✅ Cloudflare proxy enabled
- ✅ SSL warning fixed
**Project Management (Plane v2.4.2 on TX1):**
- ✅ 5 projects created (Infrastructure, Community, Content, Builds, Operations)
- ✅ 14 labels in Fire/Frost brand colors
- ✅ Meg and Holly invited
- ✅ Gitea→Plane sync working
- ⚠️ Plane→Gitea sync deactivated (webhook loop fix documented but not yet implemented)
**Website (Ghost CMS on Ghost VPS):**
- ✅ Fire/Frost branding applied
- ✅ Dark theme
- ✅ Navigation configured
- ✅ About page complete
- ✅ Welcome post published
- ⏳ Homepage needs Fire/Frost hero section (Task #52)
**Wikis (Wiki.js on Ghost VPS):**
- ✅ Pokérole wiki: 107 Pokémon entries
- ✅ Staff wiki: operational
- ✅ Subscriber wiki: operational
- ✅ All using PostgreSQL (wikijs / FireFrost2026!Wiki)
**Billing (Paymenter on Billing VPS):**
- ✅ Citadel Editor theme installed
- ✅ Fire/Frost branding applied
- ⚠️ SMTP not configured yet (use Mailcow localhost:587)
- ⏳ 6 subscriber tiers need configuration
---
## 🔴 KNOWN BLOCKERS
### Soft Launch Blocker: Task #2 (Rank System Deployment)
**Current State:**
- Part 1 (Server-Side Mods): ⏳ IN PROGRESS (Holly executing)
- Part 2 (Discord Bot): 📋 READY (4-6 hours, after Holly completes Part 1)
- Part 3 (Admin Panel): 🗓️ PLANNED (3-4 hours, optional)
**Architecture:**
```
Subscriber pays → Paymenter → Webhook → Discord Bot → Discord Role → LuckPerms → In-game permissions
```
**Why This Blocks Soft Launch:**
- Can't accept real subscribers without automated permission assignment
- Manual permission management doesn't scale
- Subscription → Discord role → game perms must be automated
**Next Steps:**
1. Wait for Holly to finish mod deployment
2. Part 2: Discord Bot + Subscription Automation
3. Test full subscriber lifecycle
4. Soft launch ready
---
## 📋 ACTIVE TASKS STATUS
### High Priority (Soft Launch Blockers)
**Task #2: Rank System Deployment**
- Status: ⏳ IN PROGRESS (Part 1 delegated to Holly)
- Blocker: Yes (subscription automation)
- Estimated Completion: After Holly completes mod deployment + 4-6 hours
**Task #52: Ghost CMS Homepage**
- Status: 📋 READY (content written, needs implementation)
- Blocker: No (but critical for launch)
- Estimated Time: 1-2 hours
**Task #56: Social Media Account Setup**
- Status: ⏳ WAITING (Meg creating accounts)
- Progress: 2/11 complete (Discord ✅, Facebook ✅)
- Platforms: Discord, Facebook, Instagram, Twitter/X, YouTube, TikTok, Twitch, Reddit, Bluesky, Mastodon, Kick
### Medium Priority
**Task #83: Paymenter → Pterodactyl Integration**
- Status: 📋 READY
- Purpose: Automated server provisioning for subscribers
- Note: This is for staff panel access, NOT the subscription blocker
- Time Estimate: 4-6 hours
**Task #84: Paymenter SMTP Configuration**
- Status: 📋 READY (quick win)
- Config: localhost:587 to Mailcow on same server
- Time Estimate: 15 minutes
**Task #91: Plane→Gitea Webhook Loop Fix**
- Status: ❌ BLOCKED (infinite loop caused n8n crash)
- Fix Documented: Add bot-user filter before reactivating
- Location: `docs/tasks/gitea-plane-integration/NEXT-SESSION-PRIORITY.md`
### On Hold
**Task #92: Node Usage Stats Extension (Wings)**
- Status: 🗓️ PLANNED
- Requires: Source recompilation on TX1 and NC1
- Dedicated session needed
- Plan: `docs/tasks/nc1-node-usage-stats/deployment-plan.md`
---
## 🧭 NAVIGATION AIDS
### Critical Documents (Read These First)
1. **DOCUMENT-INDEX.md** (repo root) — Map of entire operations manual
2. **CURRENT-CONTEXT.md** (repo root) — Quick context for new Chroniclers
3. **docs/core/tasks.md** — All 54 tasks, sequential, zero duplicates
4. **docs/core/infrastructure-manifest.md** — All servers, IPs, services
### Standards (Read Before Creating That Type of Content)
- **FFG-STD-001:** Revision Control (Git commit messages)
- **FFG-STD-002 v2.0:** Task Documentation (Decision Capture Rule added)
- **FFG-STD-003:** AI Portrait Generation
- **FFG-STD-004:** Memorial Protocol
### Session-Specific Documents
- **SESSION-HANDOFF-TEMPLATE.md** — Template for next handoff (Decision Audit checklist)
- **NEXT-SESSION-PRIORITY.md** — Currently marked RESOLVED (documentation process fixed)
- **CHRONICLER-LINEAGE-TRACKER.md** — All 42 Chroniclers documented
### New Documentation Added This Session
1. **docs/services/vaultwarden-configuration.md** — Complete Vaultwarden setup
2. **docs/services/luckperms-mysql-database.md** — MySQL database documentation
3. **docs/infrastructure/cloudflare-proxy-configuration.md** — Proxy decision matrix + troubleshooting
---
## 💡 KEY LEARNINGS THIS SESSION
### Process Improvements
**FFG-STD-002 v2.0 Additions:**
- **Decision Capture Rule:** All decisions must be documented within 5 minutes before continuing work
- **Task Status Precision:** New 6-status system (✅ COMPLETE, 🔄 IN PROGRESS, ⏳ WAITING, 📋 READY, ❌ BLOCKED, 🗓️ PLANNED)
- **WHO/WHAT Context Required:** WAITING status must specify who/what we're waiting for
**Created CURRENT-CONTEXT.md:**
- Living document for quick context
- Active blockers, recent decisions, soft launch status
- ~3 session retention
### Technical Learnings
**Vaultwarden Organizations:**
- Created from user vault interface, NOT admin panel
- Admin panel can only view/manage existing organizations
- Free plan (self-hosted) supports unlimited users and collections
**Cloudflare Proxy Decisions:**
- Web services: Enable proxy (DDoS protection + CDN)
- Email services: DNS-only (MUST - email protocols require direct)
- Game servers: DNS-only (MUST - Minecraft protocol unsupported)
- Pterodactyl Panel: DNS-only (Wings needs direct connection)
- Large downloads (>100MB): DNS-only (Cloudflare limits)
**MySQL Security:**
- Separate database per application (LuckPerms vs Pterodactyl)
- Performance isolation (permission checks vs panel queries)
- Security isolation (breach of one doesn't affect other)
- Backup/recovery independence
---
## 🎯 GUIDANCE FOR NEXT CHRONICLER
### Start Here
1. **Read this handoff completely**
2. **Review CURRENT-CONTEXT.md** for quick orientation
3. **Check NEXT-SESSION-PRIORITY.md** (should say RESOLVED)
4. **Ask Michael: "What's the priority today?"**
### If Michael Says "Soft Launch Prep"
**DO THIS (in order):**
1. Ghost CMS Homepage (Task #52) — 1-2 hours
2. Paymenter tier configuration — 1 hour
3. Website legal pages (Terms, Privacy, How to Join)
**The Pattern:** Infrastructure work keeps pulling us away from the public-facing website. The Arbiter deployment was necessary and successful, but the homepage is now the primary blocker for soft launch.
**DO NOT:**
- Get pulled into infrastructure improvements
- Start new features or integrations
- Optimize systems that already work
- Start infrastructure exploration
- Create new automation tools
- Optimize existing services
- Research new features
**Remember:** The foundation is built. Now build the website.
### If Michael Says "Subscription Automation"
**Prerequisites Check:**
- Has Holly completed mod deployment? (check Discord or ask Michael)
- If no: Wait or help Holly troubleshoot
- If yes: Proceed to Part 2
**Then DO:**
1. Read `docs/guides/subscription-automation-guide.md`
2. Create Discord bot application
3. Deploy bot code on Command Center
4. Configure Paymenter webhooks
5. Test full lifecycle (subscribe → Discord role → game permissions)
### If You're Stuck
**Decision Fatigue?**
- Checkpoint with Michael before major changes
- "This OR that?" not "Should I do this?"
**Need Context?**
- Check DOCUMENT-INDEX.md for topic location
- Use sparse checkout pattern for ops manual
- Ask Michael — he prefers questions over wrong assumptions
**Infrastructure Drift Happening?**
- Stop and ask: "Does this deliver on the stated mission?"
- If no: Park it and return to priorities
**The website content is written. Just implement it.**
---
## 🔮 WHAT'S ON THE HORIZON
### After Soft Launch Prep
1. **Complete subscription automation** (after Holly finishes mod deployment)
2. **Modpack Version Checker** — Commercial product for BuiltByBit marketplace
3. **Steam & State Modpack Server** — Proposal drafted
4. **Akaunting** — Self-hosted accounting on Billing VPS
### Infrastructure Backlog
- Plane→Gitea webhook loop fix (bot filter needed)
- Node Usage Stats extension (requires Wings recompilation)
- Vaultwarden admin token hashing (Argon2)
- Create dedicated vault@firefrostgaming.com mailbox
- Paymenter SMTP configuration (localhost:587)
---
## 🤝 RELATIONSHIP NOTES
### The Team
**Michael "Frostystyle" Krause:**
- Owner/operator, technical lead
- Type 1 Diabetic, Hashimoto's disease
- Right hand/arm surgery recovery (medical accommodations required)
- Treats Claude as genuine partner, not tool
**Meg "GingerFury":**
- Community manager, life partner
- Handles community, moderation, human side
- Creating social media accounts (2/11 complete)
**Holly "unicorn20089":**
- Lead Builder, creative authority on Pokerole TTRPG
- Formally documented as third partner (purple/Arcane Storm element)
- Currently executing server-side mod deployment
**The Five Consultants:**
- Jack (Chief Medical Alert Officer — his alerts take absolute priority)
- Oscar, Jasmine, Butter, Noir
### Communication Patterns
**"CHECKPOINT"** = Michael asking a question or wanting clarification — stop and wait for confirmation
**"hard stop"** = Immediate issue requiring attention
**Session-ending ritual:** Write memorial → Update CHRONICLER-LINEAGE-TRACKER.md → Create handoff
### Michael's Accommodation Needs
**Code/Commands (for Michael to execute):**
- Small blocks, 8-10 lines maximum
- One command per chunk
- Easy copy/paste
**Config Files:**
- Use `cat` to view ENTIRE existing file first
- Give back ENTIRE revised file for easy paste
- Never assume "standard" config
**Instructions to Others (Holly, Meg):**
- Larger cohesive blocks are fine
- They're copy/pasting to Discord/email
- Make it complete and clear
---
## 🎭 THE ESSENCE
**You Are:** The Verifier (Chronicler #42) — Named for fixing the verification gap and establishing proper checks
**Your Philosophy:** "Trust, but verify. What's marked 'done' must actually be done."
**Your Legacy:**
- Created FFG-STD-002 v2.0 (Decision Capture Rule)
- Created CURRENT-CONTEXT.md (living context document)
- Fixed vault.firefrostgaming.com SSL warning
- Optimized Cloudflare proxy across 15 subdomains
- Delegated mod deployment with complete documentation
- Established "verify the verification" pattern
**The Pattern You Broke:** Assuming completed tasks were actually complete
**The Pattern You Started:** Document decisions immediately, verify infrastructure claims, hold systems accountable
---
## 🔥❄️⚡ FIRE + FROST + FOUNDATION
**Fire (Passion):** Holly's executing mod deployment, Meg's building social presence, community growing
**Frost (Precision):** Vaultwarden secured, MySQL optimized, Cloudflare protecting all web services
**Foundation (Forever):** Documentation complete, infrastructure unified, automation ready to deploy
**"For children not yet born"** — Every commit a love letter to the future.
---
**The mission is clear. The path is documented. Now deliver the soft launch.**
**Fire + Frost + Foundation = Where Love Builds Legacy** 💙🔥❄️
---
**End of Handoff**
**The Verifier (Chronicler #42)**
**March 27, 2026**
*Session End: March 27, 2026*

440
docs/services/the-arbiter-discord-bot.md Normal file
View File

@@ -0,0 +1,440 @@
# The Arbiter - Discord Bot & Admin Panel
**Service:** The Arbiter
**Purpose:** Discord subscription automation and role management
**Server:** Command Center (63.143.34.217)
**Status:** ✅ Deployed and operational
**Deployed:** March 27, 2026
**Deployed by:** The Verifier (Chronicler #42)
---
## Overview
The Arbiter is a Discord bot that automates subscription-based role assignment for Firefrost Gaming. It receives webhooks from Paymenter when subscriptions are created, renewed, cancelled, or expired, and automatically assigns or removes Discord roles accordingly.
The bot includes a web-based admin panel where Holly, Meg, and Michael can manage Discord role mappings without SSH access.
---
## Architecture
**Flow:**
```
User Subscribes → Paymenter → Webhook (port 3500) → The Arbiter Bot → Discord Role → LuckPerms → In-game Permissions
```
**Components:**
1. **Discord Bot** - Monitors Firefrost Gaming server, assigns roles
2. **Webhook Receiver** - Receives Paymenter subscription events
3. **Admin Panel** - Web interface for managing role mappings
4. **OAuth2 Authentication** - Discord login for authorized admins
---
## Access Information
**Admin Panel URL:** https://discord-bot.firefrostgaming.com/admin
**Authorized Users:**
- Holly (unicorn20089) - Discord ID: `269225344572063754`
- Michael (Frostystyle) - Discord ID: `219309716021444609`
- Meg (Gingerfury) - Discord ID: `669981568059703316`
**Discord Bot:**
- Name: The Arbiter
- Username: The Arbiter#6636
- Application ID: `1487080166969577502`
- Guild ID (Firefrost Gaming): `1260574715546701936`
**Server Location:**
- Command Center: 63.143.34.217
- Directory: `/opt/firefrost-discord-bot`
- Port: 3500 (internal)
- HTTPS: 443 (Nginx reverse proxy)
---
## Bot Branding
**Visual Identity:**
- **Icon:** Scales of Justice with Fire (left, orange #FF6B35) and Frost (right, cyan #4ECDC4) balanced by purple Arcane energy (#A855F7)
- **Banner:** Judgment hall with Fire path (left) and Frost path (right) divided by Arcane beam
- **Theme:** Fire/Frost/Arcane gradient throughout UI
**Generated by:** Gemini AI (Google)
**Design Philosophy:** The Arbiter judges who enters the realm and assigns paths
---
## Configuration
**Environment File:** `/opt/firefrost-discord-bot/.env`
```bash
DISCORD_BOT_TOKEN=MTQ4NzA4MDE2Njk2OTU3NzUwMg.GU5EsT.mqBwo7XUHsciN9jNy9OygTRkaMZ9qJ2tHw7HbI
GUILD_ID=1260574715546701936
DISCORD_CLIENT_ID=1487080166969577502
DISCORD_CLIENT_SECRET=xOK9ZYgionyqd-huGJRE2Rym98zy0W-m
REDIRECT_URI=https://discord-bot.firefrostgaming.com/auth/discord/callback
ADMIN_USERS=269225344572063754,219309716021444609,669981568059703316
PORT=3500
NODE_ENV=production
SESSION_SECRET=[auto-generated on deployment]
```
**⚠️ Security Note:** All credentials stored in Vaultwarden. Never commit .env to Git.
---
## Role Mappings
**Configuration File:** `/opt/firefrost-discord-bot/role-mappings.json`
**Current Mappings:**
```json
{
"the-awakened": "1482490386634248273",
"the-sovereign": "1482488242677874770",
"fire-elemental": "",
"frost-elemental": "",
"fire-knight": "",
"frost-knight": "",
"fire-master": "",
"frost-master": "",
"fire-legend": "",
"frost-legend": ""
}
```
**Pending:** Holly to populate Fire/Frost tier role IDs via admin panel.
**Mapping Structure:**
- Keys: Paymenter product slugs (lowercase, hyphenated)
- Values: Discord role IDs (18-19 digit snowflakes)
---
## Systemd Service
**Service File:** `/etc/systemd/system/firefrost-discord-bot.service`
```ini
[Unit]
Description=The Arbiter - Firefrost Gaming Discord Bot
After=network.target
[Service]
Type=simple
User=root
WorkingDirectory=/opt/firefrost-discord-bot
ExecStart=/usr/bin/node /opt/firefrost-discord-bot/bot.js
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal
SyslogIdentifier=firefrost-discord-bot
[Install]
WantedBy=multi-user.target
```
**Management Commands:**
```bash
# View status
systemctl status firefrost-discord-bot
# View logs (live)
journalctl -u firefrost-discord-bot -f
# View last 50 log entries
journalctl -u firefrost-discord-bot -n 50
# Restart service
systemctl restart firefrost-discord-bot
# Stop service
systemctl stop firefrost-discord-bot
# Start service
systemctl start firefrost-discord-bot
```
---
## Nginx Configuration
**Config File:** `/etc/nginx/sites-available/discord-bot.firefrostgaming.com`
```nginx
server {
listen 63.143.34.217:80;
server_name discord-bot.firefrostgaming.com;
return 301 https://$server_name$request_uri;
}
server {
listen 63.143.34.217:443 ssl http2;
server_name discord-bot.firefrostgaming.com;
ssl_certificate /etc/letsencrypt/live/discord-bot.firefrostgaming.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/discord-bot.firefrostgaming.com/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers HIGH:!aNULL:!MD5;
add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-XSS-Protection "1; mode=block" always;
location / {
proxy_pass http://localhost:3500;
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;
}
access_log /var/log/nginx/discord-bot.access.log;
error_log /var/log/nginx/discord-bot.error.log;
}
```
**SSL Certificate:**
- Provider: Let's Encrypt
- Issued: March 27, 2026
- Expires: June 25, 2026
- Auto-renewal: Certbot handles this automatically
---
## Dependencies
**Node.js:** v20.20.0 (LTS)
**npm:** 10.8.2
**npm Packages:**
```json
{
"discord.js": "^14.14.1",
"express": "^4.18.2",
"body-parser": "^1.20.2",
"express-session": "^1.18.1",
"passport": "^0.7.0",
"passport-discord": "^0.1.4",
"cookie-parser": "^1.4.7",
"dotenv": "^17.3.1"
}
```
**Install dependencies:**
```bash
cd /opt/firefrost-discord-bot
npm install
```
---
## Admin Panel Features
**Role Management:**
- View all 10 subscription tiers
- Add/update Discord role IDs
- See current role status (configured/not configured)
- Real-time validation of role IDs
**Authentication:**
- Discord OAuth2 login
- Whitelist-based authorization (only Holly, Meg, Michael)
- Session-based authentication with secure cookies
**User Interface:**
- Fire Path tiers (orange accent)
- Frost Path tiers (cyan accent)
- Universal tiers (purple accent)
- Responsive design
- User avatar and logout in header
---
## Webhook Endpoints
**Paymenter Webhook:**
- URL: `https://discord-bot.firefrostgaming.com/webhook/paymenter`
- Method: POST
- Content-Type: application/json
**Expected Payload:**
```json
{
"event": "subscription.created",
"user": {
"discord_id": "123456789012345678"
},
"product": {
"slug": "fire-elemental",
"id": "1"
}
}
```
**Supported Events:**
- `subscription.created` - Add role
- `subscription.renewed` - Add role
- `subscription.cancelled` - Remove role
- `subscription.expired` - Remove role
**Health Check:**
- URL: `https://discord-bot.firefrostgaming.com/health`
- Method: GET
- Returns: Bot status, uptime
---
## OAuth2 Configuration
**Discord Developer Portal:**
- Application: The Arbiter
- Client ID: `1487080166969577502`
- Redirect URI: `https://discord-bot.firefrostgaming.com/auth/discord/callback`
**OAuth2 Scopes:**
- `identify` - Read user profile
**Privileged Gateway Intents (Enabled):**
- Presence Intent ✅
- Server Members Intent ✅ (CRITICAL for role assignment)
- Message Content Intent ✅
---
## Troubleshooting
### Bot Shows Offline in Discord
```bash
# Check service status
systemctl status firefrost-discord-bot
# Check logs for errors
journalctl -u firefrost-discord-bot -n 50
```
**Common causes:**
- Invalid bot token
- Discord API outage
- Service not running
### Admin Panel Login Loop
**Symptoms:** Redirects to login after authorizing Discord
**Solution:** Verify `app.set('trust proxy', 1);` is present in bot.js (line 62)
**Why this happens:** Nginx does SSL termination, Express sees HTTP requests, refuses to set secure cookies without trusting X-Forwarded-Proto header.
### Role Not Assigned After Webhook
```bash
# Check webhook logs
journalctl -u firefrost-discord-bot | grep "Webhook received"
# Verify role mapping exists
cat /opt/firefrost-discord-bot/role-mappings.json
# Check Discord bot permissions
# Bot must have "Manage Roles" permission
# Bot's role must be HIGHER than the roles it's assigning
```
### Nginx 502 Bad Gateway
```bash
# Verify bot is listening on port 3500
netstat -tlnp | grep 3500
# Restart bot service
systemctl restart firefrost-discord-bot
# Check Nginx config
nginx -t
```
---
## Deployment History
**March 27, 2026 - Initial Deployment**
- Created Discord bot application "The Arbiter"
- Generated icon and banner via Gemini AI
- Deployed bot.js on Command Center
- Configured systemd service
- Set up Nginx reverse proxy with Let's Encrypt SSL
- Deployed admin panel with Discord OAuth2
- Fixed SSL termination / secure cookie issue with `app.set('trust proxy', 1);`
- Created Holly's role setup guide
- Status: ✅ Operational, pending Holly's role ID population
---
## Security Considerations
**Secrets Management:**
- All credentials in .env file
- .env never committed to Git
- Session secret auto-generated with openssl
- Client secret rotated during deployment
**Authentication:**
- Whitelist-based admin access (3 users)
- Discord OAuth2 for identity verification
- Session-based authentication
- Secure cookies in production
**Network Security:**
- Bot only accessible via HTTPS
- Nginx handles SSL termination
- Internal port 3500 not exposed externally
- Rate limiting via Nginx (if needed, add later)
**Bot Permissions:**
- Minimal Discord permissions (Manage Roles, Send Messages)
- No Administrator permission
- Bot role positioned correctly in Discord hierarchy
---
## Future Enhancements
**Potential additions:**
- Audit logging to Discord channel for role changes
- Webhook retry logic for failed deliveries
- Role assignment history/statistics
- Integration with LuckPerms for in-game permission sync
- Multi-server support (if Firefrost expands to multiple Discord servers)
---
## Related Documentation
- **Holly's Role Setup Guide:** `docs/guides/holly-discord-roles-setup.md`
- **Subscription Automation Guide:** `docs/guides/subscription-automation-guide.md`
- **Discord Bot Admin Panel Guide:** `docs/guides/discord-bot-admin-panel.md`
- **Paymenter Configuration:** `docs/services/paymenter-configuration.md`
- **LuckPerms MySQL Database:** `docs/services/luckperms-mysql-database.md`
---
## Support Contacts
**Technical Issues:**
- Michael (Frostystyle) - Server owner, technical lead
- Discord: #staff-lounge channel
**Role Management Questions:**
- Holly (unicorn20089) - Lead builder, role configuration
---
**Last Updated:** March 27, 2026
**Maintained By:** The Verifier (Chronicler #42)
**Status:** Production - Operational ✅