From 6f633c94b4970a598c3a135c9cd86625397ff335 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 22 Mar 2026 05:29:00 +0000 Subject: [PATCH] docs: Add comprehensive deployment guides for Holly MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Created two detailed deployment guides for server-side infrastructure: 1. Server-Side Mod Deployment Guide (976 lines) - Complete mod installation walkthrough (LuckPerms, FTB suite, WorldEdit, etc.) - MySQL database setup instructions for Michael - Per-mod configuration with exact commands - Version-flexible Discord integration (1.16.5, 1.20.x, 1.21.x) - Testing checklist and troubleshooting - Accessibility-focused (Holly can follow step-by-step) 2. Subscription Automation Guide (1000+ lines) - Michael's pre-setup section (Discord bot deployment) - Complete Paymenter → Discord → LuckPerms automation - Discord role configuration - LuckPerms group creation (all 11 tiers) - Webhook integration setup - End-to-end testing procedures Both guides designed for Holly to implement with Michael handling backend setup (MySQL, Discord bot, SSL certificates). Covers: Forge/NeoForge versions, subscriber tier automation, cross-server permission sync via MySQL, whitelist automation. Chronicler #40 --- .../server-side-mod-deployment-guide.md | 976 ++++++++++++ docs/guides/subscription-automation-guide.md | 1338 +++++++++++++++++ 2 files changed, 2314 insertions(+) create mode 100644 docs/guides/server-side-mod-deployment-guide.md create mode 100644 docs/guides/subscription-automation-guide.md diff --git a/docs/guides/server-side-mod-deployment-guide.md b/docs/guides/server-side-mod-deployment-guide.md new file mode 100644 index 0000000..eea770f --- /dev/null +++ b/docs/guides/server-side-mod-deployment-guide.md @@ -0,0 +1,976 @@ +# Firefrost Gaming - Server-Side Mod Deployment Guide + +**Version:** 1.0 +**Date:** March 23, 2026 +**Author:** Chronicler #40 +**Audience:** Holly (Lead Builder) - Step-by-step implementation guide +**Purpose:** Deploy all required server-side mods across 13+ Minecraft servers + +--- + +## 📋 TABLE OF CONTENTS + +1. [Overview](#overview) +2. [Before You Start - Michael's Setup Tasks](#before-you-start) +3. [Required Mods List](#required-mods-list) +4. [Installation Process](#installation-process) +5. [Per-Mod Configuration](#per-mod-configuration) +6. [Testing & Verification](#testing-verification) +7. [Troubleshooting](#troubleshooting) +8. [Reference](#reference) + +--- + +## 🎯 OVERVIEW + +### What This Guide Does + +This guide walks you through installing and configuring server-side mods on all Firefrost Gaming Minecraft servers. These mods handle: +- Permissions and ranks (LuckPerms) +- Chunk claiming (FTB Chunks) +- Homes and teleports (FTB Essentials) +- Building tools (WorldEdit) +- Discord integration +- And more + +### Servers You'll Configure + +**Total: 13 servers** across two dedicated machines: + +**TX1 Dallas (38.68.14.26):** +- 6-7 modpack servers + +**NC1 Charlotte (216.239.104.130):** +- 6-7 modpack servers + +### Time Estimate + +- **Per server:** 30-45 minutes +- **All 13 servers:** 6-8 hours (spread across multiple days is fine) + +### What You Need + +- SSH access to TX1 and NC1 +- Pterodactyl Panel access (panel.firefrostgaming.com) +- This guide +- Michael's help for MySQL setup (see next section) + +--- + +## 🔧 BEFORE YOU START - MICHAEL'S SETUP TASKS + +**STOP: Michael needs to complete this section BEFORE you start installing mods.** + +### Task 1: MySQL Database Setup on Command Center + +Michael will set up a MySQL database that all 13 servers will connect to for LuckPerms. + +**Michael's Steps:** + +```bash +# SSH to Command Center +ssh root@63.143.34.217 + +# Access MySQL +mysql -u root -p + +# Create database +CREATE DATABASE luckperms CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; + +# Create user (change password!) +CREATE USER 'luckperms'@'%' IDENTIFIED BY 'CHANGE_THIS_PASSWORD'; + +# Grant permissions +GRANT ALL PRIVILEGES ON luckperms.* TO 'luckperms'@'%'; +FLUSH PRIVILEGES; + +# Verify +SHOW DATABASES; +SELECT User, Host FROM mysql.user WHERE User='luckperms'; + +# Exit +exit +``` + +**What Michael gives you:** +- Database host: `63.143.34.217` +- Database name: `luckperms` +- Database user: `luckperms` +- Database password: `[password Michael sets]` +- Database port: `3306` (default MySQL) + +**Save these credentials securely - you'll need them for EVERY server.** + +### Task 2: Store Credentials in Vaultwarden + +Michael will store the MySQL credentials in Vaultwarden so you can access them securely. + +**Location:** Vaultwarden → Firefrost Gaming → "LuckPerms MySQL Credentials" + +--- + +## 📦 REQUIRED MODS LIST + +### Core Mods (Required on ALL servers) + +#### 1. **LuckPerms** +**What it does:** Permission management system. Controls who can do what (ranks, permissions, subscriber tiers). + +**Why we need it:** This is how subscriber tiers work. Awakened subscribers get 1 home, Elemental gets 5 homes, etc. LuckPerms manages all of that. + +**Versions needed:** +- 1.16.5: LuckPerms Forge v5.4.x +- 1.20.x: LuckPerms Forge/NeoForge v5.4.x +- 1.21.x: LuckPerms NeoForge v5.4.x + +**Download:** https://luckperms.net/download + +--- + +#### 2. **FTB Chunks (Forge/NeoForge)** +**What it does:** Chunk claiming and protection. Players claim chunks to protect their builds. + +**Why we need it:** Subscriber tiers give different chunk limits. Awakened = 0 chunks, Elemental = 25 chunks, Knight = 49 chunks, etc. + +**Versions needed:** +- 1.16.5: FTB Chunks Forge +- 1.20.x: FTB Chunks Forge/NeoForge +- 1.21.x: FTB Chunks NeoForge + +**Download:** https://www.curseforge.com/minecraft/mc-mods/ftb-chunks-forge + +--- + +#### 3. **FTB Essentials** +**What it does:** Essential commands like /home, /sethome, /rtp (random teleport), /spawn, /back. + +**Why we need it:** Subscriber tiers have different home limits and /rtp cooldowns. This mod enforces those limits. + +**Versions needed:** +- 1.16.5: FTB Essentials Forge +- 1.20.x: FTB Essentials Forge/NeoForge +- 1.21.x: FTB Essentials NeoForge + +**Download:** https://www.curseforge.com/minecraft/mc-mods/ftb-essentials-forge + +--- + +#### 4. **FTB Library** (Dependency) +**What it does:** Required library for FTB Chunks and FTB Essentials to work. + +**Why we need it:** FTB mods won't run without this. + +**Download:** https://www.curseforge.com/minecraft/mc-mods/ftb-library-forge + +--- + +#### 5. **FTB Teams** +**What it does:** Team system that integrates with FTB Chunks. Players can form teams and share chunk claims. + +**Why we need it:** Better than solo chunk claiming - teams can build together. + +**Download:** https://www.curseforge.com/minecraft/mc-mods/ftb-teams-forge + +--- + +#### 6. **WorldEdit** +**What it does:** Powerful building and editing tool. Copy/paste structures, fill areas, replace blocks, etc. + +**Why we need it:** Essential for builders (like you!). Staff rank gets full WorldEdit access. + +**Versions needed:** +- 1.16.5: WorldEdit Forge +- 1.20.x: WorldEdit Forge/NeoForge +- 1.21.x: WorldEdit NeoForge + +**Download:** https://enginehub.org/worldedit + +--- + +#### 7. **YAWP (Yet Another World Protector)** +**What it does:** Advanced world protection and region management. Protect spawn areas, create safe zones, etc. + +**Why we need it:** Protects important areas like spawn, prevents griefing in public spaces. + +**Download:** https://www.curseforge.com/minecraft/mc-mods/yawp (check version availability) + +--- + +### Performance & Optimization Mods (Highly Recommended) + +#### 8. **ServerCore** +**What it does:** Server-side performance optimizations. Reduces lag, improves TPS (ticks per second). + +**Why we need it:** Running 13 servers requires good performance. This helps. + +**Download:** https://www.curseforge.com/minecraft/mc-mods/servercore + +--- + +#### 9. **FerriteCore** +**What it does:** Reduces memory usage significantly (up to 30-40% in some cases). + +**Why we need it:** Less RAM per server = more stable operation across all 13 servers. + +**Download:** https://www.curseforge.com/minecraft/mc-mods/ferritecore + +--- + +#### 10. **Spark** +**What it does:** Performance profiling and monitoring. Helps diagnose lag. + +**Why we need it:** When a server lags, Spark tells us why (which mod, which chunk, etc.). + +**Download:** https://spark.lucko.me/download + +--- + +### Protection & Rollback Mods + +#### 11. **Prism** (if available for your version) +**What it does:** Block logging and rollback protection. Records who placed/broke what blocks. + +**Why we need it:** If someone griefs a subscriber's build, we can roll it back and prove who did it. + +**Status:** Check if Prism exists for Forge/NeoForge on your version. If not available, rely on backups. + +**Download:** Search CurseForge for "Prism Forge" + your version + +--- + +### Quality of Life Mods (Optional but Recommended) + +#### 12. **Waystones** +**What it does:** Fast travel between waystone structures. Players place waystones and teleport between them. + +**Why we might use it:** Nice QoL feature. Could tie cooldowns to subscriber tiers (like /rtp). + +**Status:** Optional - only install if the modpack doesn't already include it. + +**Download:** https://www.curseforge.com/minecraft/mc-mods/waystones + +--- + +#### 13. **Corpse** or **You're In Grave Danger** +**What it does:** When you die, your items are stored in a grave/corpse instead of scattering. + +**Why we might use it:** Much better death experience for subscribers. Items protected, easy to retrieve. + +**Download:** Search CurseForge for your version + +--- + +### Discord Integration (Version-Dependent) + +#### 14. **Discord Integration Mod** + +**What it does:** Connects Minecraft server to Discord. Shows in-game chat in Discord channel, and vice versa. + +**Recommended mods by version:** + +**For 1.16.5:** +- **DiscordSRV (Forge fork)** or **Discord Integration by Cadiboo** +- Download: Search "DiscordSRV Forge 1.16.5" or "Discord Integration Forge" + +**For 1.20.x (NeoForge):** +- **dcintegration** +- Download: https://www.curseforge.com/minecraft/mc-mods/dcintegration + +**For 1.21.x (NeoForge):** +- **dcintegration** (if updated) or check modpack for built-in integration +- Download: https://www.curseforge.com/minecraft/mc-mods/dcintegration + +--- + +### Monitoring & Analytics + +#### 15. **Plan** (Optional) +**What it does:** Player analytics dashboard. Track playtime, most active players, server performance over time. + +**Why we might use it:** Helps Michael/Meg understand player engagement and server health. + +**Download:** https://www.playeranalytics.net/ + +--- + +### Voice Chat (Optional, if modpack includes it) + +#### 16. **Simple Voice Chat** +**What it does:** Proximity voice chat in-game. Talk to players near you. + +**Status:** Only configure if the modpack already has it installed. Don't add it separately. + +**If present:** Configure permissions via LuckPerms (which tiers can use voice). + +--- + +## 🚀 INSTALLATION PROCESS + +### Step 1: Access the Server + +You'll be working through **Pterodactyl Panel** (easier) or **SSH** (advanced). + +#### Option A: Via Pterodactyl Panel (Recommended) + +1. Go to https://panel.firefrostgaming.com +2. Log in +3. Click on the server you want to configure +4. Go to **Files** tab +5. Navigate to `/mods/` directory + +#### Option B: Via SSH (Advanced) + +```bash +# SSH to TX1 +ssh root@38.68.14.26 + +# Or SSH to NC1 +ssh root@216.239.104.130 + +# Find your server directory +cd /var/lib/pterodactyl/volumes/[server-uuid]/mods/ +``` + +--- + +### Step 2: Download Mods + +**For each mod:** + +1. Go to the mod's download page (links above) +2. Select your Minecraft version +3. Select Forge or NeoForge (match what the modpack uses) +4. Download the `.jar` file + +**Example: Downloading LuckPerms for 1.20.1 NeoForge** + +1. Go to https://luckperms.net/download +2. Click "Forge/NeoForge" +3. Find version compatible with 1.20.1 +4. Download `LuckPerms-Forge-5.4.xxx.jar` + +--- + +### Step 3: Upload Mods to Server + +#### Via Pterodactyl Panel: + +1. In the **Files** tab, navigate to `/mods/` +2. Click **Upload** button (top right) +3. Drag and drop the `.jar` file +4. Wait for upload to complete + +#### Via SSH (if you prefer): + +```bash +# Upload from your local machine using SCP +scp LuckPerms-Forge-5.4.xxx.jar root@38.68.14.26:/var/lib/pterodactyl/volumes/[server-uuid]/mods/ +``` + +--- + +### Step 4: Verify Mod Installation + +**After uploading all mods:** + +1. In Pterodactyl Panel, go to **Console** tab +2. Click **Start** to start the server +3. Watch the console for mod loading messages +4. Look for lines like: + ``` + [Server thread/INFO] [LuckPerms]: Loading LuckPerms v5.4.xxx + [Server thread/INFO] [FTB Chunks]: Loading FTB Chunks + ``` + +**If you see errors:** +- Check that you downloaded the correct version (Forge vs NeoForge) +- Check that you downloaded for the correct Minecraft version +- Check server logs for "dependency missing" errors + +--- + +### Step 5: Stop Server for Configuration + +**Before configuring mods, stop the server:** + +1. In Pterodactyl Console, click **Stop** +2. Wait for server to fully shut down +3. Now you can edit configuration files + +--- + +## ⚙️ PER-MOD CONFIGURATION + +### LuckPerms Configuration + +**Location:** `/config/luckperms/luckperms.conf` + +#### Step 1: Switch to MySQL Storage + +**Find this section:** +```conf +storage-method = h2 +``` + +**Change to:** +```conf +storage-method = mysql +``` + +#### Step 2: Configure MySQL Connection + +**Find the `data` section and configure:** + +```conf +data { + # MySQL connection details + address = "63.143.34.217:3306" + database = "luckperms" + username = "luckperms" + password = "PASSWORD_FROM_MICHAEL" + + # Connection pool settings (leave these default) + pool-settings { + maximum-pool-size = 10 + minimum-idle = 10 + maximum-lifetime = 1800000 + connection-timeout = 5000 + } +} +``` + +**Replace:** +- `PASSWORD_FROM_MICHAEL` with the actual password Michael gave you + +#### Step 3: Configure Sync Settings + +**Find the `messaging-service` section:** + +```conf +messaging-service = none +``` + +**Change to:** +```conf +messaging-service = sql +``` + +**This enables cross-server permission sync via MySQL.** + +#### Step 4: Save and Close + +**Via Pterodactyl Panel:** +1. Click **Save Content** button +2. Close the editor + +--- + +### FTB Chunks Configuration + +**Location:** `/config/ftbchunks/common-config.snbt` + +**This file configures chunk claiming limits and force-loading.** + +#### Default Configuration + +The default config works, but you'll set limits via LuckPerms permissions instead. Leave this file as-is for now. + +**Key settings to note:** +- `max_claimed_chunks: 100` (default max, overridden by permissions) +- `max_force_loaded_chunks: 25` (default max, overridden by permissions) + +**We'll set per-tier limits in the Subscription Automation Guide.** + +--- + +### FTB Essentials Configuration + +**Location:** `/config/ftbessentials.snbt` + +**This file configures homes and teleports.** + +#### Key Settings to Configure + +**Find and modify:** + +```snbt +{ + # Home settings + max_homes: 1 # Default (will be overridden by LuckPerms) + + # RTP settings + rtp_cooldown: 600 # 10 minutes default (will be overridden by LuckPerms) + rtp_min_distance: 500 + rtp_max_distance: 10000 + + # Spawn settings + spawn_dimension: "minecraft:overworld" +} +``` + +**Leave defaults for now - we'll set per-tier values via LuckPerms permissions.** + +--- + +### WorldEdit Configuration + +**Location:** `/config/worldedit/worldedit.properties` + +**Default settings are fine for most servers.** + +#### Optional: Increase Max Blocks for Staff + +**If you want staff (Builder rank) to have higher limits:** + +```properties +# Maximum number of blocks that can be changed at once +max-blocks-changed=1000000 + +# Maximum number of polygonal points +max-polygon-points=20 + +# Maximum radius for commands +max-radius=1000 + +# Maximum super pickaxe size +max-super-pickaxe-size=100 +``` + +**For regular subscribers, limits are set via LuckPerms permissions.** + +--- + +### YAWP Configuration + +**Location:** `/config/yawp/` (exact path depends on YAWP version) + +**YAWP is typically configured in-game via commands.** + +**Basic setup:** + +1. Start the server +2. Join as an admin/op +3. Use commands like: + ``` + /yawp region create spawn + /yawp region flag spawn pvp deny + /yawp region flag spawn mob-spawning deny + ``` + +**Full YAWP configuration is beyond this guide - configure as needed per server.** + +--- + +### Discord Integration Configuration + +**Configuration varies by mod - choose based on your server version:** + +#### For DiscordSRV (1.16.5): + +**Location:** `/config/discordsrv/config.yml` + +```yaml +# Discord bot token (get from Michael or Discord Developer Portal) +BotToken: "YOUR_DISCORD_BOT_TOKEN" + +# Channel IDs +Channels: + global: "DISCORD_CHANNEL_ID" + +# Options +DiscordChatChannelConsoleCommandNotificationsEnabled: false +DiscordChatChannelServerStartupMessageEnabled: true +DiscordChatChannelServerShutdownMessageEnabled: true +``` + +#### For dcintegration (1.20.x / 1.21.x NeoForge): + +**Location:** `/config/dcintegration/config.toml` + +```toml +[discord] + # Bot token + token = "YOUR_DISCORD_BOT_TOKEN" + + # Channel ID for chat relay + channelId = "DISCORD_CHANNEL_ID" + +[minecraft] + # Enable chat relay + enableChatRelay = true + + # Webhook settings (optional) + useWebhook = false +``` + +**Get bot token and channel IDs from Michael.** + +--- + +### Spark Configuration + +**Location:** No config file needed! + +**Spark works out of the box.** + +**Usage:** +1. In-game, run `/spark profiler start` +2. Let it run for 30-60 seconds +3. Run `/spark profiler stop` +4. Spark gives you a web link to view results + +**Only staff (Builder rank and above) should have access to Spark commands.** + +--- + +## ✅ TESTING & VERIFICATION + +### Test Checklist - Per Server + +After configuring all mods on a server, test the following: + +#### 1. Server Starts Successfully + +- [ ] Server starts without errors +- [ ] All mods load (check console) +- [ ] No "missing dependency" errors +- [ ] Server reaches "Done" state + +#### 2. LuckPerms Works + +``` +# In-game or console, run: +/lp info + +# Should show LuckPerms version and connection status +# Should say "Storage: MySQL" (not h2 or sqlite) +``` + +#### 3. FTB Chunks Works + +``` +# In-game: +/ftbchunks + +# Should open chunk claiming GUI +# Try claiming a chunk (right-click a chunk on the map) +``` + +#### 4. FTB Essentials Works + +``` +# In-game: +/sethome test +/home test +/delhome test + +# Should set, teleport to, and delete home successfully +``` + +#### 5. WorldEdit Works + +``` +# In-game (as Builder rank): +//wand + +# Should give you a wooden axe (WorldEdit selection tool) +``` + +#### 6. Discord Integration Works + +``` +# In-game, type a message in chat +# Check Discord channel - message should appear +# Type in Discord - message should appear in-game +``` + +--- + +## 🔧 TROUBLESHOOTING + +### Server Won't Start + +**Symptom:** Server crashes on startup or gets stuck loading. + +**Common Causes:** +1. **Wrong Forge/NeoForge version** - Make sure mod matches server type +2. **Missing dependencies** - Check for "missing required mod" errors +3. **Incompatible mods** - Some mods conflict with each other +4. **Corrupted jar file** - Re-download and re-upload + +**Solution:** +1. Check server console for specific error messages +2. Look for lines like "Missing required mod: [modname]" +3. Download missing dependencies +4. If still broken, remove mods one by one to find the problem + +--- + +### LuckPerms Can't Connect to MySQL + +**Symptom:** LuckPerms loads but shows errors about database connection. + +**Common Causes:** +1. **Wrong MySQL credentials** - Double-check username, password, host, port +2. **Firewall blocking connection** - Server can't reach Command Center +3. **MySQL not running** - Database server is down + +**Solution:** +1. Check credentials in `/config/luckperms/luckperms.conf` +2. Test connection from server to MySQL: + ```bash + telnet 63.143.34.217 3306 + ``` +3. If connection fails, ask Michael to check firewall rules + +--- + +### FTB Chunks Claims Not Working + +**Symptom:** Players can't claim chunks or claims don't protect. + +**Common Causes:** +1. **Permission not granted** - Player doesn't have `ftbchunks.claim` permission +2. **Chunk limit reached** - Player hit their claim limit for their tier +3. **Protected area** - Trying to claim in spawn protection zone + +**Solution:** +1. Grant permission via LuckPerms: + ``` + /lp group awakened permission set ftbchunks.claim true + ``` +2. Check player's claim count: + ``` + /ftbchunks admin info + ``` +3. Adjust claim limits in config or via permissions + +--- + +### Discord Integration Not Working + +**Symptom:** Messages don't relay between Minecraft and Discord. + +**Common Causes:** +1. **Wrong bot token** - Discord bot token is incorrect or expired +2. **Wrong channel ID** - Pointing to wrong Discord channel +3. **Bot not in server** - Discord bot hasn't been invited to your Discord server +4. **Missing bot permissions** - Bot doesn't have Send Messages / Read Messages permissions + +**Solution:** +1. Double-check bot token in config file +2. Verify channel ID (right-click channel in Discord, Copy ID) +3. Re-invite bot to Discord server with proper permissions +4. Restart Minecraft server after config changes + +--- + +## 📚 REFERENCE + +### Quick Command Reference + +#### LuckPerms Commands + +```bash +# View user info +/lp user info + +# View group info +/lp group info + +# Add user to group +/lp user parent add + +# Set permission +/lp group permission set true + +# View all groups +/lp listgroups +``` + +#### FTB Chunks Commands + +```bash +# Open chunk claiming GUI +/ftbchunks + +# View player's claims +/ftbchunks admin info + +# Force claim for player (admin only) +/ftbchunks admin claim + +# Unclaim chunk +/ftbchunks unclaim +``` + +#### FTB Essentials Commands + +```bash +# Set home +/sethome + +# Go to home +/home + +# Delete home +/delhome + +# List homes +/homes + +# Random teleport +/rtp + +# Go back to previous location +/back +``` + +#### WorldEdit Commands (Staff Only) + +```bash +# Get selection wand +//wand + +# Set position 1 +//pos1 + +# Set position 2 +//pos2 + +# Replace blocks in selection +//replace + +# Fill area +//set + +# Copy selection +//copy + +# Paste selection +//paste +``` + +--- + +### File Locations Quick Reference + +``` +Server Root +├── mods/ +│ ├── LuckPerms-Forge-5.4.xxx.jar +│ ├── ftbchunks-forge-xxx.jar +│ ├── ftbessentials-xxx.jar +│ ├── ftblibrary-xxx.jar +│ ├── ftbteams-xxx.jar +│ ├── worldedit-forge-xxx.jar +│ ├── ServerCore-xxx.jar +│ ├── FerriteCore-xxx.jar +│ └── ... (other mods) +│ +├── config/ +│ ├── luckperms/ +│ │ └── luckperms.conf +│ ├── ftbchunks/ +│ │ └── common-config.snbt +│ ├── ftbessentials.snbt +│ ├── worldedit/ +│ │ └── worldedit.properties +│ └── ... (other configs) +│ +└── logs/ + └── latest.log +``` + +--- + +### Subscriber Tier Limits (Quick Reference) + +| Tier | Homes | Claimed Chunks | Force-Load Chunks | /rtp Cooldown | +|------|-------|----------------|-------------------|---------------| +| Wanderer | 0 | 0 | 0 | None (no access) | +| Awakened | 1 | 0 | 0 | None (no access) | +| Elemental | 5 | 25 | 0 | 60 min | +| Knight | 10 | 49 | 4 | 30 min | +| Master | 20 | 100 | 9 | 15 min | +| Legend | 35 | 121 | 16 | 10 min | +| Sovereign | 50 | 225 | 81 | None (unlimited) | + +**These limits are configured in the Subscription Automation Guide (separate document).** + +--- + +### Important Reminders + +1. **Always stop the server before editing config files** +2. **Test changes on ONE server before applying to all 13** +3. **MySQL credentials are the SAME for all servers** (they all connect to the same database) +4. **Make backups before making major changes** +5. **Ask Michael if you're unsure** - don't guess + +--- + +### Getting Help + +**If something isn't working:** + +1. **Check server console** - Most errors are logged there +2. **Check `/logs/latest.log`** - More detailed error information +3. **Ask Michael** - He can check from the backend +4. **Discord/Pterodactyl Panel** - Michael can see console remotely + +**When asking for help, provide:** +- Which server (name/IP) +- What you were trying to do +- Exact error message from console/logs +- What you've already tried + +--- + +## 🎯 DEPLOYMENT CHECKLIST + +Use this checklist to track your progress across all 13 servers. + +### TX1 Dallas Servers + +- [ ] Server 1: All mods installed, configured, tested +- [ ] Server 2: All mods installed, configured, tested +- [ ] Server 3: All mods installed, configured, tested +- [ ] Server 4: All mods installed, configured, tested +- [ ] Server 5: All mods installed, configured, tested +- [ ] Server 6: All mods installed, configured, tested +- [ ] Server 7: All mods installed, configured, tested (if applicable) + +### NC1 Charlotte Servers + +- [ ] Server 1: All mods installed, configured, tested +- [ ] Server 2: All mods installed, configured, tested +- [ ] Server 3: All mods installed, configured, tested +- [ ] Server 4: All mods installed, configured, tested +- [ ] Server 5: All mods installed, configured, tested +- [ ] Server 6: All mods installed, configured, tested +- [ ] Server 7: All mods installed, configured, tested (if applicable) + +### Post-Deployment + +- [ ] All servers connecting to MySQL successfully +- [ ] LuckPerms syncing across all servers +- [ ] FTB Chunks working on all servers +- [ ] FTB Essentials working on all servers +- [ ] WorldEdit permissions configured for Builder rank +- [ ] Discord integration tested on at least one server per modpack type +- [ ] Documented any server-specific issues or configurations + +--- + +**End of Server-Side Mod Deployment Guide** + +**Next Step:** Proceed to **Subscription Automation Guide** to configure the Paymenter → Discord → LuckPerms integration. + +**Fire + Frost + Foundation = Where Love Builds Legacy** 🔥❄️ + +--- + +**Document Version:** 1.0 +**Last Updated:** March 23, 2026 +**Maintained By:** Firefrost Gaming Infrastructure Team diff --git a/docs/guides/subscription-automation-guide.md b/docs/guides/subscription-automation-guide.md new file mode 100644 index 0000000..6c59b31 --- /dev/null +++ b/docs/guides/subscription-automation-guide.md @@ -0,0 +1,1338 @@ +# Firefrost Gaming - Subscription Automation Guide + +**Version:** 1.0 +**Date:** March 23, 2026 +**Author:** Chronicler #40 +**Audience:** Holly (Lead Builder) + Michael (for Discord bot setup) +**Purpose:** Automate subscriber tier assignment from Paymenter purchase to in-game ranks + +--- + +## 📋 TABLE OF CONTENTS + +1. [Overview](#overview) +2. [Architecture](#architecture) +3. [Prerequisites](#prerequisites) +4. [Part 1: Discord Bot Setup](#part-1-discord-bot-setup) +5. [Part 2: Discord Roles Configuration](#part-2-discord-roles-configuration) +6. [Part 3: LuckPerms Groups & Permissions](#part-3-luckperms-groups-permissions) +7. [Part 4: LuckPerms Discord Integration](#part-4-luckperms-discord-integration) +8. [Part 5: Paymenter Webhook Configuration](#part-5-paymenter-webhook-configuration) +9. [Testing & Verification](#testing-verification) +10. [Troubleshooting](#troubleshooting) + +--- + +## 🎯 OVERVIEW + +### What This Guide Does + +This guide sets up **fully automated subscription management**: + +1. User purchases subscription in Paymenter +2. Paymenter sends webhook to Discord bot +3. Discord bot assigns appropriate role to user +4. LuckPerms detects Discord role and syncs to in-game rank +5. Player automatically gets correct permissions on all 13 servers + +**No manual work required after setup.** + +### The Flow + +``` +User Subscribes ($1-$499) + ↓ +Paymenter (billing.firefrostgaming.com) + ↓ +Webhook fires (new purchase detected) + ↓ +Discord Bot receives webhook + ↓ +Bot assigns Discord role (The Awakened, Fire Elemental, etc.) + ↓ +LuckPerms syncs Discord role → In-game group + ↓ +Player gets permissions on all 13 servers instantly + ↓ +Player can join servers, claim chunks, set homes (based on tier) +``` + +### Time Estimate + +- **Discord Bot Setup:** 1-2 hours (Michael + Holly) +- **Discord Roles:** 30 minutes (Holly) +- **LuckPerms Configuration:** 2-3 hours (Holly, across all 13 servers) +- **Paymenter Webhooks:** 1 hour (Michael + Holly testing) + +**Total:** 4-6 hours + +--- + +## 🏗️ ARCHITECTURE + +### Components + +1. **Paymenter** (billing.firefrostgaming.com) - Billing system +2. **Discord Server** - Community hub +3. **Discord Bot** - Automation middleman +4. **LuckPerms** - Permission management (all 13 game servers) +5. **MySQL Database** - Shared permission storage + +### Why This Design? + +**Why not direct Paymenter → LuckPerms?** +- Discord is the community hub - subscribers want Discord access too +- Discord roles provide social status and channel access +- Discord bot can handle complex logic (upgrades, downgrades, cancellations) +- Easier to troubleshoot (can see Discord roles visually) + +**Why LuckPerms syncs FROM Discord?** +- Industry standard approach +- Discord becomes "source of truth" for subscriber status +- If someone loses subscriber role in Discord, they automatically lose in-game perks +- Prevents desync between Discord and game servers + +--- + +## ✅ PREREQUISITES + +### Before You Start + +**Complete these first:** + +- [ ] **Server-Side Mod Deployment Guide** completed on ALL 13 servers +- [ ] LuckPerms installed and connected to MySQL on all servers +- [ ] Michael has created MySQL database and provided credentials +- [ ] You have admin access to Firefrost Gaming Discord server +- [ ] You have access to Paymenter admin panel + +### What You'll Need + +**From Michael:** +- Discord bot token (Michael will create this) +- Paymenter admin credentials +- MySQL database credentials (already provided for LuckPerms) + +**Access Required:** +- Discord server admin permissions +- Pterodactyl panel access (to restart servers) +- SSH access to game servers (for testing) + +--- + +## 🤖 PART 1: DISCORD BOT SETUP + +--- + +## 🔧 MICHAEL'S PRE-SETUP (Complete BEFORE Holly Starts) + +**STOP: Michael must complete this entire section BEFORE handing the guide to Holly.** + +### Task 1: Create Discord Application & Bot + +**Michael's steps:** + +1. Go to https://discord.com/developers/applications +2. Click **New Application** +3. Name: "Firefrost Subscription Manager" +4. Click **Create** + +### Task 2: Configure Bot Settings + +1. In the application, go to **Bot** tab (left sidebar) +2. Click **Add Bot** → **Yes, do it!** +3. Under **Privileged Gateway Intents**, enable: + - ✅ **Server Members Intent** (REQUIRED - bot needs to assign roles) + - ✅ **Message Content Intent** (REQUIRED - bot needs to read webhook data) +4. Click **Save Changes** + +### Task 3: Get Bot Token + +1. Under **Bot** tab, find **Token** section +2. Click **Reset Token** (confirm if asked) +3. Click **Copy** to copy the token +4. **SAVE THIS TOKEN SECURELY** - you'll give it to Holly later + +**The token looks like:** +``` +MTxxxxxxxxxxxxxxxxxxxxxx.xxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxx +``` + +**⚠️ NEVER share this token publicly or commit it to git!** + +### Task 4: Invite Bot to Discord Server + +1. Go to **OAuth2** tab → **URL Generator** (left sidebar) +2. Under **Scopes**, select: + - ✅ `bot` + - ✅ `applications.commands` +3. Under **Bot Permissions**, select: + - ✅ **Manage Roles** (REQUIRED - assigns subscriber roles) + - ✅ **Send Messages** (for welcome DMs) + - ✅ **Read Message History** (optional) + - ✅ **Use Slash Commands** (future-proofing) +4. Scroll down and **Copy** the generated URL +5. Open the URL in a new browser tab +6. Select **Firefrost Gaming** server from dropdown +7. Click **Authorize** +8. Complete the CAPTCHA + +**The bot should now appear in your Discord server's member list (offline status is normal - it's not running yet).** + +### Task 5: Get Discord Server ID (Guild ID) + +1. Open Discord +2. Go to **User Settings** (gear icon) +3. Go to **Advanced** (left sidebar) +4. Enable **Developer Mode** ✅ +5. Close settings +6. Right-click your **Firefrost Gaming** server icon +7. Click **Copy Server ID** +8. **Save this ID** - you'll give it to Holly + +**The ID looks like:** +``` +123456789012345678 +``` + +### Task 6: Deploy Bot Code on Command Center + +**SSH to Command Center:** + +```bash +ssh root@63.143.34.217 +``` + +**Install Node.js (if not already installed):** + +```bash +# Check if Node.js is installed +node --version + +# If not installed or version < 18, install Node.js 20: +curl -fsSL https://deb.nodesource.com/setup_20.x | bash - +apt-get install -y nodejs + +# Verify +node --version # Should show v20.x.x +npm --version # Should show 10.x.x +``` + +**Create bot directory:** + +```bash +mkdir -p /opt/firefrost-discord-bot +cd /opt/firefrost-discord-bot +``` + +**Create package.json:** + +```bash +cat > package.json << 'EOF' +{ + "name": "firefrost-discord-bot", + "version": "1.0.0", + "description": "Firefrost Gaming subscription automation bot", + "main": "bot.js", + "scripts": { + "start": "node bot.js" + }, + "dependencies": { + "discord.js": "^14.14.1", + "express": "^4.18.2", + "body-parser": "^1.20.2" + } +} +EOF +``` + +**Install dependencies:** + +```bash +npm install +``` + +**Create bot.js file:** + +```bash +cat > bot.js << 'EOF' +// Firefrost Gaming - Discord Subscription Bot +// Handles Paymenter webhooks and assigns Discord roles + +const { Client, GatewayIntentBits } = require('discord.js'); +const express = require('express'); +const bodyParser = require('body-parser'); + +// Configuration - REPLACE THESE VALUES +const DISCORD_TOKEN = 'YOUR_BOT_TOKEN_HERE'; +const GUILD_ID = 'YOUR_GUILD_ID_HERE'; + +// Product ID to Role ID mapping (from Paymenter) +// Holly will fill these in after creating Discord roles +const PRODUCT_ROLE_MAP = { + '2': 'AWAKENED_ROLE_ID', + '3': 'FIRE_ELEMENTAL_ROLE_ID', + '4': 'FROST_ELEMENTAL_ROLE_ID', + '5': 'FIRE_KNIGHT_ROLE_ID', + '6': 'FROST_KNIGHT_ROLE_ID', + '7': 'FIRE_MASTER_ROLE_ID', + '8': 'FROST_MASTER_ROLE_ID', + '9': 'FIRE_LEGEND_ROLE_ID', + '10': 'FROST_LEGEND_ROLE_ID', + '11': 'SOVEREIGN_ROLE_ID' +}; + +// Initialize Discord client +const client = new Client({ + intents: [ + GatewayIntentBits.Guilds, + GatewayIntentBits.GuildMembers + ] +}); + +// Initialize Express for webhook receiver +const app = express(); +app.use(bodyParser.json()); + +// Discord bot ready event +client.once('ready', () => { + console.log(`✅ Bot logged in as ${client.user.tag}`); + console.log(`🔗 Connected to ${client.guilds.cache.size} server(s)`); +}); + +// Webhook endpoint - Paymenter sends POST here +app.post('/webhook/paymenter', async (req, res) => { + try { + console.log('📬 Received webhook from Paymenter'); + console.log('Payload:', JSON.stringify(req.body, null, 2)); + + const { event, product_id, user_email, discord_id } = req.body; + + // Validate webhook + if (!event || !product_id) { + console.error('❌ Invalid webhook data - missing event or product_id'); + return res.status(400).json({ error: 'Missing required fields' }); + } + + if (!discord_id) { + console.error('⚠️ No discord_id provided - cannot assign role'); + return res.status(400).json({ error: 'Missing discord_id' }); + } + + console.log(`📦 Event: ${event}, Product: ${product_id}, Discord ID: ${discord_id}`); + + // Get Discord guild + const guild = client.guilds.cache.get(GUILD_ID); + if (!guild) { + console.error('❌ Guild not found'); + return res.status(500).json({ error: 'Guild not found' }); + } + + // Get member + const member = await guild.members.fetch(discord_id); + if (!member) { + console.error('❌ Member not found in Discord server'); + return res.status(404).json({ error: 'Member not found' }); + } + + // Get role ID for this product + const roleId = PRODUCT_ROLE_MAP[product_id]; + if (!roleId || roleId.includes('ROLE_ID')) { + console.error(`❌ No role mapped for product ${product_id} (or role ID not configured)`); + return res.status(400).json({ error: 'Unknown product or role not configured' }); + } + + // Handle event + if (event === 'subscription.created' || event === 'payment.completed') { + // Add role + await member.roles.add(roleId); + console.log(`✅ Added role ${roleId} to ${member.user.tag}`); + + // Send welcome DM + try { + await member.send(`🎉 Welcome to Firefrost Gaming! Your subscription is now active. Check out the server - your perks are ready!`); + console.log(`📨 Sent welcome DM to ${member.user.tag}`); + } catch (err) { + console.log('⚠️ Could not send DM (user has DMs disabled)'); + } + + } else if (event === 'subscription.cancelled' || event === 'subscription.expired') { + // Remove role + await member.roles.remove(roleId); + console.log(`❌ Removed role ${roleId} from ${member.user.tag}`); + + } else { + console.log(`⚠️ Unknown event type: ${event}`); + } + + res.status(200).json({ success: true }); + + } catch (error) { + console.error('❌ Webhook processing error:', error); + res.status(500).json({ error: 'Internal server error', details: error.message }); + } +}); + +// Health check endpoint +app.get('/health', (req, res) => { + res.status(200).json({ + status: 'healthy', + bot: client.user ? client.user.tag : 'disconnected', + uptime: process.uptime() + }); +}); + +// Start Express server +const PORT = 3100; +app.listen(PORT, () => { + console.log(`🌐 Webhook server listening on port ${PORT}`); + console.log(`📍 Webhook URL: http://localhost:${PORT}/webhook/paymenter`); +}); + +// Start Discord bot +client.login(DISCORD_TOKEN); +EOF +``` + +**Edit bot.js and add your credentials:** + +```bash +nano bot.js +``` + +**Find these lines:** +```javascript +const DISCORD_TOKEN = 'YOUR_BOT_TOKEN_HERE'; +const GUILD_ID = 'YOUR_GUILD_ID_HERE'; +``` + +**Replace with:** +```javascript +const DISCORD_TOKEN = 'MTxxxx...'; // Your actual bot token from Task 3 +const GUILD_ID = '123456789012345678'; // Your actual server ID from Task 5 +``` + +**Save and exit** (Ctrl+X, Y, Enter) + +**Create systemd service:** + +```bash +cat > /etc/systemd/system/firefrost-discord-bot.service << 'EOF' +[Unit] +Description=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 + +[Install] +WantedBy=multi-user.target +EOF +``` + +**Enable and start the bot:** + +```bash +# Reload systemd +systemctl daemon-reload + +# Enable auto-start on boot +systemctl enable firefrost-discord-bot + +# Start the bot +systemctl start firefrost-discord-bot + +# Check status +systemctl status firefrost-discord-bot +``` + +**You should see:** +``` +● firefrost-discord-bot.service - Firefrost Gaming Discord Bot + Loaded: loaded + Active: active (running) +``` + +**View logs to confirm it's working:** + +```bash +journalctl -u firefrost-discord-bot -f +``` + +**You should see:** +``` +✅ Bot logged in as Firefrost Subscription Manager#1234 +🔗 Connected to 1 server(s) +🌐 Webhook server listening on port 3100 +``` + +**If you see errors about invalid token:** +- Double-check you copied the token correctly +- Make sure there are no extra spaces +- Verify the token hasn't been reset/revoked + +**Press Ctrl+C to exit log view when done.** + +### Task 7: Set Up Nginx Reverse Proxy + +**Still on Command Center, configure Nginx:** + +```bash +cat > /etc/nginx/sites-available/discord-webhook << 'EOF' +server { + listen 80; + server_name webhook.firefrostgaming.com; + + 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_cache_bypass $http_upgrade; + } +} +EOF +``` + +**Enable the site:** + +```bash +ln -s /etc/nginx/sites-available/discord-webhook /etc/nginx/sites-enabled/ +nginx -t +systemctl reload nginx +``` + +**Get SSL certificate:** + +```bash +certbot --nginx -d webhook.firefrostgaming.com +``` + +**Test the webhook endpoint:** + +```bash +curl https://webhook.firefrostgaming.com/health +``` + +**Should return:** +```json +{"status":"healthy","bot":"Firefrost Subscription Manager#1234","uptime":123.456} +``` + +### Task 8: Prepare Information for Holly + +**Create a file with all the info Holly needs:** + +```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 + +--- +Generated: $(date) +EOF + +cat /root/holly-bot-credentials.txt +``` + +**Save this output - you'll give it to Holly.** + +--- + +## ✅ MICHAEL'S PRE-SETUP COMPLETE + +**Checklist before handing to Holly:** + +- [ ] Discord bot created and invited to server +- [ ] Bot token saved securely +- [ ] Guild ID recorded +- [ ] Node.js installed on Command Center +- [ ] Bot code deployed to /opt/firefrost-discord-bot/ +- [ ] Bot service running successfully +- [ ] Nginx reverse proxy configured +- [ ] SSL certificate obtained +- [ ] Webhook endpoint accessible at https://webhook.firefrostgaming.com +- [ ] Credentials file created for Holly + +**If all checked, proceed to Part 2 and hand the guide to Holly.** + +--- + +## 👥 HOLLY'S TASKS START HERE + +**At this point, Michael has:** +- ✅ Created the Discord bot application +- ✅ Deployed bot code to Command Center +- ✅ Set up Nginx reverse proxy +- ✅ Bot is running and accessible at https://webhook.firefrostgaming.com + +**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 + +--- + +## 👥 PART 2: DISCORD ROLES CONFIGURATION + +### Step 1: Create Discord Roles (Holly's Task) + +**In your Discord server:** + +1. Right-click server icon → **Server Settings** +2. Click **Roles** +3. Click **Create Role** for each tier + +**Create these roles (in order, top to bottom):** + +#### Role 1: Sovereign (Founder) +- **Name:** `⚡ Sovereign` +- **Color:** `#FFD600` (Amber Gold) +- **Permissions:** (default member permissions) +- **Display separately:** ✅ Yes +- **Mentionable:** ✅ Yes + +#### Role 2: Fire Legend +- **Name:** `🔥 Fire Legend` +- **Color:** `#FF3D00` (Deep Orange/Red) +- **Permissions:** (default member permissions) +- **Display separately:** ✅ Yes + +#### Role 3: Frost Legend +- **Name:** `❄️ Frost Legend` +- **Color:** `#00E5FF` (Electric Cyan) +- **Permissions:** (default member permissions) +- **Display separately:** ✅ Yes + +#### Role 4: Fire Master +- **Name:** `🔥 Fire Master` +- **Color:** `#FF3D00` +- **Permissions:** (default member permissions) +- **Display separately:** ✅ Yes + +#### Role 5: Frost Master +- **Name:** `❄️ Frost Master` +- **Color:** `#00E5FF` +- **Permissions:** (default member permissions) +- **Display separately:** ✅ Yes + +#### Role 6: Fire Knight +- **Name:** `🔥 Fire Knight` +- **Color:** `#FF3D00` +- **Permissions:** (default member permissions) +- **Display separately:** ✅ Yes + +#### Role 7: Frost Knight +- **Name:** `❄️ Frost Knight` +- **Color:** `#00E5FF` +- **Permissions:** (default member permissions) +- **Display separately:** ✅ Yes + +#### Role 8: Fire Elemental +- **Name:** `🔥 Fire Elemental` +- **Color:** `#FF3D00` +- **Permissions:** (default member permissions) +- **Display separately:** ✅ Yes + +#### Role 9: Frost Elemental +- **Name:** `❄️ Frost Elemental` +- **Color:** `#00E5FF` +- **Permissions:** (default member permissions) +- **Display separately:** ✅ Yes + +#### Role 10: The Awakened +- **Name:** `The Awakened` +- **Color:** `#FFFFFF` (White) +- **Permissions:** (default member permissions) +- **Display separately:** ✅ Yes + +#### Role 11: Wanderer (Free) +- **Name:** `Wanderer` +- **Color:** `#99AAB5` (Gray) +- **Permissions:** Read messages only (restrict Send Messages in channels) +- **Display separately:** No + +### Step 2: Get Role IDs + +**For each role you just created:** + +1. Right-click the role in Server Settings → Roles +2. Click **Copy ID** (if you don't see this, enable Developer Mode in Discord settings) +3. Paste the ID somewhere - you'll need them + +**Create a mapping:** +``` +The Awakened: 123456789012345678 +Fire Elemental: 234567890123456789 +Frost Elemental: 345678901234567890 +Fire Knight: 456789012345678901 +Frost Knight: 567890123456789012 +Fire Master: 678901234567890123 +Frost Master: 789012345678901234 +Fire Legend: 890123456789012345 +Frost Legend: 901234567890123456 +Sovereign: 012345678901234567 +``` + +### Step 3: Update Bot Code with Role IDs + +**Edit `/opt/firefrost-discord-bot/bot.js`:** + +Replace the `PRODUCT_ROLE_MAP` section: + +```javascript +const PRODUCT_ROLE_MAP = { + '2': '123456789012345678', // The Awakened + '3': '234567890123456789', // Fire Elemental + '4': '345678901234567890', // Frost Elemental + '5': '456789012345678901', // Fire Knight + '6': '567890123456789012', // Frost Knight + '7': '678901234567890123', // Fire Master + '8': '789012345678901234', // Frost Master + '9': '890123456789012345', // Fire Legend + '10': '901234567890123456', // Frost Legend + '11': '012345678901234567' // Sovereign +}; +``` + +**Restart the bot:** + +```bash +systemctl restart firefrost-discord-bot +``` + +### Step 4: Configure Channel Permissions + +**Create private channels for Fire/Frost paths:** + +#### Fire Path Channels +- `#🔥-fire-general` - Only visible to Fire Elemental+ roles +- `#🔥-fire-builds` - Only visible to Fire Elemental+ roles +- `#🔥-fire-strategy` - Only visible to Fire Elemental+ roles + +**Permissions:** +- Deny: `@everyone` - View Channel +- Allow: `@🔥 Fire Elemental`, `@🔥 Fire Knight`, `@🔥 Fire Master`, `@🔥 Fire Legend`, `@⚡ Sovereign` + +#### Frost Path Channels +- `#❄️-frost-general` - Only visible to Frost Elemental+ roles +- `#❄️-frost-builds` - Only visible to Frost Elemental+ roles +- `#❄️-frost-strategy` - Only visible to Frost Elemental+ roles + +**Permissions:** +- Deny: `@everyone` - View Channel +- Allow: `@❄️ Frost Elemental`, `@❄️ Frost Knight`, `@❄️ Frost Master`, `@❄️ Frost Legend`, `@⚡ Sovereign` + +#### The Nexus (Sovereign Only) +- `#⚡-the-nexus` - Only visible to Sovereign + +**Permissions:** +- Deny: `@everyone` - View Channel +- Allow: `@⚡ Sovereign` only + +--- + +## ⚙️ PART 3: LUCKPERMS GROUPS & PERMISSIONS + +**This is the longest section - you'll configure 11 groups across 13 servers.** + +### Step 1: Create LuckPerms Groups + +**SSH to ONE game server first (we'll sync to others after):** + +```bash +ssh root@38.68.14.26 # TX1 +# Or +ssh root@216.239.104.130 # NC1 +``` + +**Access server console via Pterodactyl Panel, then run these commands:** + +#### Create Wanderer Group (Free Tier) + +``` +/lp creategroup wanderer +/lp group wanderer setweight 10 +/lp group wanderer meta setprefix "&7[Wanderer] " +/lp group wanderer meta setsuffix "" +``` + +#### Create Awakened Group ($1 Tier) + +``` +/lp creategroup awakened +/lp group awakened parent add wanderer +/lp group awakened setweight 20 +/lp group awakened meta setprefix "&f[The Awakened] " + +# Permissions +/lp group awakened permission set ftbessentials.home.set true +/lp group awakened permission set ftbessentials.home.teleport true +/lp group awakened meta setmeta max-homes 1 +``` + +#### Create Fire Elemental Group ($5/mo) + +``` +/lp creategroup fire_elemental +/lp group fire_elemental parent add awakened +/lp group fire_elemental setweight 30 +/lp group fire_elemental meta setprefix "&c[🔥 Fire Elemental] " + +# Permissions +/lp group fire_elemental meta setmeta max-homes 5 +/lp group fire_elemental permission set ftbchunks.claim true +/lp group fire_elemental meta setmeta max-claimed-chunks 25 +/lp group fire_elemental permission set ftbessentials.rtp true +/lp group fire_elemental meta setmeta rtp-cooldown 3600 +``` + +#### Create Frost Elemental Group ($5/mo) + +``` +/lp creategroup frost_elemental +/lp group frost_elemental parent add awakened +/lp group frost_elemental setweight 30 +/lp group frost_elemental meta setprefix "&b[❄️ Frost Elemental] " + +# Permissions (same as Fire Elemental) +/lp group frost_elemental meta setmeta max-homes 5 +/lp group frost_elemental permission set ftbchunks.claim true +/lp group frost_elemental meta setmeta max-claimed-chunks 25 +/lp group frost_elemental permission set ftbessentials.rtp true +/lp group frost_elemental meta setmeta rtp-cooldown 3600 +``` + +#### Create Fire Knight Group ($10/mo) + +``` +/lp creategroup fire_knight +/lp group fire_knight parent add fire_elemental +/lp group fire_knight setweight 40 +/lp group fire_knight meta setprefix "&c[🔥 Fire Knight] " + +# Permissions +/lp group fire_knight meta setmeta max-homes 10 +/lp group fire_knight meta setmeta max-claimed-chunks 49 +/lp group fire_knight meta setmeta max-force-loaded-chunks 4 +/lp group fire_knight meta setmeta rtp-cooldown 1800 +``` + +#### Create Frost Knight Group ($10/mo) + +``` +/lp creategroup frost_knight +/lp group frost_knight parent add frost_elemental +/lp group frost_knight setweight 40 +/lp group frost_knight meta setprefix "&b[❄️ Frost Knight] " + +# Permissions (same as Fire Knight) +/lp group frost_knight meta setmeta max-homes 10 +/lp group frost_knight meta setmeta max-claimed-chunks 49 +/lp group frost_knight meta setmeta max-force-loaded-chunks 4 +/lp group frost_knight meta setmeta rtp-cooldown 1800 +``` + +#### Create Fire Master Group ($15/mo) + +``` +/lp creategroup fire_master +/lp group fire_master parent add fire_knight +/lp group fire_master setweight 50 +/lp group fire_master meta setprefix "&c[🔥 Fire Master] " + +# Permissions +/lp group fire_master meta setmeta max-homes 20 +/lp group fire_master meta setmeta max-claimed-chunks 100 +/lp group fire_master meta setmeta max-force-loaded-chunks 9 +/lp group fire_master meta setmeta rtp-cooldown 900 +``` + +#### Create Frost Master Group ($15/mo) + +``` +/lp creategroup frost_master +/lp group frost_master parent add frost_knight +/lp group frost_master setweight 50 +/lp group frost_master meta setprefix "&b[❄️ Frost Master] " + +# Permissions +/lp group frost_master meta setmeta max-homes 20 +/lp group frost_master meta setmeta max-claimed-chunks 100 +/lp group frost_master meta setmeta max-force-loaded-chunks 9 +/lp group frost_master meta setmeta rtp-cooldown 900 +``` + +#### Create Fire Legend Group ($20/mo) + +``` +/lp creategroup fire_legend +/lp group fire_legend parent add fire_master +/lp group fire_legend setweight 60 +/lp group fire_legend meta setprefix "&c[🔥 Fire Legend] " + +# Permissions +/lp group fire_legend meta setmeta max-homes 35 +/lp group fire_legend meta setmeta max-claimed-chunks 121 +/lp group fire_legend meta setmeta max-force-loaded-chunks 16 +/lp group fire_legend meta setmeta rtp-cooldown 600 +``` + +#### Create Frost Legend Group ($20/mo) + +``` +/lp creategroup frost_legend +/lp group frost_legend parent add frost_master +/lp group frost_legend setweight 60 +/lp group frost_legend meta setprefix "&b[❄️ Frost Legend] " + +# Permissions +/lp group frost_legend meta setmeta max-homes 35 +/lp group frost_legend meta setmeta max-claimed-chunks 121 +/lp group frost_legend meta setmeta max-force-loaded-chunks 16 +/lp group frost_legend meta setmeta rtp-cooldown 600 +``` + +#### Create Sovereign (Founder) Group ($499 Lifetime) + +``` +/lp creategroup sovereign +/lp group sovereign parent add awakened +/lp group sovereign setweight 100 +/lp group sovereign meta setprefix "&6[⚡ Founder] " + +# Permissions (maximum everything) +/lp group sovereign meta setmeta max-homes 50 +/lp group sovereign meta setmeta max-claimed-chunks 225 +/lp group sovereign meta setmeta max-force-loaded-chunks 81 +/lp group sovereign permission set ftbessentials.rtp true +# No rtp cooldown for Sovereign +``` + +### Step 2: Verify Groups Created + +``` +/lp listgroups +``` + +**You should see all 11 groups listed.** + +### Step 3: Sync to All Other Servers + +**Because all servers connect to the SAME MySQL database, the groups are already synced!** + +**To verify on another server:** + +1. Go to Pterodactyl Panel +2. Open console for a different server +3. Run `/lp listgroups` +4. Should show the same 11 groups + +**If groups don't appear:** +- Check that server's LuckPerms config points to the MySQL database +- Restart the server + +--- + +## 🔗 PART 4: LUCKPERMS DISCORD INTEGRATION + +**This connects Discord roles to LuckPerms groups.** + +### Step 1: Enable Discord Integration in LuckPerms + +**On EVERY server, edit `/config/luckperms/luckperms.conf`:** + +**Find the section:** +```conf +# Discord integration +discord-integration { + enabled = false +} +``` + +**Change to:** +```conf +discord-integration { + enabled = true + + # Role to group mappings + role-mappings { + # Format: "discord-role-id" = "luckperms-group" + + "123456789012345678" = "awakened" # The Awakened + "234567890123456789" = "fire_elemental" # Fire Elemental + "345678901234567890" = "frost_elemental" # Frost Elemental + "456789012345678901" = "fire_knight" # Fire Knight + "567890123456789012" = "frost_knight" # Frost Knight + "678901234567890123" = "fire_master" # Fire Master + "789012345678901234" = "frost_master" # Frost Master + "890123456789012345" = "fire_legend" # Fire Legend + "901234567890123456" = "frost_legend" # Frost Legend + "012345678901234567" = "sovereign" # Sovereign + } +} +``` + +**Replace role IDs with the ACTUAL role IDs you copied in Part 2.** + +**Save the file.** + +### Step 2: Restart All Servers + +**Via Pterodactyl Panel:** + +1. Open each server's console +2. Click **Restart** +3. Wait for server to come back online + +**Repeat for all 13 servers.** + +### Step 3: Test Discord → LuckPerms Sync + +**Manual test:** + +1. Go to Discord +2. Manually assign yourself `The Awakened` role (right-click your name → Roles) +3. Join a Minecraft server +4. Run `/lp user YourUsername info` +5. Should show you're in the `awakened` group + +**If it doesn't work:** +- Check LuckPerms config for typos in role IDs +- Check that Discord integration is enabled +- Restart the server + +--- + +## 🪝 PART 5: PAYMENTER WEBHOOK CONFIGURATION + +**This connects Paymenter to the Discord bot.** + +### Step 1: Set Up Nginx Proxy (Michael's Task) + +**On Command Center (where Discord bot runs):** + +**Create file: `/etc/nginx/sites-available/discord-bot-webhook`** + +```nginx +server { + listen 80; + server_name webhook.firefrostgaming.com; + + 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_cache_bypass $http_upgrade; + } +} +``` + +**Enable the site:** + +```bash +ln -s /etc/nginx/sites-available/discord-bot-webhook /etc/nginx/sites-enabled/ +nginx -t +systemctl reload nginx +``` + +**Get SSL certificate:** + +```bash +certbot --nginx -d webhook.firefrostgaming.com +``` + +**Now the webhook endpoint is:** +``` +https://webhook.firefrostgaming.com/webhook/paymenter +``` + +### Step 2: Configure Paymenter Webhooks (Michael + Holly) + +**In Paymenter admin panel:** + +1. Go to **Settings** → **Webhooks** +2. Click **Add Webhook** +3. Configure: + - **URL:** `https://webhook.firefrostgaming.com/webhook/paymenter` + - **Events:** + - ✅ `subscription.created` + - ✅ `payment.completed` + - ✅ `subscription.cancelled` + - ✅ `subscription.expired` + - **Payload Format:** JSON +4. Click **Save** + +### Step 3: Test Webhook + +**Create a test purchase in Paymenter (use test mode if available).** + +**Watch Discord bot logs:** + +```bash +journalctl -u firefrost-discord-bot -f +``` + +**You should see:** +``` +📬 Received webhook from Paymenter +📦 Event: subscription.created, Product: 2, User: 123456789012345678 +✅ Added role 123456789012345678 to TestUser#1234 +``` + +**If it works, the user should now have The Awakened role in Discord.** + +**If it doesn't work:** +- Check webhook URL is correct +- Check Paymenter is sending the correct payload format +- Check Discord bot logs for errors + +--- + +## ✅ TESTING & VERIFICATION + +### End-to-End Test + +**Complete flow test:** + +1. **Create test user in Discord** +2. **Purchase Awakened tier ($1) in Paymenter** +3. **Verify webhook fires** (check Discord bot logs) +4. **Verify Discord role assigned** (check Discord - user should have "The Awakened" role) +5. **Join Minecraft server** +6. **Run `/lp user TestUser info`** - Should show `awakened` group +7. **Test permissions:** + - `/sethome test` - Should work (1 home allowed) + - `/sethome test2` - Should FAIL (only 1 home for Awakened) + - Try claiming chunks - Should FAIL (Awakened has 0 chunk claims) + - Try `/rtp` - Should FAIL (Awakened has no /rtp access) + +**If all these work correctly, the automation is functioning!** + +### Upgrade Test + +**Test tier upgrade:** + +1. Upgrade test user to Fire Elemental ($5/mo) in Paymenter +2. Verify Discord role changes (old role removed, new role added) +3. Join Minecraft server +4. Run `/lp user TestUser info` - Should show `fire_elemental` group +5. Test new permissions: + - `/sethome` - Should work (5 homes allowed) + - Claim chunks - Should work (25 chunks allowed) + - `/rtp` - Should work (60 minute cooldown) + +### Cancellation Test + +**Test subscription cancellation:** + +1. Cancel test user's subscription in Paymenter +2. Verify Discord role removed +3. Join Minecraft server +4. Run `/lp user TestUser info` - Should show `wanderer` or default group +5. Test permissions: + - `/sethome` - Should FAIL (no subscription) + - Try joining server - Should be DENIED (whitelist = Awakened+ only) + +--- + +## 🔧 TROUBLESHOOTING + +### Discord Role Not Assigned After Purchase + +**Symptoms:** User purchases subscription but doesn't get Discord role. + +**Check:** +1. **Webhook logs:** `journalctl -u firefrost-discord-bot -f` + - Are webhooks being received? +2. **Paymenter webhook config:** Is webhook URL correct? +3. **Discord bot permissions:** Does bot have "Manage Roles" permission? +4. **Role position:** Bot's role must be ABOVE subscriber roles in Discord role hierarchy + +**Solution:** +- Move bot's role to the top of the role list in Discord Server Settings +- Restart Discord bot: `systemctl restart firefrost-discord-bot` + +--- + +### LuckPerms Not Syncing Discord Roles + +**Symptoms:** User has Discord role but no in-game permissions. + +**Check:** +1. **LuckPerms config:** Is Discord integration enabled? +2. **Role IDs:** Are Discord role IDs correct in luckperms.conf? +3. **Server restart:** Did you restart server after config change? + +**Solution:** +- Double-check role IDs match (right-click role in Discord → Copy ID) +- Ensure luckperms.conf has correct mapping +- Restart all game servers + +--- + +### User Can't Join Server After Subscribing + +**Symptoms:** User purchased subscription, has Discord role, but can't join server. + +**Check:** +1. **Whitelist status:** Is whitelist enabled on server? +2. **LuckPerms sync:** Run `/whitelist add Username` manually as test +3. **Server online:** Is server actually running? + +**Solution:** +- Ensure LuckPerms-based whitelist is configured (see Server-Side Mod Deployment Guide) +- Check server console for "User not whitelisted" messages +- Manually add to whitelist temporarily while debugging + +--- + +### Webhook Endpoint Returns 500 Error + +**Symptoms:** Paymenter shows webhook failed with 500 error. + +**Check:** +1. **Bot running:** `systemctl status firefrost-discord-bot` +2. **Bot logs:** `journalctl -u firefrost-discord-bot -f` for errors +3. **Nginx proxy:** Is Nginx running and proxying correctly? + +**Solution:** +- Restart Discord bot +- Check bot code for syntax errors +- Test webhook manually with curl: + ```bash + curl -X POST https://webhook.firefrostgaming.com/webhook/paymenter \ + -H "Content-Type: application/json" \ + -d '{"event":"subscription.created","product_id":"2","discord_id":"YOUR_DISCORD_ID"}' + ``` + +--- + +## 📚 REFERENCE + +### Quick Command Reference + +#### Discord Bot Management + +```bash +# Start bot +systemctl start firefrost-discord-bot + +# Stop bot +systemctl stop firefrost-discord-bot + +# Restart bot +systemctl restart firefrost-discord-bot + +# View logs +journalctl -u firefrost-discord-bot -f + +# Check status +systemctl status firefrost-discord-bot +``` + +#### LuckPerms Commands + +```bash +# View user's groups +/lp user info + +# Manually add user to group +/lp user parent add + +# Remove user from group +/lp user parent remove + +# View group permissions +/lp group permission info + +# List all groups +/lp listgroups +``` + +--- + +### Subscriber Tier → Discord Role → LuckPerms Group Mapping + +| Tier | Price | Discord Role | LuckPerms Group | +|------|-------|--------------|-----------------| +| Wanderer | Free | `Wanderer` | `wanderer` | +| Awakened | $1 | `The Awakened` | `awakened` | +| Fire Elemental | $5/mo | `🔥 Fire Elemental` | `fire_elemental` | +| Frost Elemental | $5/mo | `❄️ Frost Elemental` | `frost_elemental` | +| Fire Knight | $10/mo | `🔥 Fire Knight` | `fire_knight` | +| Frost Knight | $10/mo | `❄️ Frost Knight` | `frost_knight` | +| Fire Master | $15/mo | `🔥 Fire Master` | `fire_master` | +| Frost Master | $15/mo | `❄️ Frost Master` | `frost_master` | +| Fire Legend | $20/mo | `🔥 Fire Legend` | `fire_legend` | +| Frost Legend | $20/mo | `❄️ Frost Legend` | `frost_legend` | +| Sovereign | $499 | `⚡ Sovereign` | `sovereign` | + +--- + +### File Locations Quick Reference + +``` +Command Center (63.143.34.217) +└── /opt/firefrost-discord-bot/ + ├── bot.js + ├── package.json + └── node_modules/ + +Game Servers (TX1/NC1) +└── /config/luckperms/ + └── luckperms.conf (Discord integration config) + +Nginx +└── /etc/nginx/sites-available/ + └── discord-bot-webhook +``` + +--- + +**End of Subscription Automation Guide** + +**You've now completed the full automation setup! Users can subscribe in Paymenter and automatically get:** +- Discord role assignment +- In-game rank sync +- Correct permissions on all 13 servers +- Channel access based on Fire/Frost path + +**Fire + Frost + Foundation = Where Love Builds Legacy** 🔥❄️ + +--- + +**Document Version:** 1.0 +**Last Updated:** March 23, 2026 +**Maintained By:** Firefrost Gaming Infrastructure Team