Builders

An App service needs a container image before it can run. When the source is an upload, GitHub repository, or Git repository, Easypanel can build that image with Dockerfile, Cloud Native Buildpacks, Nixpacks, or Railpack.

The builder runs against the source's configured Build Path. In a monorepo, set that path to the application directory so detection files, package manifests, and the Docker build context come from the intended project.

Choose a builder

For a new application without a Dockerfile, start with Railpack. Use a Dockerfile when automatic detection cannot express the required build or when you need full control over the base image and system configuration.

Configure and run a build

1. Open the App service's Source section.
2. Select Upload, GitHub, or Git and configure its Build Path.
3. Open Build and select a builder.
4. Save its settings.
5. Select Deploy from the service overview.
6. Open the deployment action to review detection, dependency installation, compilation, and image creation output.

Saving a builder does not deploy the application. Use Force Rebuild when you need another deployment without the existing Docker build cache.

Project and service environment variables are available during builds, and Easypanel also adds GIT_SHA for repository deployments. They are provided to the running container separately.

Railpack

Railpack analyzes the source, selects a provider, creates a build plan, and produces an image with BuildKit. It supports common Node.js and frontend frameworks as well as Python, Go, PHP, Java, Ruby, .NET, Deno, Rust, Elixir, static sites, and other providers.

Railpack is the preferred automatic builder for new applications. It is the successor to Nixpacks and generally produces smaller runtime images with more granular build and runtime package controls.

Easypanel settings

• Version pins the Railpack release used to generate and execute the plan.
• Install Command replaces the provider's detected install commands.
• Build Command replaces the provider's detected build commands.
• Start Command sets the command used when the resulting container starts.
• Mise Packages installs additional tools. Enter space-separated package@version values; the version is optional.
• Build APT Packages installs packages needed only while building.
• Deploy APT Packages installs packages in the final runtime image.

Use Deploy APT Packages for commands the application needs after it starts, such as ffmpeg. Prefer Build APT Packages for compilers and headers that are not needed at runtime.

The three command fields are replacements, not additional commands. Leave them empty to use Railpack's detected provider commands.

Advanced Railpack configuration

For configuration beyond the Easypanel fields, add railpack.json to the root of the Build Path. Railpack automatically reads that file. It can select a provider, add or change build steps, configure caches and packages, and control the final deployment command.

{
  "$schema": "https://schema.railpack.com",
  "provider": "node",
  "steps": {
    "build": {
      "commands": ["npm run build"]
    }
  },
  "deploy": {
    "startCommand": "node dist/server.js"
  }
}

See the official Railpack configuration reference and environment variable reference.

Dockerfile

Dockerfile builds provide direct control over the build stages, base image, installed packages, files, user, and default command.

There are two ways to use one:

• With an Upload, GitHub, or Git source, select Dockerfile under Build and enter the file path. The default is Dockerfile.
• Select Dockerfile as the source type to store a complete inline Dockerfile in Easypanel. This source has no repository files unless the Dockerfile downloads or creates them itself.

For repository sources, the Dockerfile path is resolved from the Build Path, and that directory is also the Docker build context. A Dockerfile cannot COPY files outside that context.

Easypanel builds the image with Docker Buildx and passes project and service environment values, including GIT_SHA, as build arguments. Declare only the arguments the Dockerfile needs:

ARG GIT_SHA
RUN echo "Building revision ${GIT_SHA}"

Use a multi-stage Dockerfile to leave compilers and source-only dependencies out of the final image. Pin important base-image versions or digests and keep a .dockerignore file in the Build Path to exclude local dependencies, Git data, secrets, and other unnecessary files.

See Docker's Dockerfile reference for instruction syntax.

Buildpacks

Easypanel uses the pack CLI and a selected Cloud Native Buildpacks builder to detect the application, install its runtime and dependencies, and create an OCI image without a Dockerfile.

The current builder suggestions include:

• heroku/builder:24, the default;
• heroku/builder:22 and heroku/builder:20;
• Paketo Jammy full, base, and tiny builders.

The Builder field accepts an image reference, so it is not limited to the suggestions. A builder controls which buildpacks, build image, and run images are available. Test compatibility before changing it on an existing service.

Easypanel asks pack to use the web process as the image's default process. Make sure the detected buildpacks create that process. Use a project.toml file in the Build Path when you need to select buildpacks or configure other Cloud Native Buildpacks inputs.

See the official Cloud Native Buildpacks app developer guide and the current Heroku Cloud Native Buildpacks documentation.

Nixpacks

Nixpacks detects the application and produces a Nix-based build plan containing packages, install and build commands, and a start command.

Nixpacks is now in maintenance mode, and its maintainers recommend Railpack as the replacement. Existing Nixpacks services can continue to use it, but prefer Railpack for new applications unless a project depends on Nix-specific packages or behavior.

Easypanel settings

• Version pins the Nixpacks release.
• Install Command, Build Command, and Start Command replace detected commands.
• Nix Packages adds packages from Nix.
• APT Packages adds packages through APT.

Pin the version for repeatable builds. Test a version change in a staging service because provider detection and generated build plans can change between releases.

For more control, put nixpacks.toml or nixpacks.json in the Build Path. The file can extend provider-generated phases instead of replacing every detected setting.

See the official Nixpacks configuration guide.

Build paths and monorepos

Detection and build files must be inside the configured Build Path:

repository/
├── apps/
│   ├── api/
│   │   ├── package.json
│   │   └── railpack.json
│   └── web/
└── package.json

For the API in this example, use /apps/api when it can build independently. Use / when its build needs workspace files from the repository root.

The Build Path is also the boundary of the Docker build context. Choosing a deep path can prevent access to shared packages above it; choosing the repository root can make automatic detection select the wrong application.

Docker Buildx builders

Dockerfile and generated Nixpacks and Railpack images use the currently selected Docker Buildx builder. Open Settings → Server → Docker Builders to:

• see the current builder and whether its node is running;
• create and select a builder with CPU, memory, and swap limits;
• switch, stop, or remove non-default builders.

A resource-limited builder can protect application workloads from build spikes, but a limit that is too low can terminate dependency installation or compilation. For another server, see Remote Docker Builder.

Troubleshooting

The builder detects the wrong application

Check the Source Build Path and make sure the expected manifest or config file is at its root. In a monorepo, decide whether the application can build from its own directory or needs the repository root.

The build succeeds but the container does not start

Check the detected or overridden start command. The application should run as a foreground process, listen on the configured target port, and normally bind to 0.0.0.0.

A command or library is missing at runtime

With Railpack, put runtime commands in Deploy APT Packages, not only Build APT Packages. With a Dockerfile, install runtime dependencies in the final stage. For Nixpacks or Buildpacks, inspect the generated plan or builder documentation.

A corrected build keeps using old output

Select Force Rebuild to bypass the Docker build cache. If the issue remains, check package-manager caches, generated artifacts committed to the repository, and whether the deployment is building the expected revision and Build Path.

The build runs out of memory

Review server capacity and the selected Docker builder's limits. Increase the builder memory or swap, reduce parallel compilation, or use a remote builder.