Add Task #104: Server-Side Mod Deployment Automation
- Gemini consultation documented - Chose Option B (Trinity Console Push) for speed - Holly working in parallel with her Catalyst - Will compare approaches and merge best ideas
This commit is contained in:
Claude
@@ -0,0 +1,120 @@
|
||||
# Gemini Consultation: Server-Side Mod Deployment Automation
|
||||
|
||||
**Date:** April 9, 2026
|
||||
**From:** Michael (The Wizard) + Claude (Chronicler #74)
|
||||
**To:** Gemini (Architectural Partner)
|
||||
**Re:** Automating deployment of server-side mods to Minecraft servers
|
||||
|
||||
---
|
||||
|
||||
## The Problem
|
||||
|
||||
Every time we deploy a new public modpack, Holly has to manually install and configure 14 server-side mods. She has 10 servers to do this on, and it takes about an hour per server. That's 10 hours of repetitive file manager work.
|
||||
|
||||
---
|
||||
|
||||
## Current State
|
||||
|
||||
- **Pterodactyl Panel** manages all game servers
|
||||
- **3 Minecraft versions** in use: 1.16.5, 1.20.1, 1.21.1
|
||||
- **14 server-side mods** per server (different mod sets per MC version)
|
||||
- **Mods sourced from** CurseForge (mostly)
|
||||
- **Configs are identical** across servers of the same MC version
|
||||
- **MC version is stored** in Pterodactyl egg variables (already queryable)
|
||||
- **Current process:** Manual download → SFTP/File Manager → configure each server
|
||||
|
||||
---
|
||||
|
||||
## Gemini's Response
|
||||
|
||||
### 1. Best Storage Location for Bundles
|
||||
|
||||
**The Winner:** S3-Compatible Storage (MinIO or B2) or a dedicated Web Server directory.
|
||||
|
||||
While Gitea is great for configs, putting 42+ JAR files (14 mods × 3 versions) into Git will bloat your repo quickly.
|
||||
|
||||
**Why S3/Web Server?** It provides a direct download URL. Pterodactyl's "Startup Command" or a deployment script can easily wget or curl a single zip file from a URL.
|
||||
|
||||
**Recommendation:** Store them on the Command Center in a public-facing web directory (e.g., `firefrostgaming.com/deploy/mods/1.20.1.zip`).
|
||||
|
||||
### 2. Pterodactyl Files API vs. Startup Script
|
||||
|
||||
The Files API is powerful, but for this use case, **Option C (Startup/Install Script) is actually superior**.
|
||||
|
||||
- **Files API:** You can upload a zip, but you then have to send a second API call to "decompress" it. It's more "brittle" because the server has to be in a specific state.
|
||||
- **Startup/Install Script:** If you modify the Pterodactyl Egg, you can add a "General Mod Sync" script to the Installation Script or the Startup Command.
|
||||
|
||||
**The Logic:** On start, the server checks if a `mod_version.txt` matches the remote version. If not, it wipes the mods folder, downloads the new zip, and extracts it.
|
||||
|
||||
**Benefit:** It's self-healing. If a mod file gets corrupted, a restart fixes it.
|
||||
|
||||
### 3. Integration: Trinity Console vs. Separate Tool
|
||||
|
||||
**Keep it in Trinity Console.** Since you already have the "Deploy Arbiter" button, adding a "Sync Server-Side Mods" button creates a single "Source of Truth" UI.
|
||||
|
||||
The button should trigger a script that updates the Pterodactyl environment variable for that server (e.g., `MOD_BUNDLE_VERSION`), then triggers a server restart.
|
||||
|
||||
The server's internal logic (from Question 2) handles the actual heavy lifting during the boot sequence.
|
||||
|
||||
### 4. The Update Workflow
|
||||
|
||||
**"Bundle & Bump" method:**
|
||||
|
||||
1. Holly updates local folder: She updates the 1.20.1 mods/configs on her PC.
|
||||
2. Zip & Upload: She zips it and uploads it to the Command Center storage.
|
||||
3. Version Bump: She updates a `manifest.json` on the Command Center that says `1.20.1: version_1.2`.
|
||||
4. Mass Restart: Via Trinity Console, you trigger a "Restart All 1.20.1 Servers."
|
||||
5. Auto-Update: As each server starts, it sees version 1.2 is available, pulls the zip, and boots up.
|
||||
|
||||
### 5. Concerns with Running Servers
|
||||
|
||||
**Never push to a running Minecraft server.**
|
||||
|
||||
Minecraft locks many file handles, and overwriting a JAR while the JVM is using it can cause a "Grey Screen" crash or segment faults.
|
||||
|
||||
**Safety Protocol:** Your automation should follow this sequence:
|
||||
```
|
||||
Send Power Action (Stop) → Wait for Status: Offline → (Update Files) → Send Power Action (Start)
|
||||
```
|
||||
|
||||
### 6. CurseForge API — Overkill?
|
||||
|
||||
**Verdict: Overkill for now.**
|
||||
|
||||
CurseForge's API (Eternal/Overwolf) requires an API Key and often blocks "Server-Side Only" mods from direct third-party downloads unless the mod author explicitly allows it.
|
||||
|
||||
Since you only have 14 mods, the time Holly spends manually downloading them once per MC version is negligible compared to the time spent deploying them. Let Holly curate the "Master Zip," and let the automation handle the "Multiplication."
|
||||
|
||||
---
|
||||
|
||||
## Proposed Technical Architecture: The "Firefrost Sync"
|
||||
|
||||
### Startup Logic Snippet (for Egg)
|
||||
|
||||
```bash
|
||||
# Example Startup Logic snippet
|
||||
if [ ! -f "current_bundle.txt" ] || [ "$(cat current_bundle.txt)" != "${MOD_BUNDLE_VERSION}" ]; then
|
||||
echo "Updating mod bundle to ${MOD_BUNDLE_VERSION}..."
|
||||
rm -rf mods/*
|
||||
curl -o mods.zip https://firefrostgaming.com/deploy/${MC_VERSION}.zip
|
||||
unzip -o mods.zip
|
||||
echo "${MOD_BUNDLE_VERSION}" > current_bundle.txt
|
||||
fi
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Decision Made
|
||||
|
||||
**Chose Option B (Trinity Console Push)** for now, with intent to revisit Option A (Egg Startup Script) post-launch.
|
||||
|
||||
**Rationale:**
|
||||
- 6 days from soft launch — speed matters
|
||||
- Holly needs relief NOW
|
||||
- We already have Pterodactyl API in Arbiter
|
||||
- Can test on single server before mass deploy
|
||||
- No egg modifications needed
|
||||
|
||||
---
|
||||
|
||||
**Fire + Frost + Foundation = Where Love Builds Legacy** 🔥❄️
|
||||
130
docs/tasks-index/task-104-mod-deployment-automation.md
Normal file
130
docs/tasks-index/task-104-mod-deployment-automation.md
Normal file
@@ -0,0 +1,130 @@
|
||||
---
|
||||
task_number: 104
|
||||
title: Server-Side Mod Deployment Automation
|
||||
status: In Progress
|
||||
priority: P1-High
|
||||
is_blocker: false
|
||||
owner: Holly
|
||||
tags:
|
||||
- automation
|
||||
- pterodactyl
|
||||
- mods
|
||||
estimated_hours: 8
|
||||
---
|
||||
|
||||
# Task #104: Server-Side Mod Deployment Automation
|
||||
|
||||
## Problem
|
||||
|
||||
Every time we deploy a new public modpack, Holly has to manually install and configure 14 server-side mods per server. With 10 servers and ~1 hour per server, that's 10 hours of repetitive file manager work.
|
||||
|
||||
## Solution
|
||||
|
||||
Automate deployment via Trinity Console using Pterodactyl API.
|
||||
|
||||
## Architecture Decision
|
||||
|
||||
**Chosen: Option B — Trinity Console Push (API)**
|
||||
|
||||
Per Gemini consultation (April 9, 2026), we evaluated three approaches:
|
||||
|
||||
| Option | Approach | Verdict |
|
||||
|--------|----------|---------|
|
||||
| A | Egg Startup Script (self-healing pull) | Future — after 50+ servers |
|
||||
| B | Trinity Console Push (API) | **NOW** — fast to build, we control it |
|
||||
| C | Hybrid | Effectively B with intent to revisit A |
|
||||
|
||||
**Why B for now:**
|
||||
- 6 days from soft launch — speed matters
|
||||
- Holly needs relief NOW
|
||||
- We already have Pterodactyl API in Arbiter
|
||||
- Can test on single server before mass deploy
|
||||
- No egg modifications needed
|
||||
|
||||
**Revisit Option A** post-launch when stability > flexibility.
|
||||
|
||||
---
|
||||
|
||||
## Implementation Plan
|
||||
|
||||
### Phase 1: Bundle Creation (Holly)
|
||||
|
||||
Holly creates 3 mod bundles:
|
||||
|
||||
| MC Version | Bundle Contents |
|
||||
|------------|-----------------|
|
||||
| 1.16.5 | 14 mods + configs |
|
||||
| 1.20.1 | 14 mods + configs |
|
||||
| 1.21.1 | 14 mods + configs |
|
||||
|
||||
**Bundle structure:**
|
||||
```
|
||||
1.20.1.zip
|
||||
├── mods/
|
||||
│ ├── mod1.jar
|
||||
│ ├── mod2.jar
|
||||
│ └── ...
|
||||
└── config/
|
||||
├── mod1.toml
|
||||
└── ...
|
||||
```
|
||||
|
||||
**Storage location:** Command Center `/var/www/html/deploy/` or Gitea LFS
|
||||
|
||||
### Phase 2: Trinity Console Integration (Claude/Michael)
|
||||
|
||||
Add to Servers page:
|
||||
1. Display MC version on each server card (from Pterodactyl egg variables)
|
||||
2. "Deploy Server Mods" button per server
|
||||
3. Button workflow:
|
||||
- Stop server (power action)
|
||||
- Wait for offline status
|
||||
- Upload correct bundle via Files API
|
||||
- Extract zip
|
||||
- Start server
|
||||
|
||||
### Phase 3: Mass Deploy
|
||||
|
||||
Add "Deploy Mods to All [version] Servers" button for batch operations.
|
||||
|
||||
---
|
||||
|
||||
## Gemini Consultation Summary
|
||||
|
||||
**Key recommendations:**
|
||||
1. **Storage:** Web-accessible directory on Command Center
|
||||
2. **Never push to running servers** — stop first, then deploy
|
||||
3. **Skip CurseForge API** — overkill for 14 mods, manual download is fine
|
||||
4. **Self-healing (Option A)** is better long-term but invasive now
|
||||
|
||||
**Full consultation:** `docs/consultations/gemini-mod-deployment-automation-2026-04-09.md`
|
||||
|
||||
---
|
||||
|
||||
## Safety Protocol
|
||||
|
||||
```
|
||||
Stop Server → Wait for Offline → Upload Files → Extract → Start Server
|
||||
```
|
||||
|
||||
Never overwrite JARs while JVM is running (causes crashes).
|
||||
|
||||
---
|
||||
|
||||
## Open Questions
|
||||
|
||||
1. Where exactly to store bundles? (Command Center web dir vs Gitea LFS)
|
||||
2. How to detect MC version from Pterodactyl API? (egg variable name)
|
||||
3. Should configs overwrite existing or merge?
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- Holly is working on this with her Catalyst in parallel
|
||||
- Compare approaches and merge best ideas
|
||||
- This is P1 because it directly affects Holly's workload before launch
|
||||
|
||||
---
|
||||
|
||||
**Fire + Frost + Foundation = Where Love Builds Legacy** 🔥❄️
|
||||
Reference in New Issue
Block a user