Railpack Documentation

Railpack is a zero-config application builder designed to automatically analyze your source code and transform it into a container image. It functions as a custom BuildKit frontend, utilizing BuildKit LLB for efficient image construction.

Key capabilities include:

• Multi-language support: Out-of-the-box support for Node, Python, Go, PHP, Java, Ruby, and more.
• Framework awareness: First-class support for modern web frameworks like Vite, Astro, Next.js, and Create React App (CRA) static sites.
• Customization: Users can configure build behavior using environment variables or a configuration file.

Railpack is designed as a modern alternative to Heroku builders and Cloud Native Buildpacks (CNB) with the following characteristics:

• Open Source: Completely open source and serves as the default builder for Railway.
• Unified Builder: A single builder for all languages, removing the need to manage multiple language-specific CNB builders.
• Parallel Execution: Built on Docker LLB, allowing many aspects of the build to run in parallel.
• Tooling Alignment: Built on mise, enabling you to align development, CI, and production tooling.
• Testing Strategy: Every change is tested across hundreds of example projects to ensure stability.

Railpack treats environment variables and secrets differently based on their lifecycle and visibility:

• Environment Variables: These are saved in the final image and are available at runtime. They should not contain sensitive information. Providers can use these to inject runtime configuration.
• Secrets: These are only available at build time and are never saved to the final image or logged in build logs. They are supplied via BuildKit secrets mounts.

Language support is implemented via Providers (e.g., node, python, php). A provider performs two main functions:

1. Detect: It analyzes the application directory to determine if it matches the provider's criteria (e.g., the node provider looks for a package.json).
2. Build: It modifies the build context by injecting the necessary steps, commands, caches, and configurations required to build for that specific language or framework.

Railpack utilizes BuildKit's layer caching to optimize build speeds by avoiding redundant work. The cache is preserved unless a 'cache busting' event occurs.

Cache busting is triggered by:

• Copying files from the local context to the build context
• Changing environment variables
• Adding new generated files to the build context
• Executing shell commands in the build context

Railpack builds Deno applications using a zero-configuration approach. The build process follows these steps:

1. Installation: Installs the specified Deno version.
2. Dependency Caching: Runs deno cache to prepare dependencies.
3. Start Command: Determines the entry point to run with deno run --allow-all.

Determining the Entry Point

Railpack selects the file to run in this order:

1. It looks for a main.ts, main.js, main.mjs, or main.mts file in the project root.
2. If no such file exists, it uses the first .ts, .js, .mjs, or .mts file found in the project.

Railpack automatically identifies a project as a static site if any of the following conditions are met:

• A Staticfile configuration file is present in the root directory.
• An index.html file is present in the root directory.
• A public directory exists.
• The RAILPACK_STATIC_FILE_ROOT environment variable is set.

Railpack is composed of three main components that work together to transform an application into a container image:

• Core: Acts as a compiler. It analyzes your application and generates a platform-independent Build Plan (a JSON object).
• BuildKit: Acts as the backend. It consumes the Build Plan to generate BuildKit LLB (Low-Level Builder) and executes the build to produce a final image.
• CLI: The primary entry point for users to interact with the system.

The architecture is designed so that the Build Plan is decoupled from the specific backend (currently BuildKit), allowing for future extensibility.

Railpack automatically detects Bun as the JavaScript runtime and package manager using the following priority logic:

1. Explicit Declaration: The packageManager field in package.json explicitly declares bun.
2. Implicit Detection: If no higher-priority package manager is configured, Railpack looks for:
   • An engines.bun field in package.json.
   • A bun.lock file.
   • A bun.lockb file.
3. Command Invocation: Bun is also installed if a package script or a configured start command explicitly invokes the bun binary.