diff --git a/docs/consultations/catalyst/gemini-server-mod-automation-2026-04-09.md b/docs/consultations/catalyst/gemini-server-mod-automation-2026-04-09.md new file mode 100644 index 0000000..359ac8a --- /dev/null +++ b/docs/consultations/catalyst/gemini-server-mod-automation-2026-04-09.md @@ -0,0 +1,212 @@ +# Gemini Consultation: Trinity Console Server-Side Mod Automation Module + +**Date:** April 9, 2026 +**From:** Holly (The Catalyst) + Claude (Catalyst #2) +**To:** Gemini (Architectural Partner) +**Re:** Automating server-side mod installation and configuration + +--- + +## Hey Gemini! 👋 + +Holly here with a workflow pain point that's begging for automation. Every time we add a new Minecraft server to the fleet (and we have 13+ running), we manually install and configure the same server-side mods on each one. It's tedious, error-prone, and takes Holly away from creative building work. + +We're thinking about adding a module to Trinity Console (Arbiter 3.0) to automate this. Before we dive in, we'd love your architectural guidance. + +--- + +## Current Workflow (Manual) + +**When deploying a new modded Minecraft server:** + +1. Create server in Pterodactyl Panel +2. Upload modpack +3. **Manually upload server-side mods** (same set every time) +4. **Manually configure each mod** (config files, permissions) +5. Set up LuckPerms +6. Configure Discord integration +7. Test and launch + +**Steps 3-4 are repetitive and identical across servers.** + +--- + +## What We Want to Automate + +**Common server-side mods we install on every server:** +- LuckPerms (permission management) +- EssentialsX (commands, warps, homes) +- Vault (economy/permission bridge) +- WorldEdit (building tools for Holly) +- CoreProtect (rollback/logging) +- DiscordSRV (Discord integration) +- TAB (player list formatting) +- Chunky (pre-generation) +- [Plus modpack-specific mods] + +**Each mod has:** +- JAR file (downloaded from CurseForge, Modrinth, or SpigotMC) +- Configuration files (YAML, JSON, or properties) +- Some need initial setup (database connections, API keys) + +--- + +## Proposed Architecture + +### Trinity Console Module: "Server Template Manager" + +**User Flow:** +1. Holly logs into Trinity Console +2. Goes to "Server Templates" module +3. Selects a template (e.g., "Standard Survival", "Creative Build", "Pokerole RPG") +4. Template contains: + - List of mods with versions + - Pre-configured config files + - LuckPerms groups/permissions export + - Discord webhook settings +5. Clicks "Deploy to Server" → selects Pterodactyl server +6. Trinity Console: + - Downloads mods via Pterodactyl API (file upload) + - Uploads config files to /config/ + - Restarts server + - Validates installation + +**Template Structure (JSON/YAML):** +```yaml +name: "Standard Survival" +description: "Base survival server with essentials" +minecraft_version: "1.20.1" +server_type: "paper" # or fabric, forge + +mods: + - name: "LuckPerms" + source: "spigot" + file_id: "12345" + version: "5.4.102" + config_files: + - path: "plugins/LuckPerms/config.yml" + template: "luckperms-standard.yml" + + - name: "EssentialsX" + source: "spigot" + file_id: "67890" + version: "2.20.1" + config_files: + - path: "plugins/Essentials/config.yml" + template: "essentialsx-standard.yml" + +luckperms_export: "luckperms-groups-standard.json" +discord_webhook: "${DISCORD_WEBHOOK_URL}" +``` + +**Backend:** +- Store templates in PostgreSQL (`server_templates` table) +- Config templates stored as text blobs or file references +- Integration with Pterodactyl API for file uploads +- Queue-based deployment (so long operations don't block UI) + +--- + +## Technical Challenges We're Considering + +### 1. Mod Downloads +**Challenge:** How do we get the mod files? + +**Options:** +- **A)** Holly manually uploads JARs to Trinity Console first (template includes upload reference) +- **B)** Integrate with CurseForge/Modrinth APIs (auto-download by file ID) +- **C)** Store mods in S3/CDN, templates reference URLs + +**Our instinct:** Option A (manual upload) for MVP, Option B later when we scale + +### 2. Config File Templating +**Challenge:** Some configs need server-specific values (server IP, database credentials) + +**Options:** +- **A)** Simple string replacement (`${SERVER_NAME}`, `${DATABASE_URL}`) +- **B)** Full templating engine (Handlebars, EJS) +- **C)** Interactive form before deployment (Holly fills in per-server values) + +**Our instinct:** Option A for simple cases, Option C for complex setup + +### 3. Pterodactyl API Integration +**Challenge:** Uploading files via API vs SFTP + +**Pterodactyl Client API supports:** +- File upload (POST to `/api/client/servers/{server}/files/write`) +- File deletion +- Directory creation +- Server restart + +**Our instinct:** Use Pterodactyl API for everything (already have credentials in Arbiter) + +### 4. Error Handling +**Challenge:** What if mod upload fails mid-deployment? + +**Options:** +- **A)** Transaction-style rollback (delete uploaded files, restore backup) +- **B)** Pause deployment, notify Holly, allow manual resume +- **C)** Best-effort only, Holly fixes manually + +**Our instinct:** Option B (pause + notify) + +### 5. Version Management +**Challenge:** Mod updates break servers + +**Options:** +- **A)** Lock templates to specific mod versions +- **B)** Allow "latest" but track what's deployed +- **C)** Show version diff before deploying template update + +**Our instinct:** Option A for stability + +--- + +## Specific Questions for You + +1. **Architecture:** Does our template-based approach make sense, or is there a better pattern for "deploy identical configs to multiple servers"? + +2. **Pterodactyl Integration:** Any gotchas with programmatic file uploads to Minecraft servers via their API? Should we worry about file permissions, ownership, or timing issues? + +3. **Template Storage:** JSON in database vs files in repo vs hybrid? We're leaning toward database for easy UI editing. + +4. **Deployment Queue:** Should we use a job queue (Bull/BullMQ) for async deployment, or is a simple "polling status" approach sufficient for 1-2 servers at a time? + +5. **Config Templating:** Is simple `${VARIABLE}` replacement enough, or will we regret not using a real templating engine when configs get complex? + +6. **Error Recovery:** What's the right balance between automation and "let Holly fix it manually"? We want to save her time, not create a debugging nightmare. + +7. **MVP Scope:** If we build this in phases, what's the minimum viable feature set that delivers real value? (Our guess: upload template + deploy to one server with pre-uploaded JARs) + +--- + +## Context + +**Trinity Console Details:** +- Already built (95% complete, security hardening in progress) +- Tech stack: Node.js + Express, PostgreSQL, htmx + Tailwind +- Has Pterodactyl Panel API integration (file reading) +- Philosophy: Low-bandwidth friendly, RV-optimized, no complex build pipelines + +**Firefrost Server Fleet:** +- 13+ active Minecraft servers across 2 nodes (TX1 Dallas, NC1 Charlotte) +- Mix of modded (Fabric/Forge) and plugin-based (Paper/Spigot) +- Managed via Pterodactyl Panel +- New servers deployed frequently (testing modpacks, seasonal servers) + +**Holly's Workflow:** +- Non-technical but very capable with guided UIs +- Prefers "click button, it works" over "SSH and run commands" +- Spends time building, not configuring +- Values consistency (same mods = same experience across servers) + +**Our Goal:** +Reduce new server deployment from 2-3 hours to 15-30 minutes, with Holly clicking buttons in Trinity Console instead of manually uploading files via SFTP. + +--- + +Thanks Gemini! Your architectural insight would be incredibly valuable here. We trust your judgment on what's worth building vs what's premature optimization. + +🔥❄️ + +— Holly + Claude (Catalyst #2)