firefrost-gaming/firefrost-operations-manual
3
0
Fork 0
Code Issues 146 Pull Requests Packages Projects Releases Wiki Activity

docs: Add comprehensive JVM optimization guide for game servers

Browse Source 
Created complete optimization guide (500+ lines):

Modern JVM Flags (2024-2026 Best Practices):
- Aikar's Flags optimized for Minecraft
- G1GC configuration for 4-16GB heaps
- Per-server RAM recommendations (all 11 servers)
- Deprecated flags to remove

Server-Specific Configuration:
- Vanilla: 4GB (lightweight)
- Standard modpacks: 8GB
- Heavy modpacks: 10-12GB
- ATM10: 16GB (kitchen sink)
- Custom G1HeapRegionSize per heap size

Implementation:
- 3-phase deployment (backup, update, monitor)
- Via Pterodactyl panel startup variables
- 1 hour total for all 11 servers
- Rollback procedure included

Performance Impact:
- Expected +0.5 to +2 TPS improvement
- More stable memory usage
- Shorter GC pause times
- Fewer lag spikes

Comprehensive troubleshooting for common issues.
Ready to execute via Pterodactyl panel.

Task: Game Server Startup Script Audit (Tier 3)
FFG-STD-002 compliant
This commit is contained in:
Claude
2026-02-18 00:50:58 +00:00
parent 5466cd07c2
commit ab14e1c276
1 changed files with 513 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

513
docs/tasks/game-server-startup-script-audit-&-optimization/optimization-guide.md Normal file
View File

