homelab-optimized/docs/hosts/vms/seattle/pufferpanel/README.md

# 🎮 PufferPanel Game Server Management

*Web-based game server management panel for the Seattle VM*

## Overview
PufferPanel provides a comprehensive web interface for managing game servers, including Minecraft, Source engine games, and other popular multiplayer games.

## Deployment Information

### Host Location
- **Host**: Seattle VM (`homelab_vm`)
- **Container**: `pufferpanel-seattle`
- **Status**: ✅ Active
- **Access**: `https://games.vish.gg`

### Container Configuration
```yaml
services:
  pufferpanel:
    image: pufferpanel/pufferpanel:latest
    container_name: pufferpanel-seattle
    restart: unless-stopped
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
    volumes:
      - pufferpanel-config:/etc/pufferpanel
      - pufferpanel-data:/var/lib/pufferpanel
      - game-servers:/var/lib/pufferpanel/servers
    ports:
      - "8080:8080"
      - "25565:25565"  # Minecraft
      - "27015:27015"  # Source games
    networks:
      - game-network
```

## Managed Game Servers

### Minecraft Servers
- **Vanilla Minecraft**: Latest release version
- **Paper Minecraft**: Performance-optimized server
- **Modded Minecraft**: Forge/Fabric mod support
- **Bedrock Edition**: Cross-platform compatibility

### Source Engine Games
- **Garry's Mod**: PropHunt and sandbox modes
- **Left 4 Dead 2**: Co-op survival campaigns
- **Counter-Strike**: Classic competitive gameplay
- **Team Fortress 2**: Team-based multiplayer

### Other Games
- **Satisfactory**: Factory building dedicated server
- **Valheim**: Viking survival multiplayer
- **Terraria**: 2D adventure and building
- **Don't Starve Together**: Survival multiplayer

## Server Management

### Web Interface
- **URL**: `https://games.vish.gg`
- **Authentication**: Local user accounts
- **Features**: Start/stop, console access, file management
- **Monitoring**: Real-time server status and logs

### User Management
```bash
# Create admin user
docker exec pufferpanel-seattle pufferpanel user add --admin admin

# Create regular user
docker exec pufferpanel-seattle pufferpanel user add player

# Set user permissions
docker exec pufferpanel-seattle pufferpanel user perms player server.minecraft.view
```

### Server Templates
- **Pre-configured**: Common game server templates
- **Custom templates**: Tailored server configurations
- **Auto-updates**: Automatic game updates
- **Backup integration**: Scheduled server backups

## Network Configuration

### Port Management
```yaml
# Port mappings for different games
ports:
  - "25565:25565"    # Minecraft Java
  - "19132:19132/udp" # Minecraft Bedrock
  - "27015:27015"    # Source games
  - "7777:7777/udp"  # Satisfactory
  - "2456-2458:2456-2458/udp" # Valheim
```

### Firewall Rules
```bash
# Allow game server ports
sudo ufw allow 25565/tcp comment "Minecraft Java"
sudo ufw allow 19132/udp comment "Minecraft Bedrock"
sudo ufw allow 27015/tcp comment "Source games"
sudo ufw allow 7777/udp comment "Satisfactory"
```

## Storage Management

### Server Data
```
/var/lib/pufferpanel/servers/
├── minecraft-vanilla/
│   ├── world/
│   ├── plugins/
│   └── server.properties
├── gmod-prophunt/
│   ├── garrysmod/
│   └── srcds_run
└── satisfactory/
    ├── FactoryGame/
    └── Engine/
```

### Backup Strategy
- **Automated backups**: Daily world/save backups
- **Retention policy**: 7 daily, 4 weekly, 12 monthly
- **Storage location**: `/mnt/backups/game-servers/`
- **Compression**: Gzip compression for space efficiency

## Performance Optimization

### Resource Allocation
```yaml
# Per-server resource limits
deploy:
  resources:
    limits:
      memory: 4G      # Minecraft servers
      cpus: '2.0'
    reservations:
      memory: 2G
      cpus: '1.0'
```

