Addon Manager

Addon Manager A powerful Pterodactyl Panel extension for browsing and installing Minecraft content — modpacks, mods, plugins, datapacks, resource packs and shaders — from Modrinth and CurseForge with a modern, user-friendly interface. Features • Multi-Provider Support – Modrinth works out of the box; CurseForge with an API key • Every Content Type – Modpacks, mods, plugins, data packs, resource packs and shaders • Correct Placement – Each type lands where the server actually reads it (see the table below) • Version-Aware Picking – Loader and Minecraft version dropdowns that only offer combinations published upstream, with recommended dependencies listed for one-shot installs • Side-by-Side Installs – Content files install individually and are named for the version you picked, so several builds coexist • Safe Removal – Uninstalling deletes the recorded file only, never the whole mods/ (or plugins/, …) directory • Advanced Filtering – Search by game version, loader, category and provider, in a grid or list view • Live Downloads – Per-file progress with stage reporting (download → unarchive → manifest → fetch → deploy) and a cancel button per install • Server Management – Installed tab with integrity checks, plus update, restore and uninstall • Version-Picked Updates – Updating opens the project's version list, so upgrading, downgrading or reinstalling a specific build runs through the same live progress and stage reporting an install does • Clear Notifications – Outcomes appear as dismissible popups at the top of the dashboard that close themselves after ten seconds, and they name the actual content type (Unable to update the mod, never "modpack") • Secure – API keys stored server-side, never exposed to the client Where each content type lands | Type | Destination inside the server | | ---- | ----------------------------- | | Modpack | server root — files, overrides and its mods/ come from the manifest | | Mod | mods/ | | Plugin | plugins/ | | Data pack | world/datapacks/ | | Resource pack | resourcepacks/ | | Shader | shaderpacks/ | Downloaded files are renamed from your selections (e.g. example-mod-fabric-1-20-1.jar), so every installed file is self-describing. Requirements • Pterodactyl Panel v1.8+ • Blueprint (Pterodactyl extension framework) • PHP 8.1+ • Node.js 18+ (used by Blueprint to compile frontend assets during install) Installation > You need sudo (root) access on the server running your Pterodactyl panel. > > Full details are in INSTALLATION.md. Quick start (recommended) Clone this repository into your Pterodactyl directory, install the mi developer CLI, and run the installer: mi install (the former installer.sh) automatically: • installs missing system tools and the PHP curl/zip extensions, • raises your PHP-FPM limits so large modpacks (400 MB+) don't time out mid-download, • installs Blueprint if you don't have it yet, • installs this extension with blueprint -install and publishes the panel assets. Uninstalling mi remove deletes everything mi install / mi build published — the installed extension, its admin pages, routes, styles, published assets and the panel's rebuilt bundle — so a later install starts from a clean panel. It is not an uninstaller for your setup: system packages, PHP extensions, Blueprint, the checked-out repo and the global mi command all stay exactly where they are. Mods, plugins and packs already placed on a game server stay, and so does the extension's own bookkeeping (the install records in /var/lib/pterodactyl/modpack-installer, outside the panel) — rebuild and your Installed list is back. A developer's clone under .blueprint/dev is kept unless you ask for it, since deleting a working tree unasked would be destructive — mi remove tells you when one is still there, and sudo mi remove --dev-tree drops it: Rebuild any time with sudo mi install (or mi build from a checkout). Development The repo ships mi, a small developer CLI covering the whole workflow: Flags accepted everywhere: --help, --quiet / -q, --json, --no-color (or NOCOLOR=1), and --dry-run / -n on build, release and db:reset. The ones you reach for most: mi check is exactly what the pre-push hook runs (mi hooks install) and what CI runs — so a passing local check means a passing pipeline. The same hook can version a push from its commit messages (feat: minor, fix: patch, chore: major); mi hooks shows both toggles, mi hooks checks off / mi hooks bump off turn them off. Which deploy command you use depends on why you cloned the repo: • You just want to install the extension — clone into /var/www/pterodactyl and run mi install (see Installation above). No Blueprint developer mode required. • You are developing the extension — turn on Blueprint's developer mode once (Admin → Extensions → Blueprint → set developer to true), clear and clone the repo into /var/www/pterodactyl/.blueprint/dev, then mi build (regenerates css, syncs the install-time files and runs blueprint -build) or mi watch to rebuild on every change. Only this layout needs developer mode. • Any other checkout (e.g. /home/you/addon-manager) — mi build deploys via the rsync pipeline (tools/build.sh) into the panel at /var/www/pterodactyl. root.css is generated from components/styles/.css — edit the modular files, never root.css. mi css or any mi build regenerates it. Optional: CurseForge API key Modrinth works out of the box. To enable CurseForge, set CURSEFORGEAPIKEY in your panel's .env, then run php artisan config:cache and restart PHP-FPM — details in INSTALLATION.md. Usage For Panel Administrators 1. Log in to your Pterodactyl Panel 2. Navigate to Admin Panel → Extensions → Addon Manager 3. Configure optional settings (if needed) For Server Owners 1. Go to your server dashboard 2. Click the Addon Manager tab 3. Browse content from Modrinth or CurseForge 4. Filter by game version, loader, and category 5. Pick a version, choose any recommended dependencies, and click Install 6. Manage installed content from the Installed tab Configuration Environment Variables | Variable | Required | Description | | ----------------------------------- | -------- | ----------------------------------------------------------------------------------- | | CURSEFORGEAPIKEY | No | Your CurseForge API key for catalog access | | MODPACKINSTALLERSERVERTARGET | No | Server target mode: local (default) or wings | | MODPACKINSTALLERSERVERROOT | No | Custom server root path (defaults to /var/lib/pterodactyl/volumes) | | MODPACKINSTALLERMAXDOWNLOADMB | No | Max download size in MB (no limit by default) | | MODPACKINSTALLERDATADIR | No | Install records storage path (defaults to /var/lib/pterodactyl/modpack-installer) | Contributing See CONTRIBUTING.md for setup, the commit convention (it drives the version number), and the PR checklist. Run mi check (lint + all test suites) before pushing — CI runs the same. Security issues: SECURITY.md — please report privately. Architecture • Backend – PHP service layer with modular provider architecture • Frontend – React + TypeScript with responsive Tailwind-based styling • Providers – Pluggable provider system for Modrinth and CurseForge APIs • Storage – Server-side file management with backup capabilities Supported Loaders Mods and modpacks publish a loader, so their version window offers only the combinations that exist upstream: Fabric, Forge, Quilt, NeoForge, LiteLoader, Cauldron, Rift (CurseForge's set) plus whatever Modrinth lists for a project. Shaders publish a shader loader instead — Iris, OptiFine — which both providers record, so shader windows let you pick the loader the pack was built for and the installed file keeps it in its name. CurseForge does not record which ser