firefrost-operations-manual/docs/tasks/pterodactyl-modpack-version-display/README.md

# Pterodactyl Modpack Version Display

**Status:** Ready  
**Priority:** Tier 3 - Quality of Life  
**Time:** 1-2 hours  
**Last Updated:** 2026-02-18  
**Created By:** The Chronicler

---

## Overview

Add a custom "Modpack Version" field to Pterodactyl panel that displays the current modpack version for each Minecraft server. Makes version tracking visible at a glance without digging through server files.

**Problem:** Currently no easy way to see which modpack version is running on each server  
**Solution:** Custom egg variable that displays in Startup tab

---

## Benefits

- ✅ **Version visibility** - See modpack version at a glance
- ✅ **Change tracking** - Know when updates were applied
- ✅ **Troubleshooting** - Quickly identify version mismatches
- ✅ **Documentation** - Server state clearly visible in panel
- ✅ **Staff clarity** - Everyone knows what's running

---

## Scope

**Affected Servers:**
- All The Mons (Cobblemon)
- Stoneblock 4
- Society: Sunlit Valley
- Reclamation
- The Ember Project
- Minecolonies: Create and Conquer
- All The Mods 10
- Homestead
- EMC Subterra Tech

**Not applicable:**
- Vanilla 1.21.11 (no modpack)
- Hytale (different game)
- FoundryVTT (not Minecraft)

---

## Implementation Methods

### Method 1: Egg Variable (Recommended)

**Pros:**
- Clean UI integration
- Per-server editable
- No code changes needed
- Visible in Startup tab

**Cons:**
- Manual entry (not auto-detected)
- Must update when modpack updates

**Complexity:** Low

---

### Method 2: Custom Script Parser

**Pros:**
- Auto-detects from modpack manifest
- No manual updates needed
- Always accurate

**Cons:**
- Requires custom Pterodactyl extension
- More complex to maintain
- Breaks on Pterodactyl updates

**Complexity:** High

---

## Recommended Approach: Egg Variable

**Create custom variable in Minecraft egg:**

### Variable Details

**Name:** Modpack Version  
**Description:** Current version of the modpack running on this server  
**Environment Variable:** `MODPACK_VERSION`  
**Default Value:** `Not Set`  
**User Viewable:** Yes  
**User Editable:** Yes (allows updates)  
**Rules:** None (free text)

---

## Implementation Steps

### Phase 1: Add Variable to Egg (15 minutes)

**Location:** Pterodactyl Admin Panel → Nests → Minecraft → [Egg]

1. Log into Pterodactyl admin panel
2. Navigate to **Nests** → **Minecraft**
3. Click on the egg used for modded servers (likely "Forge" or "NeoForge")
4. Go to **Variables** tab
5. Click **New Variable**

**Configuration:**

```
Name: Modpack Version
Description: Current version of the modpack (e.g., "1.2.3" or "2024-02-18")
Environment Variable: MODPACK_VERSION
Default Value: Not Set
Display Order: 10 (or any position you prefer)

Permissions:
☑ User Viewable
☑ User Editable
☐ Hidden from users
```

6. Click **Save**
7. The variable now appears in Startup tab for all servers using this egg

---

### Phase 2: Populate Current Versions (30 minutes)

**For each modpack server:**

1. Research current modpack version
   - Check modpack manifest file
   - Check CurseForge/Modrinth page
   - Check server files for version.json

2. Go to server in Pterodactyl panel
3. Click **Startup** tab
4. Find "Modpack Version" field
5. Enter current version (e.g., "1.5.2" or "2024-02-18")
6. Click **Save**

---

### Phase 3: Document Process (15 minutes)

**Create update procedure:**

When updating a modpack:
1. Update modpack files
2. Test server restart
3. Update "Modpack Version" field in Pterodactyl
4. Document in changelog

**Location:** `docs/procedures/modpack-update-procedure.md`

---

## Alternative: Display in Server Name

**Quick hack (no code needed):**

Include version in server display name:

**Before:** "All The Mons"  
**After:** "All The Mons [v1.5.2]"

**Pros:**
- Instantly visible in server list
- No panel modifications needed
- Works immediately

**Cons:**
- Clutters server name
- Must manually update name field
- Looks less professional

---

## Version Format Standards

**Recommended formats:**

### Semantic Versioning
- Format: `MAJOR.MINOR.PATCH`
- Example: `1.5.2`, `2.0.1`
- Best for: Official modpack releases

### Date-Based
- Format: `YYYY-MM-DD`
- Example: `2026-02-18`
- Best for: Custom/internal modpacks

### Hybrid
- Format: `VERSION (DATE)`
- Example: `1.5.2 (2026-02-18)`
- Best for: Tracking both

**Pick ONE format and use consistently across all servers.**

---

## Automation Opportunities (Future)

### Auto-Detection Script

**Concept:** Script that reads modpack version from manifest and updates Pterodactyl via API

```bash
#!/bin/bash
# Auto-update modpack version in Pterodactyl

SERVER_ID="668a5220-7e72-4379-9165-bdbb84bc9806"
MANIFEST="/var/lib/pterodactyl/volumes/${SERVER_ID}/manifest.json"

# Extract version from manifest
VERSION=$(jq -r '.version' "$MANIFEST")

# Update via Pterodactyl API
curl -X PUT "https://panel.firefrostgaming.com/api/application/servers/${SERVER_ID}/startup" \
  -H "Authorization: Bearer ${PTERO_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "{\"environment\": {\"MODPACK_VERSION\": \"${VERSION}\"}}"
```

**Status:** Future enhancement (not needed for MVP)

---

## Success Criteria

- ✅ Egg variable created in Pterodactyl
- ✅ Variable visible in Startup tab for all modded servers
- ✅ Current versions documented for all 9 modpack servers
- ✅ Update procedure documented
- ✅ Staff trained on updating field when modpacks update

---

## Rollback

**If implementation causes issues:**

1. Delete custom variable from egg
2. Field disappears from all servers
3. No data loss (versions can be recorded elsewhere)

**Risk:** None (purely cosmetic addition)

---

## Related Tasks

- **Task #23:** Game Server Startup Script Audit (same servers affected)
- **Future:** Automated version detection system
- **Future:** Changelog integration (link version to release notes)

---

## Notes

- This is a **tracking feature**, not a functional requirement
- Servers will run fine without it
- Primary benefit is **operational clarity**
- Consider extending to other metadata fields:
  - Minecraft version
  - Java version
  - Last updated date
  - Responsible admin

---

**Fire + Frost + Foundation = Where Love Builds Legacy** 💙🔥❄️

**Version tracking = Professional operations**