Railpack Build Integration#

Overview#

Railpack is one of six build strategies supported by Dokploy (alongside nixpacks, dockerfile, heroku_buildpacks, paketo_buildpacks, and static). It is selected via the application's buildType field and dispatched by getBuildCommand() in packages/server/src/utils/builders/index.ts. The entire Railpack workflow is encapsulated in a single bash script returned by getRailpackCommand() in packages/server/src/utils/builders/railpack.ts.

Configuration#

Two application fields drive Railpack behavior:

• railpackVersion — defaults to "0.15.4" in both the database schema and frontend Zod validation 1. The UI offers a predefined version dropdown (RAILPACK_VERSIONS) plus a free-text input for custom versions.
• cleanCache — when true, injects a nanoid(10) value as the cache-key build arg to force Docker layer cache invalidation 2.

Build Workflow#

getRailpackCommand() 3 generates a self-contained bash script executed in the deployment pipeline. The script runs three phases in sequence:

1. Install & Prepare#

export RAILPACK_VERSION=<version>
bash -c "$(curl -fsSL https://railpack.com/install.sh)"
docker buildx create --name <builderName> --driver docker-container || true
railpack prepare <buildDir> --plan-out <buildDir>/railpack-plan.json --info-out <buildDir>/railpack-info.json [--env KEY=VALUE ...]

• Railpack is installed fresh from railpack.com/install.sh using the pinned railpackVersion 4.
• A dedicated docker buildx builder instance named railpack-<appName>-<nanoid(6)> is created per build — this prevents race conditions across concurrent deployments 5.
• railpack prepare analyzes the source directory and outputs railpack-plan.json and railpack-info.json to the build directory 6. Environment variables are passed via --env flags 7.

2. Build#

docker buildx build --builder <builderName> \
  --build-arg secrets-hash=<sha256> \
  [--build-arg cache-key=<nanoid>] \
  --build-arg BUILDKIT_SYNTAX=ghcr.io/railwayapp/railpack-frontend:v<version> \
  -f <buildDir>/railpack-plan.json \
  --output type=docker,name=<appName> \
  [--secret id=KEY,env=KEY ...] \
  <buildDir>

Key details:

• BUILDKIT_SYNTAX — specifies the Railpack BuildKit frontend image from ghcr.io/railwayapp/railpack-frontend at the pinned version, allowing railpack-plan.json to be used directly as a Dockerfile 8.
• secrets-hash — a SHA-256 hash of all sorted environment variable strings, used for deterministic layer cache invalidation when secrets change .
• Secrets injection — each env var is passed as --secret id=KEY,env=KEY (BuildKit secrets) and pre-exported via export KEY=<shell-quoted-value> before the docker buildx build call 11. Values are shell-quoted using shell-quote to prevent injection.
• Output — the built image is loaded directly into the local Docker daemon as type=docker,name=<appName> 12.

3. Cleanup#

Regardless of success or failure, docker buildx rm <builderName> removes the isolated builder instance . This prevents builder accumulation across repeated deployments.

Environment Variable Resolution#

Environment variables are resolved through a three-layer merge (service → project → environment) by prepareEnvironmentVariables and prepareEnvironmentVariablesForShell in packages/server/src/utils/docker/utils.ts. The shell-safe variant is used for --env flags in railpack prepare; the raw variant is parsed for BuildKit --secret args.

Call Sites#

getBuildCommand() is invoked from packages/server/src/services/application.ts in four contexts 15:

• Standard deploy (line 225)
• Rebuild (line 318)
• Preview deployments (line 443)
• Rollback (line 558)

If a registry is configured, getBuildCommand() appends an uploadImageRemoteCommand() after the build step.

Key Files#