firefrost-gaming/firefrost-services
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
af297f2cdafd1431ea6e83ac440ebcdb265587e6
firefrost-services/docs/code-bridge/requests/REQ-2026-04-16-modpack-installer.md

8.9 KiB
Raw Blame History

REQ-2026-04-16-modpack-installer

From: Chronicler #93
Date: 2026-04-16
Priority: HIGH — Michael wants this done tonight
Status: PENDING
Linked Task: #101 — AI-Powered Modpack Server Installer
Architecture: Fully locked via 4-round Gemini consultation
Consultation docs:

  • firefrost-operations-manual/docs/consultations/gemini-modpack-installer-trinity-console-2026-04-15.md
  • firefrost-operations-manual/docs/consultations/gemini-modpack-installer-followup-2026-04-15.md
  • firefrost-operations-manual/docs/holly-review-modpack-installer.md

What This Is

A full modpack installer integrated into Trinity Console. Holly reviewed and approved the full feature set. Bitch Bot (the first-boot provisioning mod) is already built and compiled — this is the Arbiter/Trinity Console side that drives everything.

Database Migrations

Migration 143 — server_config updates

ALTER TABLE server_config
ADD COLUMN modpack_provider VARCHAR(50),
ADD COLUMN modpack_id VARCHAR(100),
ADD COLUMN current_version_id VARCHAR(100),
ADD COLUMN is_version_locked BOOLEAN DEFAULT FALSE,
ADD COLUMN locked_version_id VARCHAR(100) DEFAULT NULL,
ADD COLUMN lock_reason TEXT DEFAULT NULL,
ADD COLUMN spawn_verified BOOLEAN DEFAULT FALSE,
ADD COLUMN ram_allocation_mb INT NOT NULL DEFAULT 8192,
ADD COLUMN ram_ceiling_mb INT NOT NULL DEFAULT 16384,
ADD COLUMN hibernation_status VARCHAR(50) DEFAULT 'active';

Migration 144 — install_history table

CREATE TABLE install_history (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    server_id UUID REFERENCES server_config(id) ON DELETE CASCADE,
    pterodactyl_server_id VARCHAR(100),
    job_type VARCHAR(50) NOT NULL,
    target_version_id VARCHAR(100) NOT NULL,
    triggered_by VARCHAR(100) NOT NULL,
    status VARCHAR(50) NOT NULL,
    started_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    completed_at TIMESTAMP WITH TIME ZONE,
    duration_seconds INT,
    mods_injected INT DEFAULT 0,
    log_output JSONB DEFAULT '{}'
);

CREATE INDEX idx_install_history_recent_failures
ON install_history(server_id, status, started_at);

Job Queue (pg-boss)

Add pg-boss as a dependency. Three queues:

  • modpack-installs — concurrency 2 (heavy file I/O)
  • maintenance-tasks — concurrency 5 (ghost updates, hibernation)
  • fast-sync — concurrency 20 (LuckPerms pings, Discord alerts)

Worker Execution Flow (modpack-installs)

  1. Job picked up → install_history status = running
  2. Pre-flight: check node RAM/disk headroom, map Java version → correct egg. Refuse with clear error if insufficient headroom.
  3. Pterodactyl server provisioned
  4. Download pack mods via provider API. Scrub client-only mods (cross-reference serverPackFileId for CurseForge; skip 403s silently).
  5. Inject Firefrost Standard Mod Stack from NextCloud (standard-mods/{mc_version}/)
  6. Drop provision.json + BitchBot-1.0.0-neoforge-1.21.1.jar into server mods folder (skip if spawn_type = skyblock or has_lobby)
  7. Stream everything to Pterodactyl via Wings SFTP
  8. Create Cloudflare A + SRV records
  9. Create Discord category + 5 channels (chat, in-game, forum, voice, status)
  10. Add to status poller
  11. Seed server_config record
  12. Power on server → set spawn_verified = false → post staff Discord ping → install_history = success

Trinity Console Pages

GET /admin/modpack-installer

Main installer page. Sections:

Provider Selection — 6 providers with logos: CurseForge, Modrinth, FTB, ATLauncher, Technic, VoidsWrath

Pack Browser (after provider selected):

  • Search box
  • Filters: category (Magic, Tech, Quests, Sci-Fi, Skyblock, Horror), mod loader (Forge, Fabric, NeoForge), MC version
  • Pack cards: name, thumbnail, mod count, mod loader, MC version, short description

Pack Details + Version Selection (after pack selected):

  • Full description, screenshots if available
  • Version dropdown (default: latest)
  • Resource estimates: recommended RAM, disk based on mod count/pack size
  • Smart node recommendation: query existing servers' RAM usage, recommend best node

Install Form:

  • Short name / subdomain (auto-suggested from pack name, slugified) — becomes Discord prefix + Cloudflare subdomain + DB short_name
  • Display name
  • Node selector (TX1 Dallas / NC1 Charlotte) — pre-filled from recommendation, overridable
  • RAM allocation (pre-filled from estimate, adjustable)
  • Spawn type: Standard / Skyblock / Has Lobby
  • Confirm button → enqueues job → redirects to install status page

