Easypanel Nixpacks Deploy

My Easypanel Nixpacks Deploy

Helps check, configure, and adapt existing PHP web projects so they can be deployed on an Easypanel server via the Nixpacks builder.

Goal

A PHP project should be buildable and runnable on Easypanel without its own Dockerfile. The skill makes sure that Nixpacks detects the project correctly, installs dependencies, uses the right webroot, builds optional frontend assets, and clearly documents the required Easypanel environment variables.

Input

The skill requires an existing PHP web project or a concrete project path.

• When invoked with a project path, work in that project.
• When invoked without a project path, use the current working directory if a PHP project is detectable there.
• If no PHP project is detectable, ask for the correct project path.
• If the user provides a concrete error message from Easypanel or Nixpacks, analyze it first.

Prerequisites

• Before making changes, read the existing project structure and relevant deployment files.
• For concrete deployment work, load the reference references/php-nixpacks-easypanel.md.
• Prefer Nixpacks-native configuration over a Dockerfile, as long as the project can be deployed sensibly that way.
• Do not overwrite existing files such as nixpacks.toml, nginx.conf, Procfile, or .env.example without reading them first and preserving existing intent.
• Never change secrets directly in files. Document required values as Easypanel environment variables.

Steps

1. Detect the project

   • Check composer.json, composer.lock, index.php, public/, framework markers, .env.example, package.json, and lockfiles.
   • Determine whether it is generic PHP, Laravel, Symfony, or another PHP framework.
   • Detect whether a frontend build via npm, pnpm, or yarn is needed.

2. Read the existing deployment

   • Check nixpacks.toml, nixpacks.json, Procfile, nginx.conf, nginx.template.conf, Dockerfile, and project documentation.
   • Keep working existing deployment decisions.
   • Only remove or ignore competing configuration if it concretely disrupts the Nixpacks/Easypanel build.

3. Check PHP and Composer configuration

   • Make sure composer.json describes the required PHP version and PHP extensions.
   • Add missing extensions as Composer platform requirements such as ext-redis or ext-intl if the project needs them.
   • Check whether composer install can run for production without interactive steps.

4. Establish the Nixpacks configuration

   • Create or update nixpacks.toml only if auto-detection is not enough or additional build steps are needed.
   • For Laravel and Symfony on Easypanel, typically use NIXPACKS_PHP_ROOT_DIR=/app/public.
   • For front-controller routing, typically set NIXPACKS_PHP_FALLBACK_PATH=/index.php.
   • Add build phases for frontend assets only if package.json and a production build script are present.

5. Document the Easypanel settings

   • Name the builder Nixpacks.
   • Document all required environment variables, especially framework secrets such as APP_KEY, database access, cache/queue/session drivers, and mail settings.
   • Document the expected app port, or explain that the Nixpacks PHP provider starts Nginx.

6. Validate

   • Run local checks that are possible without production access, for example composer validate, composer install --no-dev --dry-run, or existing test/build scripts.
   • Check that the webroot matches the project structure.
   • Check that no secrets were committed.
   • At the end, output clear deploy steps for Easypanel.

Quality criteria

• Nixpacks can detect the project based on composer.json or index.php.
• The webroot is set correctly for frameworks with public/.
• PHP version, extensions, and Composer dependencies are defined in a traceable way.
• Optional Node asset builds are reproducible and use the appropriate package manager.
• Easypanel environment variables are complete, but documented without secret values.
• Existing deployment configuration is respected and not blindly replaced.

Output

At the end, briefly report:

1. Which PHP project type was detected.
2. Which deployment files were created or changed.
3. Which Easypanel environment variables must be set.
4. Which local checks were run and with what result.
5. Which Easypanel steps are needed for the deployment test.
6. Which open items or manual follow-ups remain.