firefrost-operations-manual/docs/pterodactyl-extensions-plan.md

# Pterodactyl Extensions Deployment Plan

**Created:** February 9, 2026  
**Purpose:** Automation and quality-of-life improvements for 15+ server management  
**Priority:** Deploy after Phase 0.5 completion (Services 1-5)  
**Status:** Planning phase

---

## Overview

Pterodactyl Panel extensions to reduce manual workload, improve community experience, and enable Fire vs Frost competitive tracking. All extensions focused on accessibility (reducing repetitive tasks for hands-limited operation).

---

## Extension 1: Pterodactyl-Discord Integration

**Priority:** HIGH (deploy first)  
**Impact:** Massive time savings for Meg (The Emissary)  
**Complexity:** Medium

### Features
- Auto-post server status updates to Discord channels
- Player-initiated commands (start/stop/restart) from Discord
- Real-time player counts in channel names/topics
- Automated restart/maintenance notifications
- Per-server webhook configuration

### Benefits
- Reduces "is the server down?" DMs to staff
- Community self-service (players restart servers themselves within limits)
- Perfect integration with 15 server-specific Discord channels
- Real-time status visibility for all players

### Technical Requirements
- Discord bot application created
- Webhook URLs per server (15 webhooks total)
- Permission management (who can restart, who can just view)
- Rate limiting to prevent abuse

### Installation Steps
1. Create Discord bot application
2. Install Pterodactyl-Discord plugin
3. Configure webhooks per server
4. Set permission levels per Discord role
5. Test with one server before rollout
6. Deploy to all 15 servers

### Configuration Notes
- Fire Path servers get Fire-themed bot messages
- Frost Path servers get Frost-themed bot messages
- Founder-only commands available in Nexus channels

---

## Extension 2: Automated Backups System

**Priority:** HIGH (deploy first)  
**Impact:** Critical data protection + peace of mind  
**Complexity:** Medium

### Features
- Scheduled backups per server (daily, weekly, custom)
- Retention policies (7 days, 30 days, forever)
- One-click restore from panel
- Off-site backup storage (S3, FTP, or local NAS)
- Backup compression and encryption
- Backup status monitoring

### Benefits
- Automated protection against data loss
- No manual backup management (saves hands)
- Quick disaster recovery
- Player trust (data is safe)
- Compliance ready (can prove backups exist)

