Panel Laravel Package

Getting Started

Pterodactyl is a Laravel application (not a typical drop-in package) that manages game servers through a companion daemon, Wings. You leverage it by extending the panel, automating it through its two REST APIs, or authoring "eggs" that define how servers are provisioned.

Minimal setup:

1. Clone/install alongside your Laravel toolchain: composer install, copy .env.example to .env, php artisan key:generate, then php artisan p:environment:setup and p:environment:mail.
2. Run php artisan migrate --seed (the seeders populate nests and core eggs), then php artisan p:user:make to create your first admin.
3. Run a queue worker (php artisan queue:work) and the scheduler — server creation, installs, and deletions are all queued jobs, so nothing works without them.
4. Install Wings on the node host and create a node + allocation in the admin UI before any server can be created.
5. Patch PHP first. The v1.15.2 security release (php2shell, CVE-2026-109618 / CVE-2026-109619) requires PHP 8.2.35 or 8.3.36 minimum. Upgrade the whole PHP package set together — sudo apt update && sudo apt install --only-upgrade 'php8.*' — rather than bumping a single extension.

Where to look first:

• app/Services/ — the real business logic (server creation, environment, installations). Controllers are thin; extend here.
• app/Models/ and app/Contracts/Repository/ — Eloquent models with a repository layer behind them.
• app/Http/Controllers/Api/Client and .../Api/Application — the two API surfaces you'll integrate against.
• database/Seeders/ — canonical examples of nest/egg structure.
• resources/scripts/ — the React frontend, if you need to touch the UI.

First use case: generate an Application API key, then script a full onboarding flow — create user → create server → poll until install completes. This is the highest-leverage thing most developers do with the panel.

Implementation Patterns

Egg authoring and distribution. Eggs are JSON documents describing Docker images, startup command, config files to parse, variables, and an install script. In this beta, exporting an egg from the admin area downloads a ready-to-reimport .json file, so a practical workflow is: build a server manually, tune it, export the egg, commit it to your repo, and import it into staging/production via the admin UI or the Application API. Treat exported eggs as versioned artifacts.

API-first automation. Use the Application API (/api/application) for admin operations (users, nodes, servers, nests, eggs) and the Client API (/api/client) for per-server actions (power, files, backups, schedules, websockets). Store keys per-environment; the Application API key is effectively root for the panel.

Service-layer extension. Rather than editing controllers, wrap or extend the services in app/Services/. For example, hook ServerCreationService or listen to the model/job events it fires to enforce naming conventions, auto-assign allocations, or sync to an external billing system.

Event-driven integrations. The panel dispatches Eloquent and domain events for server lifecycle, user creation, and backups. Register listeners in a small service provider and push to your own queue — do not do synchronous HTTP inside the panel's request cycle.

Frontend customization. Themes/skins live in resources/scripts (React) and Blade views in resources/views. Keep custom Blade in your own namespace and prefer overriding published views over editing vendor assets.

Deployment. Pin the Docker tag (ghcr.io/pterodactyl/panel:v2.0.0-beta.2 for the beta line, or the matching v1.15.2 tag if you are still on 1.x) rather than tracking latest, and keep Wings and panel versions aligned — mismatched panel/daemon pairs are a common source of confusing failures.

Custom images must mirror the hardened PHP config. The official image now ships PHP 8.3.36 and disables session.upload_progress in php-fpm as part of the php2shell mitigation. If you build your own panel image (common for agencies with a baked-in theme), replicate that ini change and pin the PHP base image, otherwise you silently reintroduce the vulnerability while believing you patched it.

Gotchas and Tips

• This is a 2.0 beta. Do not run it as your first production panel. The release notes explicitly direct 1.x users to test the upgrade on a copy first; the 1.x → 2.0 migration is not a routine composer update.
• Two live branches, two patch paths. v1.15.2 is a 1.x security release; the assessment above targets 2.0.0-beta.2. Do not assume pulling the beta gets you the 1.x fixes, or vice versa. Inventory which branch each environment runs before applying anything, and prefer composer/image pulls over cherry-picking, since beta upgrades should stay mechanical.
• PHP version is now a hard floor. Anything below 8.2.35 / 8.3.36 is vulnerable to php2shell. Audit the PHP version on every host — panel web nodes, queue workers, and scheduler containers are often provisioned separately and drift. Upgrade all php8.* packages in one transaction; a partial upgrade can leave mismatched extensions that fail confusingly at boot.
• session.upload_progress is disabled on purpose. If you have bespoke upload flows relying on $_SESSION upload progress keys, they will stop working on the patched image. Use the panel's own file-upload endpoints or client-side progress instead of re-enabling the directive.
• Export/import round-trip. The fix in the beta line makes an exported egg directly re-importable. If you maintain eggs in git, re-export after upgrading — eggs exported on earlier betas may carry the malformed shape that release corrects, and importing them back can fail or silently drop variables.
• Queues are mandatory. A "stuck" server creation is almost always a dead queue worker or a failed Queue\Jobs entry. Check php artisan queue:failed before touching the database. Note that a PHP upgrade implies restarting workers — php artisan queue:restart — or they keep running the old, unpatched interpreter.
• Allocations before servers. Creating a server via API without a free allocation on the target node returns a validation error that reads like a server-side fault. Provision allocations first.
• Config caching. After changing .env (especially APP_URL, SESSION_DRIVER, or mail settings) run php artisan optimize:clear. A cached config is the cause of most "my changes did nothing" reports.
• Eggs are nest-scoped. Importing into the wrong nest makes the egg invisible where you expect it. Verify the nest ID in the payload, not just the UI context.
• Permissions are a separate system from Laravel policies. Subusers get granular per-server permissions defined in the panel's own schema; don't assume Gate/Policy covers API authorization for client routes.
• Rate limits and pagination. The APIs paginate by default; naive integrations that read only the first page silently miss resources. Respect the X-RateLimit-* headers if you sync on a schedule.
• Stay out of vendor/. Register extension points in your own service provider so beta upgrades remain composer/image pulls rather than manual patch reapplications.
• Debugging. APP_DEBUG=true plus storage/logs/laravel.log covers the panel; daemon-side problems surface in Wings logs on the node, so check both before assuming a panel bug. After a security patch, verify the running PHP version (php -v and php-fpm -v) rather than trusting the package manager's report.