GET /admin/modpack-installer/status/:job_id

Live install progress page. Shows:

  • Current step (streaming via SSE or polling)
  • Log output
  • Success/failure state
  • Link to server card on completion

GET /admin/modpack-installer/history

Install history table. Columns: server, job type, version, triggered by, status, duration, started at. Filterable by status and server.

GET /admin/modpack-installer/pending-spawns

Holly's queue. Lists all servers where spawn_verified = false. Each row: server name, installed date, "Mark Verified" button. This is Holly's only job after an install — log in, confirm spawn looks right, click verified.

Pre-Flight Mod Loader Check

During step 2 of the worker flow, after downloading mods:

  • Crack open each mod jar
  • Read META-INF/mods.toml (NeoForge/Forge) or fabric.mod.json (Fabric)
  • Verify loader matches the selected egg
  • Log mismatches as warnings, don't hard-fail (some jars are multi-loader)
  • If >20% of mods are wrong-loader, hard-fail with clear error before touching Pterodactyl

provision.json Structure (Bitch Bot input)

Arbiter generates and drops this into the server root during step 6:

{
  "version": "1.0",
  "schematic_name": "firefrost-spawn-v1.schem",
  "schematic_url": "https://downloads.firefrostgaming.com/Firefrost-Schematics/firefrost-spawn-v1.schem",
  "schematic_hash": "REAL_SHA256_GOES_HERE",
  "spawn_type": "standard",
  "spawn_coords": { "x": -5000, "y": 64, "z": -5000 },
  "paste_origin": "center",
  "worldspawn_offset": { "x": 0, "y": 1, "z": 0 },
  "command_blocks": [
    { "position": { "x": -4998, "y": 65, "z": -4998 }, "facing": "up" },
    { "position": { "x": -5002, "y": 65, "z": -4998 }, "facing": "up" },
    { "position": { "x": -4998, "y": 65, "z": -5002 }, "facing": "up" },
    { "position": { "x": -5002, "y": 65, "z": -5002 }, "facing": "up" }
  ],
  "rules_signs": [
    {
      "position": { "x": -4999, "y": 65, "z": -5005 },
      "lines": ["Welcome to", "Firefrost!", "Read /rules", "Have fun!"]
    }
  ],
  "yawp_region": {
    "name": "spawn",
    "min": { "x": -5050, "y": 0, "z": -5050 },
    "max": { "x": -4950, "y": 255, "z": -4950 },
    "flags": ["no-pvp", "no-mob-spawning", "break-blocks", "place-blocks"]
  },
  "self_destruct_on_success": true
}

Note: schematic_hash is a placeholder until Holly exports the real schematic. The installer should store this in .env or a config table so it can be updated without a code change.

.env additions

CURSEFORGE_API_KEY=your_key_here
WIKIJS_API_KEY=your_key_here
BITCH_BOT_SCHEMATIC_HASH=placeholder_until_holly_exports
BITCH_BOT_SCHEMATIC_URL=https://downloads.firefrostgaming.com/Firefrost-Schematics/firefrost-spawn-v1.schem

Files to Create/Modify

New:

  • migrations/143_server_config_modpack.sql
  • migrations/144_install_history.sql
  • src/services/modpackInstaller.js — job worker, provider API clients, install orchestration
  • src/services/providerApi/curseforge.js — CurseForge API client
  • src/services/providerApi/modrinth.js — Modrinth API client
  • src/services/providerApi/ftb.js — FTB API client (stub ATLauncher/Technic/VoidsWrath for now)
  • src/routes/admin/modpack-installer.js — all installer routes
  • src/views/admin/modpack-installer/index.ejs
  • src/views/admin/modpack-installer/status.ejs
  • src/views/admin/modpack-installer/history.ejs
  • src/views/admin/modpack-installer/pending-spawns.ejs

Modify:

  • src/index.js — register pg-boss, mount installer routes
  • src/views/layout.ejs — sidebar link to installer + pending spawns badge
  • package.json — add pg-boss

Scope Notes

In scope for tonight:

  • Full installer flow (CurseForge + Modrinth primary, FTB stub)
  • DB migrations
  • pg-boss queue
  • Pre-flight mod loader check
  • Holly's pending spawns queue
  • Install history

Defer to follow-up tasks:

  • Ghost updates (zero-downtime staging)
  • Hibernation/wake-up system
  • Dynamic RAM scaling
  • Crash loop sentinel
  • Cursed Modpack Roulette
  • Clone to dev
  • AI patch notes
  • Auto-tier syncing (Redis/LuckPerms messaging)

These are all in the Gemini consultation and have approved architecture. They become separate tasks after #101 ships.

Deploy Steps (after build)

Standard Arbiter deployment pattern:

  1. Run migrations 143 + 144 on Command Center
  2. npm install (picks up pg-boss)
  3. Copy files to /opt/arbiter-3.0
  4. Restart arbiter-3
  5. Verify sidebar link appears
  6. Test with a real CurseForge pack ID
Reference in New Issue View Git Blame Copy Permalink