@@ -0,0 +1,513 @@
# Game Server Startup Script Audit & Optimization - Complete Guide
**Status:** Ready to Execute
**Priority:** Tier 3 - Performance Optimization
**Time Estimate:** 1 hour (all 11 servers)
**Last Updated:** 2026-02-17
---
## Overview
Comprehensive audit and optimization of JVM startup flags for all 11 Minecraft servers. Modernize flags, optimize memory allocation, and improve performance using current best practices for Java 17/21.
**Benefits:**
- Reduced lag and improved TPS
- Better garbage collection performance
- Optimized memory usage
- Fewer crashes and OOM errors
- Future-proofed for modern Java versions
---
## Current Server List (11 Servers)
**TX1 Dallas (5 servers):**
1. Vanilla 1.21.11
2. All The Mons
3. Stoneblock 4
4. Society: Sunlit Valley
5. Reclamation
**NC1 Charlotte (6 servers):**
6. The Ember Project
7. Minecolonies: Create and Conquer
8. All The Mods 10
9. Homestead
10. EMC Subterra Tech
11. Hytale (non-Minecraft)
---
## Modern JVM Optimization Strategy
### Java Version Considerations
**For Minecraft 1.20+:** Java 17 or 21 (recommended)
**For older modpacks:** Java 17 minimum
**Never use:** Java 8 (outdated, poor performance)
---
## Recommended JVM Flags (2024-2026 Best Practices)
### For Servers with 8-16GB RAM (Most Servers)
```bash
java -Xms8G -Xmx8G \
-XX:+UseG1GC \
-XX:+ParallelRefProcEnabled \
-XX:MaxGCPauseMillis=200 \
-XX:+UnlockExperimentalVMOptions \
-XX:+DisableExplicitGC \
-XX:+AlwaysPreTouch \
-XX:G1NewSizePercent=30 \
-XX:G1MaxNewSizePercent=40 \
-XX:G1HeapRegionSize=8M \
-XX:G1ReservePercent=20 \
-XX:G1HeapWastePercent=5 \
-XX:G1MixedGCCountTarget=4 \
-XX:InitiatingHeapOccupancyPercent=15 \
-XX:G1MixedGCLiveThresholdPercent=90 \
-XX:G1RSetUpdatingPauseTimePercent=5 \
-XX:SurvivorRatio=32 \
-XX:+PerfDisableSharedMem \
-XX:MaxTenuringThreshold=1 \
-Dusing.aikars.flags=https://mcflags.emc.gs \
-Daikars.new.flags=true \
-jar server.jar nogui
```
**These are Aikar's Flags (2024 edition) - proven optimal for Minecraft.**
---
### For ATM10 (16GB+ RAM, Memory-Hungry Modpack)
```bash
java -Xms16G -Xmx16G \
-XX:+UseG1GC \
-XX:+ParallelRefProcEnabled \
-XX:MaxGCPauseMillis=200 \
-XX:+UnlockExperimentalVMOptions \
-XX:+DisableExplicitGC \
-XX:+AlwaysPreTouch \
-XX:G1NewSizePercent=30 \
-XX:G1MaxNewSizePercent=40 \
-XX:G1HeapRegionSize=16M \
-XX:G1ReservePercent=20 \
-XX:G1HeapWastePercent=5 \
-XX:G1MixedGCCountTarget=4 \
-XX:InitiatingHeapOccupancyPercent=15 \
-XX:G1MixedGCLiveThresholdPercent=90 \
-XX:G1RSetUpdatingPauseTimePercent=5 \
-XX:SurvivorRatio=32 \
-XX:+PerfDisableSharedMem \
-XX:MaxTenuringThreshold=1 \
-Dusing.aikars.flags=https://mcflags.emc.gs \
-Daikars.new.flags=true \
-jar server.jar nogui
```
---
### For Vanilla (Lightweight, 4-6GB RAM)
```bash
java -Xms4G -Xmx4G \
-XX:+UseG1GC \
-XX:+ParallelRefProcEnabled \
-XX:MaxGCPauseMillis=200 \
-XX:+UnlockExperimentalVMOptions \
-XX:+DisableExplicitGC \
-XX:+AlwaysPreTouch \
-XX:G1HeapRegionSize=8M \
-XX:G1ReservePercent=20 \
-XX:G1HeapWastePercent=5 \
-XX:G1MixedGCCountTarget=4 \
-XX:InitiatingHeapOccupancyPercent=15 \
-XX:G1MixedGCLiveThresholdPercent=90 \
-XX:SurvivorRatio=32 \
-XX:+PerfDisableSharedMem \
-XX:MaxTenuringThreshold=1 \
-jar server.jar nogui
```
---
## Flag Explanations
### Memory Allocation
**-Xms and -Xmx (ALWAYS SET EQUAL)**
- `-Xms8G` - Initial heap size
- `-Xmx8G` - Maximum heap size
- **Critical:** Must be equal to avoid heap resizing overhead
- **Rule:** Allocate 80% of available RAM to Minecraft
**Why equal?** Prevents Java from dynamically resizing heap (causes lag spikes)
---
### Garbage Collection (G1GC)
**-XX:+UseG1GC**
- Use G1 Garbage Collector (best for Minecraft)
- Designed for large heaps (>4GB)
- Low pause times
- Better than CMS, ZGC, or Shenandoah for MC
**-XX:MaxGCPauseMillis=200**
- Target max GC pause time: 200ms
- Lower = more frequent but shorter pauses
- 200ms is sweet spot for Minecraft
**-XX:+ParallelRefProcEnabled**
- Process references in parallel
- Reduces GC pause time
---
### G1GC Tuning
**-XX:G1NewSizePercent=30**
**-XX:G1MaxNewSizePercent=40**
- Young generation size: 30-40% of heap
- Optimized for Minecraft's object creation patterns
**-XX:G1HeapRegionSize=8M (or 16M for large heaps)**
- Size of G1 heap regions
- 8M for <16GB heaps
- 16M for 16GB+ heaps
**-XX:G1ReservePercent=20**
- Reserve 20% of heap to prevent full GC
- Safety margin for allocation spikes
**-XX:InitiatingHeapOccupancyPercent=15**
- Start concurrent GC when heap is 15% full
- Earlier start = smoother collection
---
### Performance Flags
**-XX:+AlwaysPreTouch**
- Pre-touch all memory at startup
- Prevents lazy allocation lag during gameplay
**-XX:+DisableExplicitGC**
- Ignore System.gc() calls from mods
- Prevents mods from triggering GC unnecessarily
**-XX:+PerfDisableSharedMem**
- Disable JVM performance data collection
- Reduces disk I/O
**-XX:MaxTenuringThreshold=1**
- Promote objects to old generation quickly
- Optimized for Minecraft's object lifecycle
---
## Deprecated Flags to REMOVE
**Remove these if found in current startup scripts:**
```bash
# REMOVE - Outdated
-XX:+UseConcMarkSweepGC # Use G1GC instead
-XX:+CMSParallelRemarkEnabled
-XX:+CMSIncrementalMode
-XX:+CMSClassUnloadingEnabled
# REMOVE - Deprecated in Java 17+
-XX:+AggressiveOpts
-XX:+UseAdaptiveSizePolicy
# REMOVE - Can cause issues
-XX:+UseStringDeduplication # Can cause memory leaks
-Xmn (explicit young gen size) # Let G1 manage it
# REMOVE - Not helpful
-server # Default in modern Java
```
---
## Server-Specific Recommendations
### Vanilla 1.21.11
**RAM:** 4GB (Xms4G -Xmx4G)
**Reason:** Vanilla is lightweight
**Special:** None needed
### All The Mons (Cobblemon)
**RAM:** 8GB (Xms8G -Xmx8G)
**Reason:** Moderate mod count
**Special:** None
### Stoneblock 4
**RAM:** 8GB (Xms8G -Xmx8G)
**Reason:** Skyblock with tech mods
**Special:** None
### Society: Sunlit Valley
**RAM:** 8GB (Xms8G -Xmx8G)
**Reason:** Moderate modpack
**Special:** None
### Reclamation
**RAM:** 8GB (Xms8G -Xmx8G)
**Reason:** Moderate modpack
**Special:** None
### The Ember Project
**RAM:** 10GB (Xms10G -Xmx10G)
**Reason:** Large modpack
**Special:** None
### Minecolonies: Create and Conquer
**RAM:** 12GB (Xms12G -Xmx12G)
**Reason:** Minecolonies is RAM-hungry
**Special:** May need more if colonies grow large
### All The Mods 10 (ATM10)
**RAM:** 16GB (Xms16G -Xmx16G)
**Reason:** Kitchen sink modpack, very large
**Special:** G1HeapRegionSize=16M for large heap
**Note:** Known memory leak - monitor closely
### Homestead
**RAM:** 8GB (Xms8G -Xmx8G)
**Reason:** Moderate modpack
**Special:** None
### EMC Subterra Tech
**RAM:** 10GB (Xms10G -Xmx10G)
**Reason:** Tech-focused modpack
**Special:** None
---
## Implementation Procedure
### Phase 1: Backup Current Scripts (5 min)
```bash
# On TX1 and NC1
cd /var/lib/pterodactyl/volumes
# Backup all startup scripts
for server in */; do
if [ -f "${server}start.sh" ]; then
cp "${server}start.sh" "${server}start.sh.backup.$(date +%Y%m%d)"
fi
done
```
---
### Phase 2: Update via Pterodactyl Panel (40 min)
**For each server:**
1. Log into panel.firefrostgaming.com
2. Navigate to server
3. Go to **Startup** tab
4. Edit **Java Arguments** field
5. Replace with recommended flags (from above)
6. Click **Save**
7. Restart server
8. Monitor for 10 minutes
**Test checklist per server:**
- Server starts successfully
- Players can join
- TPS remains stable (use `/tps` or `/forge tps`)
- No errors in console
- Memory usage is stable
---
### Phase 3: Monitor Performance (15 min)
**Check after 24 hours:**
- TPS average (should be 19.5-20)
- GC pause times (check logs)
- Memory usage patterns
- Player reports of lag
**Tools:**
- Pterodactyl console
- `/tps` command in-game
- Server logs for GC messages
---
## Pterodactyl Startup Variable
**In Pterodactyl, the startup command looks like:**
```
java {{JAVA_ARGS}} -jar {{SERVER_JARFILE}} nogui
```
**The {{JAVA_ARGS}} variable is where you paste the optimization flags.**
**Example for 8GB server:**
```
-Xms8G -Xmx8G -XX:+UseG1GC -XX:+ParallelRefProcEnabled -XX:MaxGCPauseMillis=200 -XX:+UnlockExperimentalVMOptions -XX:+DisableExplicitGC -XX:+AlwaysPreTouch -XX:G1NewSizePercent=30 -XX:G1MaxNewSizePercent=40 -XX:G1HeapRegionSize=8M -XX:G1ReservePercent=20 -XX:G1HeapWastePercent=5 -XX:G1MixedGCCountTarget=4 -XX:InitiatingHeapOccupancyPercent=15 -XX:G1MixedGCLiveThresholdPercent=90 -XX:G1RSetUpdatingPauseTimePercent=5 -XX:SurvivorRatio=32 -XX:+PerfDisableSharedMem -XX:MaxTenuringThreshold=1 -Dusing.aikars.flags=https://mcflags.emc.gs -Daikars.new.flags=true
```
---
## Common Issues & Solutions
### Server Won't Start After Update
**Issue:** Server crashes on startup
**Check:**
- RAM allocation doesn't exceed available RAM
- Java version is compatible (17 or 21)
- No typos in flags
**Fix:**
- Restore backup: `start.sh.backup.YYYYMMDD`
- Reduce RAM allocation
- Verify Java version: `java -version`
---
### Worse Performance After Update
**Issue:** TPS lower than before
**Possible causes:**
- RAM allocation too high (swapping to disk)
- G1HeapRegionSize wrong for heap size
- Java version incompatibility
**Fix:**
- Reduce RAM allocation by 2GB
- For <16GB heap, use `G1HeapRegionSize=8M`
- For 16GB+ heap, use `G1HeapRegionSize=16M`
---
### Memory Leaks (ATM10)
**Issue:** Memory usage keeps climbing
**ATM10 specific:** Known memory leak in some versions
**Solution:**
- Increase restart frequency (use staggered restart system)
- Monitor memory usage via Pterodactyl
- Alert when usage hits 90%
- Restart before OOM
---
## Performance Testing
### Before Optimization (Record Baseline)
For each server, record:
- Average TPS (check over 1 hour)
- Memory usage (initial, average, peak)
- GC frequency and pause time
- Player complaints
### After Optimization (Compare)
Same metrics after 24 hours:
- TPS should improve by 0.5-2
- Memory usage should be more stable
- GC pauses should be shorter
- Fewer lag spikes
---
## Documentation Template
**After updating each server, document:**
```
Server: [Name]
Date: 2026-02-17
Previous Flags: [paste old flags]
New Flags: [paste new flags]
RAM: [old] → [new]
Java Version: [version]
Performance:
- TPS Before: X.X
- TPS After: X.X
- Improvement: +X.X TPS
- Notes: [any observations]
```
Save in: `docs/reference/startup-optimization-log.md`
---
## Rollback Procedure
**If optimization causes problems:**
```bash
# Via Pterodactyl panel:
1. Go to Startup tab
2. Restore previous flags from backup
3. Save and restart
# Or via SSH (if needed):
cd /var/lib/pterodactyl/volumes/[uuid]/
mv start.sh.backup.YYYYMMDD start.sh
# Restart via panel
```
---
## Additional Optimizations (Optional)
### CPU Affinity (Advanced)
Pin specific servers to specific CPU cores for better performance:
```bash
taskset -c 0-7 java [flags...] -jar server.jar nogui
```
**Example:** Pin ATM10 to cores 0-15 (first 16 cores)
### Huge Pages (Advanced)
Enable huge pages for better memory performance:
```bash
# Add to JVM flags
-XX:+UseTransparentHugePages
```
---
## References
- **Aikar's Flags:** https://mcflags.emc.gs (official source)
- **G1GC Documentation:** https://docs.oracle.com/en/java/javase/17/gctuning/
- **Minecraft Optimization Guide:** https://github.com/brucethemoose/Minecraft-Performance-Flags-Benchmarks
---
**Fire + Frost + Foundation = Where Love Builds Legacy** 💙🔥❄️
---
**Document Status:** COMPLETE
**Ready to Execute:** When Pterodactyl panel access available (1 hour)
**Risk Level:** LOW (easy rollback via backups)
**Expected Improvement:** +0.5 to +2 TPS per server