### Technical Requirements
- Backup storage location (recommend S3 or Backblaze B2)
- Storage capacity planning (15 servers × backup size × retention)
- Backup schedule staggering (don't backup all 15 at once)
- Monitoring integration (alert if backup fails)

### Installation Steps
1. Set up backup storage (S3 bucket or equivalent)
2. Install Pterodactyl Backups addon
3. Configure storage credentials
4. Set backup schedules per server
5. Test restore procedure
6. Document restore process for team
7. Configure backup failure alerts

### Backup Schedule Recommendation
- **Critical servers** (high player count): Daily backups, 30-day retention
- **Standard servers**: Daily backups, 7-day retention
- **Test/development servers**: Weekly backups, 7-day retention
- **Off-site replication**: Weekly full backups to separate provider

---

## Extension 3: Paymenter-Pterodactyl Integration

**Priority:** MEDIUM (deploy before subscription launch)  
**Impact:** Zero-touch subscription management  
**Complexity:** High

### Features
- Auto-provision server access on subscription purchase
- Auto-suspend servers on payment failure (with grace period)
- Auto-adjust resource limits on tier upgrade/downgrade
- Auto-archive servers on subscription cancellation
- Subscription status sync (active, suspended, cancelled)

### Benefits
- No manual server provisioning (saves massive time)
- Fire vs Frost tier enforcement automated
- Payment failures handled automatically
- Can sleep while subscriptions process
- Reduces billing disputes (automated = consistent)

### Technical Requirements
- Paymenter API access configured
- Pterodactyl API access configured
- Webhook endpoint for payment events
- Grace period configuration (7 days before suspension?)
- Tier-to-resource mapping defined

### Tier Resource Mapping
**The Awakened ($1):**
- Access to all servers (no special resources)

**Fire/Frost Elemental ($5):**
- 1 home location set per server
- Priority queue position
- Path-specific channels unlocked

**Fire/Frost Knight ($10):**
- 2 home locations per server
- Higher priority queue
- /fly on non-PvP servers

**Fire/Frost Master ($15):**
- 3 home locations
- Highest priority queue
- Custom nickname colors
- Access to creative plots

**Fire/Frost Legend ($20):**
- 5 home locations
- Instant queue entry
- Custom particle effects
- Early access to new servers

**Founder ($499 lifetime):**
- Unlimited homes
- Both Fire and Frost access
- All perks from both paths
- Beta server access

### Installation Steps
1. Document tier-to-permission mappings (work with LuckPerms)
2. Install Paymenter-Pterodactyl bridge plugin
3. Configure API credentials both directions
4. Set up webhook listeners
5. Configure grace periods and suspension rules
6. Test with dummy subscription (full lifecycle)
7. Monitor first 10 real subscriptions manually
8. Enable full automation after validation

---

## Extension 4: Pterodactyl Analytics Dashboard

**Priority:** MEDIUM (deploy after subscriptions active)  
**Impact:** Data-driven decisions, Fire vs Frost metrics  
**Complexity:** Medium

### Features
- CPU/RAM/Disk usage graphs per server
- Player count trends over time
- Peak hours identification
- Most popular servers ranking
- Resource allocation recommendations
- Fire vs Frost path popularity comparison

### Benefits
- See which servers need resource upgrades
- Fire vs Frost competition tracking (who's winning?)
- Identify underutilized servers (candidates for shutdown)
- Capacity planning for growth
- Performance optimization opportunities

### Technical Requirements
- Time-series database (InfluxDB or similar)
- Data collection agents on each node
- Dashboard framework (Grafana or custom)
- Historical data retention policy

### Metrics to Track
**Per Server:**
- CPU usage (average, peak)
- RAM usage (average, peak)
- Disk usage and growth rate
- Player count (current, average, peak)
- Uptime percentage
- Restart frequency

**Fire vs Frost Comparison:**
- Total players per path
- Average session duration per path
- Server popularity rankings per path
- Subscription tier distribution per path
- Revenue attribution per path (for the competition!)

### Dashboard Views
1. **Executive Dashboard** - High-level overview, Fire vs Frost scores
2. **Operations Dashboard** - Server health, alerts, resource usage
3. **Community Dashboard** - Player counts, popular servers, trends
4. **Financial Dashboard** - Subscription metrics, revenue per path

### Installation Steps
1. Install time-series database (InfluxDB)
2. Deploy data collection agents to TX1 and NC1
3. Install analytics dashboard plugin
4. Configure dashboards and widgets
5. Set up automated reports (weekly email to Michael/Meg)
6. Create public status page (transparency for community)

---

## Extension 5: Multi-Server Management (Bulk Actions)

**Priority:** HIGH (deploy early)  
**Impact:** Massive time savings for hands-limited operation  
**Complexity:** Low to Medium

### Features
- Restart ALL servers in one click
- Update ALL mods across servers simultaneously
- Broadcast message to ALL servers at once
- Batch configuration changes (MOTD, rules, etc.)
- Selective bulk actions (all Fire servers, all Frost servers, etc.)

### Benefits
- 15 servers = 1 action instead of 15
- Critical for emergency maintenance
- Mod updates across network in minutes
- Consistent configuration across servers
- Saves hands from repetitive clicking

### Use Cases
**Emergency Maintenance:**
- Network-wide restart for host maintenance
- Emergency security patch deployment
- Broadcast warning before scheduled downtime

**Regular Operations:**
- Mod updates for modpacks (ATM10 updates all instances)
- Server configuration changes
- MOTD updates for events
- Rule changes across network

**Fire vs Frost Events:**
- Broadcast event announcements to Fire path only
- Broadcast event announcements to Frost path only
- Special events affecting all servers

### Technical Requirements
- Pterodactyl API access
- Server grouping/tagging capability
- Action queuing (don't overwhelm nodes)
- Rollback capability if bulk action fails

### Installation Steps
1. Install bulk actions plugin or create API scripts
2. Configure server groups (Fire, Frost, All, Test)
3. Set up action templates (common tasks)
4. Create safety confirmations (prevent accidents)
5. Test with non-critical actions first
6. Document common bulk action workflows
7. Train Meg on bulk operations

### Server Groups
- **All Servers** - Every game server (15 total)
- **Fire Path** - Servers themed for Fire path players
- **Frost Path** - Servers themed for Frost path players
- **High Priority** - Most popular servers (careful restarts)
- **Test Servers** - Safe to break, test updates here first
- **TX1 Servers** - All servers on Dallas node
- **NC1 Servers** - All servers on Charlotte node

---

## Deployment Timeline

### Phase 0.6: Extension Preparation (After Phase 0.5 complete)
- Research and documentation for all 5 extensions
- Create installation guides
- Test in isolated environment

### Phase 0.7: Core Extensions Deployment
**Week 1:**
1. Extension 5: Bulk Actions (fastest, highest immediate impact)
2. Extension 2: Automated Backups (critical protection)

**Week 2:**
3. Extension 1: Discord Integration (Meg will love this)

### Phase 0.8: Advanced Extensions
**Week 3:**
4. Extension 4: Analytics Dashboard (data-driven decisions)

**Week 4:**
5. Extension 3: Paymenter Integration (before subscription launch)

---

## Success Metrics

### Extension 1: Discord Integration
- ✅ 80% reduction in "is server down?" DMs
- ✅ Player-initiated restarts functioning
- ✅ Real-time player counts visible in channels

### Extension 2: Automated Backups
- ✅ 100% daily backup success rate
- ✅ Successful restore test completed
- ✅ Off-site replication confirmed

### Extension 3: Paymenter Integration
- ✅ Zero manual server provisioning required
- ✅ Suspension automation working (tested with expired test subscription)
- ✅ Tier upgrades processing automatically

### Extension 4: Analytics Dashboard
- ✅ Fire vs Frost popularity tracked weekly
- ✅ Resource optimization recommendations generated
- ✅ Public status page live

### Extension 5: Bulk Actions
- ✅ Network-wide restarts complete in <5 minutes
- ✅ Mod updates deployed to all servers in one action
- ✅ No failed bulk operations after initial testing

---

## Cost Analysis

### Extension 1: Discord Integration
**Cost:** Free (community plugin)  
**Time Investment:** 8-10 hours setup + configuration

### Extension 2: Automated Backups
**Cost:** $5-20/month (S3 storage for 15 servers)  
**Time Investment:** 6-8 hours setup + testing

### Extension 3: Paymenter Integration
**Cost:** Free (API-based)  
**Time Investment:** 12-16 hours (complex mapping and testing)

### Extension 4: Analytics Dashboard
**Cost:** Free (self-hosted Grafana) or $10-30/month (hosted)  
**Time Investment:** 10-12 hours dashboard creation

### Extension 5: Bulk Actions
**Cost:** Free (API scripts or community plugin)  
**Time Investment:** 4-6 hours setup + documentation

**Total Estimated Cost:** $15-50/month (mostly backup storage)  
**Total Time Investment:** 40-52 hours (spread over 4 weeks)  
**ROI:** Saves 10+ hours/week ongoing (pays back in ~1 month)

---

## Risk Mitigation

### Risk: Bulk action accidentally affects production
**Mitigation:** 
- Require confirmation for bulk actions
- Test on test servers first
- Implement rollback capability
- Limit bulk action permissions to Michael/Meg only

### Risk: Backup failures go unnoticed
**Mitigation:**
- Daily backup status emails
- Integration with Uptime Kuma
- Weekly manual spot-check of random backup
- Quarterly full restore drill

### Risk: Paymenter integration bugs cause service disruption
**Mitigation:**
- Extended testing period with dummy subscriptions
- Grace period before suspensions (7 days minimum)
- Manual override capability
- Detailed logging of all automated actions

### Risk: Discord integration spammed by players
**Mitigation:**
- Rate limiting on bot commands
- Permission-based command access
- Cooldowns between restart requests
- Moderation logging

### Risk: Analytics dashboard exposes sensitive data
**Mitigation:**
- Public dashboard shows only aggregated data
- Detailed metrics admin-only
- No player names or personal info in public view
- Revenue metrics completely private

---

## Documentation Requirements

Each extension requires:
1. **Installation Guide** - Step-by-step with screenshots
2. **Configuration Reference** - All settings explained
3. **User Guide** - For Meg and future staff
4. **Troubleshooting Guide** - Common issues and solutions
5. **Maintenance Schedule** - When to review/update

All documentation stored in BookStack after deployment.

---

## Revision History

| Version | Date | Author | Changes |
|---------|------|--------|---------|
| **1.0** | 2026-02-09 | Michael | Initial extension plan created. All 5 extensions scoped and prioritized. |

---

**END OF DOCUMENT**