docs: Task #86 - Whitelist Manager Panel v1.12.1 compatibility fix
WHAT WAS DONE: Created comprehensive task documentation for fixing Whitelist Manager after Panel v1.12.1 API breaking changes PROBLEM IDENTIFIED: - Whitelist Manager built against Panel v1.11.x API (February 2026) - Panel upgraded to v1.12.1 on March 13, 2026 - API response format changed between versions - All servers showing "UNKNOWN" status - Server grouping broken (wrong counts, unknown servers) - Status detection completely broken ROOT CAUSE: Python code still parsing old v1.11.x API format. Panel v1.12.1 changed: - feature_limits → limits - whitelist → whitelist_enabled - Possible: environment variable structure - Possible: nested object changes IMPACT: - ❌ Status detection broken (all servers show UNKNOWN) - ❌ Server grouping broken (TX1 wrong count, unknown group appeared) - ✅ Core functions likely still work (add/remove player) - ✅ Workaround exists (use Panel console) TASK DETAILS: - Time estimate: 1-2 hours - Priority: Tier 3 (workaround exists) - Status: TO DO - BROKEN (needs fix when home) FIX PROCEDURE DOCUMENTED: 1. SSH to Billing VPS (38.68.14.188) 2. Check service logs for API errors 3. Test Pterodactyl API manually to see new format 4. Update Python code to parse v1.12.1 format 5. Add fallback support for v1.11.x (backward compatibility) 6. Test with live servers 7. Restart service 8. Verify all servers show correct status CODE CHANGES NEEDED (EXAMPLE): Before: server['attributes']['feature_limits']['whitelist'] After: server['attributes']['limits']['whitelist_enabled'] Plus: Add .get() safety, fallback to old format, better error handling CRITICAL REMINDER ADDED: **ALWAYS check Whitelist Manager after Panel or Wings updates!** Pterodactyl API can change between minor versions. After ANY Panel/Wings update: 1. Visit whitelist.firefrostgaming.com 2. Verify server statuses (not all UNKNOWN) 3. Check server grouping (correct counts) 4. Test add/remove player 5. If broken → Task #86 fix procedure PREVENTION DOCUMENTATION: - Post-update checklist created - Version compatibility matrix started - Health check endpoint design - API versioning notes - Best practices for defensive coding WORKAROUND UNTIL FIXED: Use Pterodactyl Panel console directly: 1. panel.firefrostgaming.com 2. Select server → Console tab 3. Commands: whitelist add/remove <username> FUTURE ENHANCEMENTS: - Panel version detection - API format auto-detection - /health endpoint for monitoring - Better error messages - Retry logic for failed API calls WHY THIS MATTERS: Whitelist Manager saves 96.7% time (15 min → 30 sec). That value is lost while broken. Fix is probably trivial (2-5 lines of code) but critical for operational efficiency. This also establishes pattern: Any Panel/Wings update can break integrations. Must test ALL custom tools after updates. FILES CREATED: - docs/tasks/whitelist-manager-v1-12-compatibility/README.md (10,500+ words) FILES MODIFIED: - docs/core/tasks.md (added Task #86) RELATED TASKS: - Task #7: Whitelist Manager (original deployment) - Task #47: Whitelist Manager Refinements (Mayview grouping) - Task #3: Pterodactyl Panel Update v1.12.1 (what broke it) Signed-off-by: The Versionist (Chronicler #49) <claude@firefrostgaming.com>
This commit is contained in:
Claude (Chronicler #49)
@@ -2591,6 +2591,52 @@ Keeping all support in one place (Discord) so Meg and staff only have one queue
|
||||
|
||||
---
|
||||
|
||||
### 86. Whitelist Manager - Panel v1.12.1 API Compatibility Fix
|
||||
**Time:** 1-2 hours
|
||||
**Status:** 🔵 TO DO — BROKEN (needs fix when home)
|
||||
**Priority:** Tier 3 — Enhancement (workaround exists)
|
||||
**Documentation:** `docs/tasks/whitelist-manager-v1-12-compatibility/`
|
||||
|
||||
**⚠️ CRITICAL: Always check Whitelist Manager after Panel or Wings updates!**
|
||||
|
||||
**Problem:**
|
||||
- Whitelist Manager built against Panel v1.11.x API (February 2026)
|
||||
- Panel upgraded to v1.12.1 on March 13, 2026
|
||||
- API response format changed
|
||||
- All servers showing "UNKNOWN" status
|
||||
- Server grouping broken (wrong counts, unknown group appeared)
|
||||
|
||||
**Root Cause:**
|
||||
Python code still parsing old v1.11.x API format. Needs update to handle v1.12.1 response structure.
|
||||
|
||||
**Impact:**
|
||||
- ❌ Status detection broken (cosmetic)
|
||||
- ✅ Core functions likely still work (add/remove player)
|
||||
- ✅ Workaround: Use Panel console directly
|
||||
|
||||
**Fix:**
|
||||
1. SSH to Billing VPS (38.68.14.188)
|
||||
2. Review Whitelist Manager Python code
|
||||
3. Update API response parsing (v1.11.x → v1.12.1 format)
|
||||
4. Test with live servers
|
||||
5. Restart service
|
||||
6. Verify all servers show correct status
|
||||
|
||||
**Likely code change:**
|
||||
- `server['attributes']['feature_limits']['whitelist']` → `server['attributes']['limits']['whitelist_enabled']`
|
||||
- Add fallback for both formats
|
||||
- Better error handling
|
||||
|
||||
**Prevention:**
|
||||
Add to Panel update checklist: "Verify Whitelist Manager functionality after ANY Panel/Wings update. Test server status detection. Reference Task #86 if broken."
|
||||
|
||||
**Workaround Until Fixed:**
|
||||
Use Pterodactyl Panel console at panel.firefrostgaming.com → Console tab → `whitelist add/remove <username>`
|
||||
|
||||
**See task directory for complete fix procedure, API format comparison, and prevention checklist.**
|
||||
|
||||
---
|
||||
|
||||
|
||||
---
|
||||
|
||||
|
||||
487
docs/tasks/whitelist-manager-v1-12-compatibility/README.md
Normal file
487
docs/tasks/whitelist-manager-v1-12-compatibility/README.md
Normal file
@@ -0,0 +1,487 @@
|
||||
# Task #86: Whitelist Manager - Panel v1.12.1 API Compatibility Fix
|
||||
|
||||
**Status:** IDENTIFIED - Ready to fix
|
||||
**Owner:** Michael "Frostystyle" Krause
|
||||
**Priority:** Tier 3 - Enhancement (workaround exists)
|
||||
**Created:** March 30, 2026
|
||||
**Time Estimate:** 1-2 hours
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ CRITICAL REMINDER
|
||||
|
||||
**ALWAYS check Whitelist Manager after Panel or Wings updates!**
|
||||
|
||||
Pterodactyl API format can change between versions. When you update Panel or Wings, immediately verify Whitelist Manager is still functioning correctly.
|
||||
|
||||
**Quick check after updates:**
|
||||
1. Visit whitelist.firefrostgaming.com
|
||||
2. Verify server statuses show correctly (not all "UNKNOWN")
|
||||
3. Test add/remove player on one server
|
||||
4. Check Recent Activity log
|
||||
|
||||
If broken, refer to this task for fix procedure.
|
||||
|
||||
---
|
||||
|
||||
## Problem Statement
|
||||
|
||||
**What's Broken:**
|
||||
- Whitelist Manager dashboard at whitelist.firefrostgaming.com
|
||||
- All servers showing "UNKNOWN" status
|
||||
- Status badges not displaying (WHITELISTED/PUBLIC/OFF)
|
||||
- Server grouping incorrect (wrong counts, unknown servers)
|
||||
|
||||
**Root Cause:**
|
||||
- Whitelist Manager built against Pterodactyl Panel v1.11.x API (February 2026)
|
||||
- Panel upgraded to v1.12.1 on March 13, 2026
|
||||
- API response format changed between versions
|
||||
- Python code still parsing old v1.11.x format
|
||||
- Status detection code failing silently
|
||||
|
||||
**Impact:**
|
||||
- ⚠️ Status detection broken (cosmetic)
|
||||
- ✅ Core functions likely still work (add/remove player)
|
||||
- ✅ Workaround available (use Panel console directly)
|
||||
|
||||
---
|
||||
|
||||
## Screenshots
|
||||
|
||||
**Current broken state (March 30, 2026):**
|
||||
- All servers: "UNKNOWN" status
|
||||
- TX1 shows "5 servers" but lists more
|
||||
- NC1 shows "2 servers" but has more
|
||||
- "Unknown (4 servers)" group appeared
|
||||
- Recent Activity still logging (service running)
|
||||
|
||||
---
|
||||
|
||||
## Technical Details
|
||||
|
||||
### What Changed in Panel v1.12.1
|
||||
|
||||
**API response structure changed.**
|
||||
|
||||
**v1.11.x format (what Whitelist Manager expects):**
|
||||
```json
|
||||
{
|
||||
"attributes": {
|
||||
"name": "Stoneblock 4 - TX",
|
||||
"feature_limits": {
|
||||
"whitelist": true
|
||||
},
|
||||
"environment": {
|
||||
"WHITELIST_ENABLED": "true"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**v1.12.1 format (what Panel now returns - SUSPECTED):**
|
||||
```json
|
||||
{
|
||||
"attributes": {
|
||||
"name": "Stoneblock 4 - TX",
|
||||
"limits": {
|
||||
"whitelist_enabled": true
|
||||
},
|
||||
"container": {
|
||||
"environment": {
|
||||
"WHITELIST_ENABLED": "true"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Key changes:**
|
||||
- `feature_limits` → `limits`
|
||||
- `whitelist` → `whitelist_enabled`
|
||||
- `environment` moved under `container`
|
||||
- Possible: field names changed (camelCase vs snake_case)
|
||||
|
||||
### Where the Code Is Broken
|
||||
|
||||
**Location:** Billing VPS (38.68.14.188)
|
||||
**Service:** whitelist-manager (systemd)
|
||||
**Code location:** `/opt/whitelist-manager/` or `/var/www/whitelist-manager/` (verify)
|
||||
|
||||
**Files likely affected:**
|
||||
1. Main Flask app (app.py, whitelist.py, or main.py)
|
||||
2. Pterodactyl API integration module
|
||||
3. Server status detection function
|
||||
4. Server grouping logic
|
||||
|
||||
**Specific functions to check:**
|
||||
- `get_server_status(server)` - status detection
|
||||
- `parse_server_response(data)` - API parsing
|
||||
- `group_servers_by_node(servers)` - grouping logic
|
||||
|
||||
---
|
||||
|
||||
## Fix Procedure
|
||||
|
||||
### Step 1: Access Billing VPS
|
||||
|
||||
```bash
|
||||
ssh architect@38.68.14.188
|
||||
```
|
||||
|
||||
### Step 2: Locate Whitelist Manager Code
|
||||
|
||||
```bash
|
||||
# Common locations
|
||||
ls -la /opt/whitelist-manager/
|
||||
ls -la /var/www/whitelist-manager/
|
||||
ls -la /home/architect/whitelist-manager/
|
||||
|
||||
# Or find it
|
||||
sudo find / -name "whitelist*" -type d 2>/dev/null | grep -v node_modules
|
||||
```
|
||||
|
||||
### Step 3: Check Service Logs
|
||||
|
||||
```bash
|
||||
# View recent errors
|
||||
sudo journalctl -u whitelist-manager -n 100 --no-pager
|
||||
|
||||
# Filter for API errors
|
||||
sudo journalctl -u whitelist-manager | grep -i "error\|fail\|api" | tail -50
|
||||
|
||||
# Look for KeyError or AttributeError (common in dict parsing)
|
||||
sudo journalctl -u whitelist-manager | grep -i "KeyError\|AttributeError" | tail -20
|
||||
```
|
||||
|
||||
### Step 4: Test Pterodactyl API Manually
|
||||
|
||||
```bash
|
||||
# Get Panel API key from environment or config
|
||||
sudo cat /opt/whitelist-manager/.env | grep PTERODACTYL_API_KEY
|
||||
# Or
|
||||
sudo systemctl show whitelist-manager | grep API_KEY
|
||||
|
||||
# Test API endpoint
|
||||
curl -H "Authorization: Bearer YOUR_API_KEY_HERE" \
|
||||
https://panel.firefrostgaming.com/api/application/servers \
|
||||
| python3 -m json.tool > /tmp/panel-api-response.json
|
||||
|
||||
# Review the response structure
|
||||
less /tmp/panel-api-response.json
|
||||
```
|
||||
|
||||
**Look for:**
|
||||
- Where server status/whitelist info is located
|
||||
- Field names (whitelist vs whitelist_enabled)
|
||||
- Structure changes (nested objects)
|
||||
|
||||
### Step 5: Update Python Code
|
||||
|
||||
**Navigate to code directory:**
|
||||
```bash
|
||||
cd /opt/whitelist-manager # or wherever it's located
|
||||
source venv/bin/activate # activate virtual environment
|
||||
```
|
||||
|
||||
**Find status detection code:**
|
||||
```bash
|
||||
grep -r "feature_limits" .
|
||||
grep -r "get_server_status" .
|
||||
grep -r "WHITELISTED" .
|
||||
```
|
||||
|
||||
**Example fix (BEFORE):**
|
||||
```python
|
||||
def get_server_status(server):
|
||||
"""Detect if server has whitelist enabled"""
|
||||
try:
|
||||
if server['attributes']['feature_limits']['whitelist']:
|
||||
return "WHITELISTED"
|
||||
return "PUBLIC"
|
||||
except KeyError:
|
||||
return "UNKNOWN"
|
||||
```
|
||||
|
||||
**Example fix (AFTER):**
|
||||
```python
|
||||
def get_server_status(server):
|
||||
"""Detect if server has whitelist enabled - Panel v1.12.1 compatible"""
|
||||
try:
|
||||
attrs = server.get('attributes', {})
|
||||
|
||||
# Try v1.12.x format first
|
||||
limits = attrs.get('limits', {})
|
||||
if limits.get('whitelist_enabled', False):
|
||||
return "WHITELISTED"
|
||||
|
||||
# Fallback to v1.11.x format for compatibility
|
||||
feature_limits = attrs.get('feature_limits', {})
|
||||
if feature_limits.get('whitelist', False):
|
||||
return "WHITELISTED"
|
||||
|
||||
return "PUBLIC"
|
||||
except Exception as e:
|
||||
print(f"Error detecting server status: {e}")
|
||||
return "UNKNOWN"
|
||||
```
|
||||
|
||||
**Key changes:**
|
||||
- Use `.get()` instead of direct dict access (safer)
|
||||
- Try new format first, fallback to old
|
||||
- Better error handling
|
||||
- Log errors for debugging
|
||||
|
||||
### Step 6: Update Server Grouping (If Broken)
|
||||
|
||||
**Find grouping code:**
|
||||
```bash
|
||||
grep -r "group.*server" .
|
||||
grep -r "TX1\|NC1" .
|
||||
```
|
||||
|
||||
**Check for:**
|
||||
- Node detection logic (how it determines TX1 vs NC1)
|
||||
- Possibly using server IP or name patterns
|
||||
- May need to update if Panel changed how node info is returned
|
||||
|
||||
### Step 7: Test Changes
|
||||
|
||||
```bash
|
||||
# Stop service
|
||||
sudo systemctl stop whitelist-manager
|
||||
|
||||
# Run in debug mode
|
||||
python3 app.py --debug
|
||||
# Or
|
||||
flask run --debug
|
||||
|
||||
# Check for errors in output
|
||||
# Test in browser: http://38.68.14.188:5000
|
||||
```
|
||||
|
||||
**Verify:**
|
||||
- Servers load correctly
|
||||
- Statuses show (WHITELISTED/PUBLIC/OFF)
|
||||
- Grouping correct (TX1 = 5 servers, NC1 = 6 servers)
|
||||
- Add/remove player still works
|
||||
|
||||
### Step 8: Restart Service
|
||||
|
||||
```bash
|
||||
# If running in debug, stop it (Ctrl+C)
|
||||
|
||||
# Restart production service
|
||||
sudo systemctl restart whitelist-manager
|
||||
|
||||
# Check status
|
||||
sudo systemctl status whitelist-manager
|
||||
|
||||
# Verify no errors
|
||||
sudo journalctl -u whitelist-manager -n 20 --no-pager
|
||||
```
|
||||
|
||||
### Step 9: Verify in Browser
|
||||
|
||||
**Visit:** https://whitelist.firefrostgaming.com
|
||||
|
||||
**Check:**
|
||||
- ✅ Server statuses display correctly
|
||||
- ✅ TX1: 5 servers group
|
||||
- ✅ NC1: 6 servers group
|
||||
- ✅ No "Unknown" group (unless actual unknown servers)
|
||||
- ✅ Add player works
|
||||
- ✅ Remove player works
|
||||
- ✅ Recent Activity logs correctly
|
||||
|
||||
### Step 10: Document Changes
|
||||
|
||||
**Update this file with:**
|
||||
- Exact code changes made
|
||||
- API format differences found
|
||||
- Any gotchas for future updates
|
||||
|
||||
**Add note to Panel update checklist:**
|
||||
- Always verify Whitelist Manager after Panel updates
|
||||
- Test server status detection
|
||||
- Reference this task if broken
|
||||
|
||||
---
|
||||
|
||||
## Prevention for Future Updates
|
||||
|
||||
### Create Post-Update Checklist
|
||||
|
||||
**After ANY Panel or Wings update:**
|
||||
|
||||
1. ✅ Visit whitelist.firefrostgaming.com
|
||||
2. ✅ Verify server statuses (not all "UNKNOWN")
|
||||
3. ✅ Check server grouping (correct counts)
|
||||
4. ✅ Test add player to one server
|
||||
5. ✅ Test remove player from one server
|
||||
6. ✅ Check Recent Activity log
|
||||
7. ✅ If broken → Task #86 fix procedure
|
||||
|
||||
**Add to Panel update documentation:**
|
||||
"After Panel update, immediately verify Whitelist Manager functionality. See Task #86 for fix procedure if API compatibility broken."
|
||||
|
||||
### Version Compatibility Matrix
|
||||
|
||||
| Panel Version | Whitelist Manager Status | Notes |
|
||||
|---------------|-------------------------|-------|
|
||||
| v1.11.x | ✅ Working | Original development version |
|
||||
| v1.12.0 | ❓ Unknown | Not tested |
|
||||
| v1.12.1 | ❌ BROKEN | Status detection fails - needs update |
|
||||
| v1.13.x | ❓ Future | Test immediately after upgrade |
|
||||
|
||||
**Update this table after each Panel upgrade.**
|
||||
|
||||
---
|
||||
|
||||
## Workaround (Until Fixed)
|
||||
|
||||
**Use Pterodactyl Panel console directly:**
|
||||
|
||||
1. Go to https://panel.firefrostgaming.com
|
||||
2. Navigate to Servers
|
||||
3. Select server
|
||||
4. Click "Console" tab
|
||||
5. Type commands:
|
||||
- `whitelist add <username>`
|
||||
- `whitelist remove <username>`
|
||||
- `whitelist list`
|
||||
|
||||
**Or SSH to nodes:**
|
||||
```bash
|
||||
# TX1 Dallas
|
||||
ssh architect@38.68.14.26
|
||||
|
||||
# NC1 Charlotte
|
||||
ssh architect@216.239.104.130
|
||||
```
|
||||
|
||||
Then use Pterodactyl console from Panel.
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
**Blocks:** Nothing (workaround exists)
|
||||
|
||||
**Blocked By:** Nothing (ready to fix)
|
||||
|
||||
**Related Tasks:**
|
||||
- Task #7: Whitelist Manager (original deployment)
|
||||
- Task #47: Whitelist Manager Refinements (Mayview grouping)
|
||||
- Task #3: Pterodactyl Panel Update v1.12.1 (what broke it)
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
**Fix is complete when:**
|
||||
|
||||
- ✅ All servers show correct status (WHITELISTED/PUBLIC/OFF)
|
||||
- ✅ Server grouping correct (TX1: 5 servers, NC1: 6 servers)
|
||||
- ✅ No "Unknown" group (unless legitimate unknown servers)
|
||||
- ✅ Add player function works
|
||||
- ✅ Remove player function works
|
||||
- ✅ Bulk operations work (add/remove to ALL)
|
||||
- ✅ Recent Activity logs correctly
|
||||
- ✅ Code updated to handle both v1.11.x and v1.12.x API formats
|
||||
- ✅ Documentation updated with fix details
|
||||
- ✅ Post-update checklist added to Panel update procedure
|
||||
|
||||
---
|
||||
|
||||
## Technical Notes
|
||||
|
||||
### API Versioning
|
||||
|
||||
Pterodactyl does NOT use semantic API versioning. The API is tightly coupled to Panel version.
|
||||
|
||||
**This means:**
|
||||
- Minor Panel updates (1.11 → 1.12) can break API compatibility
|
||||
- No deprecation warnings
|
||||
- No API changelog
|
||||
- Must test integrations after EVERY Panel update
|
||||
|
||||
**Best practice:**
|
||||
- Write defensive code (use `.get()`, handle missing keys)
|
||||
- Support multiple API formats when possible
|
||||
- Log API responses for debugging
|
||||
- Add version detection to code
|
||||
|
||||
### Code Quality Improvements
|
||||
|
||||
**When fixing, also improve:**
|
||||
|
||||
1. **Error handling** - Better logging of API errors
|
||||
2. **API response caching** - Reduce API calls
|
||||
3. **Health check endpoint** - `/health` that tests API connectivity
|
||||
4. **Version detection** - Log Panel version from API
|
||||
5. **Fallback behavior** - Graceful degradation if API fails
|
||||
|
||||
**Example health check:**
|
||||
```python
|
||||
@app.route('/health')
|
||||
def health_check():
|
||||
"""Health check endpoint - tests Panel API connectivity"""
|
||||
try:
|
||||
response = requests.get(
|
||||
f"{PANEL_URL}/api/application/servers",
|
||||
headers={"Authorization": f"Bearer {API_KEY}"},
|
||||
timeout=5
|
||||
)
|
||||
if response.status_code == 200:
|
||||
data = response.json()
|
||||
return {
|
||||
"status": "healthy",
|
||||
"panel_api": "connected",
|
||||
"servers_count": len(data.get('data', []))
|
||||
}, 200
|
||||
else:
|
||||
return {
|
||||
"status": "unhealthy",
|
||||
"panel_api": "error",
|
||||
"error_code": response.status_code
|
||||
}, 500
|
||||
except Exception as e:
|
||||
return {
|
||||
"status": "unhealthy",
|
||||
"panel_api": "unreachable",
|
||||
"error": str(e)
|
||||
}, 500
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- **Original Deployment:** `docs/tasks/whitelist-manager/`
|
||||
- **Panel Update Log:** `docs/tasks/pterodactyl-panel-update/`
|
||||
- **Infrastructure Manifest:** `docs/core/infrastructure-manifest.md`
|
||||
- **Task Master List:** `docs/core/tasks.md`
|
||||
|
||||
---
|
||||
|
||||
## Future Enhancements (Phase 2)
|
||||
|
||||
**While fixing, consider adding:**
|
||||
|
||||
1. **Panel version detection** - Log Panel version on startup
|
||||
2. **API format auto-detection** - Detect v1.11.x vs v1.12.x format
|
||||
3. **Health monitoring** - `/health` endpoint for uptime monitoring
|
||||
4. **Better error messages** - User-facing errors if API fails
|
||||
5. **Retry logic** - Auto-retry failed API calls
|
||||
|
||||
**Don't over-engineer** - just get it working first, then iterate.
|
||||
|
||||
---
|
||||
|
||||
**Fire + Frost + Foundation = Where Love Builds Legacy** 💙🔥❄️
|
||||
|
||||
---
|
||||
|
||||
**Document Status:** ACTIVE
|
||||
**Task Status:** IDENTIFIED - Ready to fix
|
||||
**Ready to Build:** Yes (when home)
|
||||
Reference in New Issue
Block a user