firefrost-operations-manual/docs/tasks/whitelist-manager/deployment-documentation.md

# Whitelist Manager - Complete Deployment Documentation

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

---

## Production Information

### Access
- **URL:** https://whitelist.firefrostgaming.com
- **Location:** Billing VPS (38.68.14.188, Chicago IL)
- **Authentication:** Basic Auth
  - Username: `mkrause612`
  - Password: `Butter2018!!`

### 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
```bash
systemctl status whitelist-manager
```

### Restart Service
```bash
systemctl restart whitelist-manager
```

### View Logs
```bash
journalctl -u whitelist-manager -f
journalctl -u whitelist-manager -n 100
```

### Health Check
```bash
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`
```ini
[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`
```nginx
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`
```bash
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
```bash
# 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
```bash
# 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
```bash
# Test renewal
certbot renew --dry-run

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

### High Memory Usage
```bash
# Check memory
systemctl status whitelist-manager | grep Memory

# Restart service
systemctl restart whitelist-manager
```

---

## Backup Procedures

### Configuration Backup
```bash
# 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
```bash
# 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)