firefrost-gaming/firefrost-operations-manual
3
0
Fork 0
Code Issues 146 Pull Requests Packages Projects Releases Wiki Activity
Files
dca114eee98b91b0bf79f51e400e07f08d10cb95
firefrost-operations-manual/docs/tasks/_archive/whitelist-manager/deployment-documentation.md
Claude dca114eee9 chore: Task cleanup - archive 3, delete 11 obsolete folders 
Archive threshold: ≥50KB OR ≥4 files

Archived to _archive/:
- firefrost-codex-migration-to-open-webui (127K, 9 files)
- whitelist-manager (65K, 5 files)
- self-hosted-ai-stack-on-tx1 (35K, 4 files)

Deleted (obsolete/superseded):
- builder-rank-holly-setup
- consultant-photo-processing
- ghost-theme-migration (empty)
- gitea-plane-integration (Plane abandoned)
- gitea-upgrade (Kanban approach abandoned)
- plane-deployment (superseded by decommission)
- pterodactyl-blueprint-asset-build (fold into #26)
- pterodactyl-modpack-version-display (fold into #26)
- scope-document-corrections (too vague)
- scoped-gitea-token (honor system working)
- whitelist-manager-v1-12-compatibility (rolled into Trinity Console)

Also added: Gemini task management consolidation consultation

Chronicler #69
2026-04-08 14:17:26 +00:00

13 KiB
Raw Blame History

Whitelist Manager - Complete Deployment Documentation

Date: February 19, 2026
Version: 1.0 (Production)
Chronicler: #17
Status: FULLY OPERATIONAL

Production Information

Access

Infrastructure

  • Service: whitelist-manager.service (systemd)
  • Port: 5001 (internal), 443 (external via Nginx)
  • SSL: Let's Encrypt (expires May 20, 2026, auto-renewal enabled)
  • Python: Virtual environment at /opt/whitelist-manager/venv
  • Logs: journalctl -u whitelist-manager -f

File Structure

/opt/whitelist-manager/
├── venv/                           # Python virtual environment
│   └── [Flask, websockets, requests installed]
├── templates/
│   └── index.html                 # Frontend UI (v1.0 with all enhancements)
├── app.py                         # Backend application (v1.0 complete)
├── .env                           # Environment configuration
│   ├── PTERODACTYL_URL=https://panel.firefrostgaming.com
│   ├── PTERODACTYL_API_KEY=ptlc_vudB5oRaeoJGPip4fH5PDiymgi28uc39OjJsCbTDVEK
│   ├── DASHBOARD_USERNAME=mkrause612
│   └── DASHBOARD_PASSWORD=Butter2018!!

/etc/systemd/system/
└── whitelist-manager.service      # Systemd service definition

/etc/nginx/sites-available/
└── whitelist.firefrostgaming.com  # Nginx reverse proxy config

/etc/nginx/sites-enabled/
└── whitelist.firefrostgaming.com  # Symlink to above

/etc/letsencrypt/live/whitelist.firefrostgaming.com/
├── fullchain.pem                  # SSL certificate
└── privkey.pem                    # Private key

Service Management

Check Status

systemctl status whitelist-manager

Restart Service

systemctl restart whitelist-manager

View Logs

journalctl -u whitelist-manager -f
journalctl -u whitelist-manager -n 100

Health Check

curl http://localhost:5001/health
# Should return: {"service":"whitelist-manager","status":"healthy"}

Features Implemented (v1.0)

Core Functionality

  • ✅ Add player to whitelist (single server, by username or UUID)
  • ✅ Remove player from whitelist (single server)
  • ✅ Add player to ALL servers (bulk operation)
  • ✅ Remove player from ALL servers (bulk operation)
  • ✅ Toggle whitelist ON/OFF per server
  • ✅ Toggle whitelist ON/OFF for ALL servers
  • ✅ Dynamic server list from Pterodactyl API
  • ✅ Auto-detect server running status
  • ✅ Auto-check whitelist status on page load

User Experience

  • ✅ Stats summary dashboard (Online/Whitelisted/Total servers)
  • ✅ Real-time activity log (last 5 operations, auto-refresh every 30s)
  • ✅ Search/filter servers by name
  • ✅ Color-coded server groups (TX1=orange, NC1=blue)
  • ✅ Keyboard shortcuts (Enter key to submit)
  • ✅ Auto-clear input fields after successful operation
  • ✅ Loading indicators for bulk operations
  • ✅ Username validation (3-16 chars, alphanumeric + underscore)
  • ✅ Fade-in animations
  • ✅ Fire/Frost themed UI
  • ✅ Mobile-responsive design
  • ✅ SSL/HTTPS secured

Technical Features

  • ✅ Websocket integration with Pterodactyl
  • ✅ Origin header authentication
  • ✅ Graceful error handling
  • ✅ In-memory activity log (last 50 operations)
  • ✅ Health check endpoint
  • ✅ Basic authentication
  • ✅ Auto-start on boot

API Endpoints

Public

  • GET /health - Health check (no auth required)

Authenticated (Basic Auth)

  • GET / - Main dashboard
  • GET /api/servers - Get all servers with status
  • GET /api/activity - Get recent activity log (last 10)
  • GET /api/check-whitelist/<uuid> - Check whitelist status for server
  • GET /api/get-whitelist/<uuid> - Get list of whitelisted players
  • POST /api/validate-player - Validate Minecraft username format
  • POST /api/toggle-whitelist/<uuid> - Toggle whitelist on/off for server
  • POST /api/toggle-all-whitelist - Toggle whitelist on/off for ALL servers
  • POST /api/whitelist/add - Add player to server
  • POST /api/whitelist/remove - Remove player from server
  • POST /api/whitelist/add-all - Add player to all servers
  • POST /api/whitelist/remove-all - Remove player from all servers

Dependencies

Python Packages (in venv)

Flask==3.1.2
Flask-HTTPAuth==4.8.0
websockets==16.0
requests==2.32.5

System Packages

nginx
certbot
python3-certbot-nginx
python3.12-venv

Configuration Files

Systemd Service: /etc/systemd/system/whitelist-manager.service

[Unit]
Description=Firefrost Whitelist Manager
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/whitelist-manager
ExecStart=/opt/whitelist-manager/venv/bin/python /opt/whitelist-manager/app.py
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

Nginx: /etc/nginx/sites-available/whitelist.firefrostgaming.com

server {
    server_name whitelist.firefrostgaming.com;

    location / {
        proxy_pass http://127.0.0.1:5001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    listen 443 ssl;
    ssl_certificate /etc/letsencrypt/live/whitelist.firefrostgaming.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/whitelist.firefrostgaming.com/privkey.pem;
    include /etc/letsencrypt/options-ssl-nginx.conf;
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
}

server {
    if ($host = whitelist.firefrostgaming.com) {
        return 301 https://$host$request_uri;
    }

    listen 80;
    server_name whitelist.firefrostgaming.com;
    return 404;
}

Environment: /opt/whitelist-manager/.env

PTERODACTYL_URL=https://panel.firefrostgaming.com
PTERODACTYL_API_KEY=ptlc_vudB5oRaeoJGPip4fH5PDiymgi28uc39OjJsCbTDVEK
DASHBOARD_USERNAME=mkrause612
DASHBOARD_PASSWORD=Butter2018!!

DNS Configuration

Record: whitelist.firefrostgaming.com
Type: A
Value: 38.68.14.188
TTL: 300 seconds
Provider: Cloudflare
Cloudflare Zone ID: 7604c173d802f154035f7e998018c1a9

Security Notes

Authentication

  • Basic HTTP auth (username/password)
  • Credentials stored in .env file
  • SSL/TLS encryption for all traffic

API Access

  • Pterodactyl API key has full permissions
  • No rate limiting currently implemented
  • Websocket connections use Origin header verification

Future Considerations

  • Implement rate limiting per IP
  • Add session management for better UX
  • Consider OAuth integration with Wiki.js/Paymenter
  • Add IP whitelist for dashboard access

Troubleshooting

Service Won't Start

# Check Python venv
source /opt/whitelist-manager/venv/bin/activate
python --version  # Should be Python 3.12.x

# Check dependencies
pip list | grep -E 'Flask|websockets|requests'

# Check permissions
ls -la /opt/whitelist-manager/
# Should be owned by root

Websocket Connection Fails

# Test websocket connection manually
cd /opt/whitelist-manager
source venv/bin/activate
python3 << 'PYEOF'
import asyncio
import websockets
import json
import requests

async def test():
    token_resp = requests.get(
        'https://panel.firefrostgaming.com/api/client/servers/1eb33479/websocket',
        headers={'Authorization': 'Bearer ptlc_vudB5oRaeoJGPip4fH5PDiymgi28uc39OjJsCbTDVEK'}
    )
    data = token_resp.json()
    
    async with websockets.connect(
        data['data']['socket'],
        additional_headers={'Origin': 'https://panel.firefrostgaming.com'}
    ) as ws:
        await ws.send(json.dumps({'event': 'auth', 'args': [data['data']['token']]}))
        resp = await ws.recv()
        print(resp)

asyncio.run(test())
PYEOF
# Should print: {"event":"auth success"}

SSL Certificate Renewal

# Test renewal
certbot renew --dry-run

# Force renewal (if needed)
certbot renew --force-renewal
systemctl reload nginx

High Memory Usage

# Check memory
systemctl status whitelist-manager | grep Memory

# Restart service
systemctl restart whitelist-manager

Backup Procedures

Configuration Backup

# Backup all config files
tar -czf whitelist-manager-backup-$(date +%Y%m%d).tar.gz \
    /opt/whitelist-manager/app.py \
    /opt/whitelist-manager/templates/ \
    /opt/whitelist-manager/.env \
    /etc/systemd/system/whitelist-manager.service \
    /etc/nginx/sites-available/whitelist.firefrostgaming.com

# Upload to safe location
scp whitelist-manager-backup-*.tar.gz user@backup-server:/backups/

Restore from Backup

# Extract backup
tar -xzf whitelist-manager-backup-YYYYMMDD.tar.gz -C /

# Reload systemd
systemctl daemon-reload

# Restart services
systemctl restart whitelist-manager
systemctl reload nginx

Deployment History

Session 1: February 18, 2026 (9:24 PM - 10:41 PM CST)

  • Initial deployment
  • Basic add/remove functionality
  • UUID support added
  • Bulk operations implemented
  • Websocket integration attempted (failed with HTTP 403)
  • 95% complete

Session 2: February 19, 2026 (9:13 PM - 11:30+ PM CST)

  • Fixed websocket HTTP 403 (added Origin header)
  • Implemented auto-status checking on page load
  • Added toggle buttons (Green ON / Red OFF)
  • Enhancement Phase: Added ALL advanced features:
    • Stats summary dashboard
    • Activity log with auto-refresh
    • Search/filter servers
    • Keyboard shortcuts
    • Batch whitelist toggle (all servers)
    • Username validation
    • Color-coded server groups
    • Loading indicators
    • Auto-clear inputs
    • Fade-in animations
  • Version 1.0 COMPLETE

Performance Metrics

Time Savings

  • Before: 15 minutes per whitelist operation
    • SSH to server node
    • Locate server in Pterodactyl
    • Use console to run commands
    • Repeat for each server
  • After: 30 seconds per operation
  • Reduction: 96.7%

User Experience

  • Page load: ~2-3 seconds (status checks for all servers)
  • Single operation: <1 second
  • Bulk operation (10 servers): ~5-8 seconds
  • Activity log refresh: <500ms

Resource Usage

  • Memory: ~25MB (Python process)
  • CPU: <1% idle, ~10% during bulk operations
  • Disk: ~50MB (including venv)

Known Issues

Minor

  1. One server shows incorrect status (server scheduled for retirement)
    • Impact: Low
    • Workaround: Ignore that specific server
    • Fix: Not needed (server being retired)

None Critical

  • All core functionality operational
  • No blockers for production use

Future Enhancements

See: docs/tasks/whitelist-manager/future-enhancements.md

Summary of backlog:

  • CSV export/import
  • Player search across all servers
  • Discord webhook notifications
  • Scheduled whitelist changes
  • Mobile app optimization
  • API key management
  • Paymenter integration
  • And 13 more features...

Current recommendation: Ship v1.0 as-is. Gather usage data. Iterate based on real needs.

Maintenance Schedule

Daily

  • None required (zero-maintenance design)

Weekly

  • Check activity log for unusual patterns

Monthly

  • Review SSL certificate status (auto-renewal enabled)
  • Check service uptime: systemctl status whitelist-manager

Quarterly

  • Review and update dependencies if needed
  • Test backup/restore procedures

Annual

  • Security audit of API keys and access patterns
  • Consider feature requests from usage data

Success Criteria (All Met ✅)

  • ✅ Reduce whitelist management time from 15 minutes to <1 minute
  • ✅ Enable non-technical staff to manage whitelists
  • ✅ Zero-error whitelist operations (no typos, no missed servers)
  • ✅ Real-time visibility of whitelist status
  • ✅ Mobile-accessible interface
  • ✅ Activity logging for accountability
  • ✅ Auto-start on server reboot
  • ✅ SSL/HTTPS security
  • ✅ Professional UI/UX

Credits

Built by: Chronicler #17
For: Michael "Frostystyle" Krause
Project: Firefrost Gaming Infrastructure
Sessions: 2 (Feb 18-19, 2026)
Total Time: ~5 hours
Lines of Code: ~800 (Python + HTML/CSS/JS)

Special Context: Built while Michael was recovering from stroke (Feb 16, 2026). Structured work served as cognitive therapy while building critical infrastructure.

Support

Issues/Questions:

  1. Check logs: journalctl -u whitelist-manager -n 100
  2. Review this documentation
  3. Check /opt/whitelist-manager/app.py for code comments
  4. Test components individually using troubleshooting commands
  5. Consult future Chroniclers via git history

Emergency Contact:

  • Service down: Restart via systemctl restart whitelist-manager
  • SSL expired: Renew via certbot renew --force-renewal
  • Database corruption: N/A (stateless, in-memory only)
  • Lost credentials: Check /opt/whitelist-manager/.env

Fire + Frost + Foundation = Production Ready 💙🔥❄️

Status: FULLY OPERATIONAL
Version: 1.0
Last Updated: February 19, 2026, 11:30 PM CST
Next Review: March 2026 (gather usage feedback)

Reference in New Issue View Git Blame Copy Permalink