repository·main·Indexed 19 days ago
https://github.com/blueprintframework/frameworkAn open-source extension framework and manager for Pterodactyl that allows developers to create modular extensions and administrators to install them without manual code changes. It includes a Bash-based CLI for management, a PHP/Laravel backend, and a frontend extended via React, TypeScript, and Blade. The framework provides a dedicated UI library (@blueprint/ui) with components like UiBadge, UiAlert, and UiDivider to ensure visual consistency with the Pterodactyl panel.
Blueprint UI provides a library of versatile, themeable components designed to match the look and feel of Pterodactyl's native UI. Extensions can consume these components using the @blueprint/ui package. Components are designed to be feature-rich counterparts to Pterodactyl's own components, ensuring visual consistency while providing enhanced functionality.
import { UiBadge } from '@blueprint/ui';Blueprint works by applying a 'Blueprint patch' onto a Pterodactyl panel. Instead of traditional standalone addons that overwrite files, Blueprint enables a modular system where the panel is extended through 'extensions'.
The framework components consist of:
Blueprint is an extension framework for Pterodactyl that allows system administrators to install versatile extensions quickly without manual code modifications.
To install Blueprint, refer to the official installation guide.
When developing or installing Blueprint extensions, the installation script enforces several security and structural constraints to ensure system stability:
.., /.., or starting with / are rejected..tsx, .ts, .jsx, or .js).server or account type.UTF-8 encoding. If the system locale is not UTF-8, the installation may proceed with limited support or fail during route generation../ or ../ in a way that violates the import rules.If an extension includes a custom removal script located at .blueprint/extensions/<identifier>/private/remove.sh, the Blueprint removal command will execute it before proceeding with the standard cleanup.
When a custom script is detected, the following environment variables are passed to the script's execution context:
ENGINE: The Blueprint engine being used.EXTENSION_IDENTIFIER: The unique identifier of the extension.EXTENSION_TARGET: The target of the extension.EXTENSION_VERSION: The version of the extension.PTERODACTYL_DIRECTORY: The root directory of the Pterodactyl installation.BLUEPRINT_VERSION: The version of Blueprint.Warning: Use custom removal scripts with caution as they run with the permissions of the web user.
If an extension provides a data.console directory, it can define Artisan commands and schedules using a Console.yml file. The installer automatically generates the necessary PHP command classes and schedule entries.
For each command defined in the Console.yml hierarchy, the following fields are used:
Signature: The Artisan command signature (e.g., extension:my-command).Description: The command description.Path: The relative path to the logic file (must end in .php).Interval: (Optional) The scheduling frequency.If an interval is provided, the installer maps it to the following Blueprint/Laravel schedule methods:
everyMinute, everyTwoMinutes, everyThreeMinutes, everyFourMinutes, everyFiveMinutes, everyTenMinutes, everyFifteenMinutes, everyThirtyMinutes.hourly, daily, weekly, monthly, quarterly, yearly.weekdays, weekends, sundays, mondays, tuesdays, wednesdays, thursdays, fridays, saturdays.cron('0 * * * *')).Blueprint automatically registers client-side API routes by scanning the routes/blueprint/client/ directory. Each .php file in that directory defines a group of routes prefixed with the filename (excluding the extension).
For example, a file named api.php in that directory will result in all routes defined within it being prefixed with /api.
Blueprint extensions are organized into specific directories within the .blueprint/extensions/<identifier>/ folder. The installation process automatically creates symbolic links to integrate these into the main application:
public/: Contains public assets. Linked to public/extensions/<identifier>.assets/: Contains extension assets (like icons and CSS). Icons are linked to public/assets/extensions/<identifier>/icon.<ext>. CSS is linked to public/assets/extensions/<identifier>/admin.style.css or resources/scripts/blueprint/css/extensions.css.private/: Contains sensitive data and configuration. Includes a .store/ directory for backups of conf.yml, Components.yml, and Console.yml.fs/: The extension filesystem. Linked to storage/extensions/<identifier> and public/fs/<identifier>.wrappers/: Contains Blade templates for dashboard or admin wrappers, linked to resources/views/blueprint/dashboard/wrappers/<identifier>.blade.php or resources/views/blueprint/admin/wrappers/<identifier>.blade.php.The watch.sh script is a developer utility designed to monitor the .blueprint/dev directory for changes. When changes are detected (via inotifywait), it triggers a rebuild of the extension using the blueprint -add "[developer-build]" command.
Prerequisites & Behavior:
is_developer)..blueprint/dev/conf.yml file to exist in the extension directory.view, config, route, cache) and the Blueprint cache (bp:cache).conf_dashboard_components or conf_dashboard_css are defined in your configuration, the script starts yarn watch in the background to monitor frontend assets.yarn processes and resetting .prettierignore.# To use this script, run it from your terminal within the project context
./scripts/commands/developer/watch.shThe init.sh script is a developer-mode command used to scaffold a new extension from a template into the .blueprint/dev directory.
Prerequisites:
.blueprint/dev directory must be empty (excluding .gitkeep) before running the command. If files exist in .blueprint/dev, the command will fail with a fatal error.Workflow: When running the command, you will be prompted to provide the following metadata, which is used to populate the extension's configuration files:
info.name): The display name of your extension.info.identifier): A unique, lowercase-only string (a-z) used to identify the extension.info.description): A brief summary of what the extension does.info.version): The initial version of your extension (e.g., 1.0).info.author): The name of the extension author.Post-Initialization:
.blueprint/dev..dist directory is created in .blueprint/dev containing symlinks to core types.node scripts/helpers/generate-types.js..blueprint/tmp upon completion.The Blueprint installation script allows you to install extensions by providing the path to the extension bundle. It supports both standard installations and developer builds.
[developer-build] flag to install an extension from a local development directory (typically .blueprint/dev).For an installation to succeed, the extension bundle must contain a valid .blueprint/conf.yml file. The installer validates several criteria:
info.name, info.identifier, info.description, info.version, info.target, and admin.view must be defined.info.identifier must be lowercase, contain only a-z characters, and cannot be blueprint or exceed 48 characters.[name], [identifier], or [ver] in their configuration.conf.yml must be relative and cannot attempt to escape the extension bundle (e.g., using .. or absolute paths).# Standard installation
./blueprint install /path/to/extension
# Developer build installation
./blueprint install [developer-build]After extensions are installed, the Blueprint installation process performs several cleanup and finalization steps to ensure the Pterodactyl panel is correctly updated.
Depending on your configuration, the following actions may occur:
YARN is enabled and IgnoreRebuild is not set to true, the panel assets are rebuilt using yarn run build:production --progress.php artisan storage:link to ensure storage is accessible.KeepApplicationCache is true) and runs php artisan bp:cache and php artisan queue:restart.$OWNERSHIP value, excluding node_modules.dbmigrations is set to true and you are not running in a Docker environment, php artisan migrate --force is executed.