### Java Optimization (Minecraft)
```bash
# JVM arguments for Minecraft servers
-Xms2G -Xmx4G
-XX:+UseG1GC
-XX:+ParallelRefProcEnabled
-XX:MaxGCPauseMillis=200
-XX:+UnlockExperimentalVMOptions
-XX:+DisableExplicitGC
-XX:G1NewSizePercent=30
-XX:G1MaxNewSizePercent=40
```

### Network Optimization
- **TCP optimization**: Tuned for game traffic
- **Buffer sizes**: Optimized for low latency
- **Connection limits**: Prevent resource exhaustion
- **Rate limiting**: Anti-DDoS protection

## Monitoring and Alerts

### Server Monitoring
- **Resource usage**: CPU, memory, disk I/O
- **Player count**: Active players per server
- **Performance metrics**: TPS, latency, crashes
- **Uptime tracking**: Server availability statistics

### Alert Configuration
```yaml
# Prometheus alerts for game servers
- alert: GameServerDown
  expr: up{job="pufferpanel"} == 0
  for: 5m
  labels:
    severity: critical
  annotations:
    summary: "Game server {{ $labels.instance }} is down"

- alert: HighMemoryUsage
  expr: container_memory_usage_bytes{name="minecraft-server"} / container_spec_memory_limit_bytes > 0.9
  for: 10m
  labels:
    severity: warning
  annotations:
    summary: "High memory usage on {{ $labels.name }}"
```

## Security Configuration

### Access Control
- **User authentication**: Local user database
- **Role-based permissions**: Admin, moderator, player roles
- **Server isolation**: Containerized server environments
- **Network segmentation**: Isolated game network

### Security Hardening
```bash
# Disable unnecessary services
systemctl disable --now telnet
systemctl disable --now rsh

# Configure fail2ban for SSH
sudo fail2ban-client set sshd bantime 3600

# Regular security updates
sudo apt update && sudo apt upgrade -y
```

### Backup Security
- **Encrypted backups**: AES-256 encryption
- **Access controls**: Restricted backup access
- **Integrity checks**: Backup verification
- **Offsite storage**: Cloud backup copies

## Troubleshooting

### Common Issues

#### Server Won't Start
```bash
# Check server logs
docker exec pufferpanel-seattle pufferpanel logs minecraft-server

# Verify port availability
netstat -tulpn | grep :25565

# Check resource limits
docker stats pufferpanel-seattle
```

#### Connection Issues
```bash
# Test network connectivity
telnet games.vish.gg 25565

# Check firewall rules
sudo ufw status numbered

# Verify DNS resolution
nslookup games.vish.gg
```

#### Performance Problems
```bash
# Monitor resource usage
htop

# Check disk I/O
iotop

# Analyze network traffic
nethogs
```

### Log Analysis
```bash
# View PufferPanel logs
docker logs pufferpanel-seattle

# View specific server logs
docker exec pufferpanel-seattle tail -f /var/lib/pufferpanel/servers/minecraft/logs/latest.log

# Check system logs
journalctl -u docker -f
```

## Maintenance Procedures

### Regular Maintenance
- **Weekly**: Server restarts and updates
- **Monthly**: Backup verification and cleanup
- **Quarterly**: Security audit and updates
- **Annually**: Hardware assessment and upgrades

### Update Procedures
```bash
# Update PufferPanel
docker pull pufferpanel/pufferpanel:latest
docker-compose up -d pufferpanel

# Update game servers
# Use PufferPanel web interface for game updates
```

### Backup Procedures
```bash
# Manual backup
docker exec pufferpanel-seattle pufferpanel backup create minecraft-server

# Restore from backup
docker exec pufferpanel-seattle pufferpanel backup restore minecraft-server backup-name
```

## Integration with Homelab

### Monitoring Integration
- **Prometheus**: Server metrics collection
- **Grafana**: Performance dashboards
- **NTFY**: Alert notifications
- **Uptime Kuma**: Service availability monitoring

### Authentication Integration
- **Authentik SSO**: Single sign-on integration (planned)
- **LDAP**: Centralized user management (planned)
- **Discord**: Player authentication via Discord (planned)

### Backup Integration
- **Automated backups**: Integration with homelab backup system
- **Cloud storage**: Backup to cloud storage
- **Monitoring**: Backup success/failure notifications

---
**Status**: ✅ PufferPanel managing multiple game servers with automated backups and monitoring