dokku · josegonzalez · Nov 10, 2025 · Sep 8, 2025 · Sep 15, 2025 · Sep 15, 2025
diff --git a/Dockerfile b/Dockerfile
@@ -33,6 +33,11 @@ RUN mkdir -p /etc/apt/keyrings \
   && NIXPACKS_BIN_DIR=/usr/bin BIN_DIR=/usr/bin /tmp/nixpacks.bash \
   && test -x /usr/bin/nixpacks \
   && rm -rf /tmp/nixpacks.bash \
+  && curl -o /tmp/railpack.bash -sSL https://railpack.com/install.sh \
+  && chmod +x /tmp/railpack.bash \
+  && RAILPACK_BIN_DIR=/usr/bin BIN_DIR=/usr/bin /tmp/railpack.bash \
+  && test -x /usr/bin/railpack \
+  && rm -rf /tmp/railpack.bash \
   && echo "dokku dokku/hostname string $DOKKU_HOSTNAME" | debconf-set-selections \
   && echo "dokku dokku/skip_key_file boolean $DOKKU_SKIP_KEY_FILE" | debconf-set-selections \
   && echo "dokku dokku/vhost_enable boolean $DOKKU_VHOST_ENABLE" | debconf-set-selections \

diff --git a/docker/etc/sudoers.d/dokku-docker b/docker/etc/sudoers.d/dokku-docker
@@ -1 +1 @@
-dokku    ALL=NOPASSWD:SETENV:/usr/bin/docker,/usr/bin/docker-container-healthchecker,/usr/bin/docker-image-labeler,/usr/bin/lambda-builder,/usr/bin/nixpacks,/usr/bin/pack
+dokku    ALL=NOPASSWD:SETENV:/usr/bin/docker,/usr/bin/docker-container-healthchecker,/usr/bin/docker-image-labeler,/usr/bin/lambda-builder,/usr/bin/nixpacks,/usr/bin/railpack,/usr/bin/pack
diff --git a/docker/usr/local/bin/railpack b/docker/usr/local/bin/railpack
@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+set -eo pipefail
+[[ $TRACE ]] && set -x
+
+main() {
+  declare desc="re-runs railpack commands as sudo"
+  local RAILPACK_BIN=""
+  if [[ -x "/usr/bin/railpack" ]]; then
+    RAILPACK_BIN="/usr/bin/railpack"
+  fi
+
+  if [[ -z "$RAILPACK_BIN" ]]; then
+    echo "!   No railpack binary found" 1>&2
+    exit 1
+  fi
+
+  sudo -E "$RAILPACK_BIN" "$@"
+}
+
+main "$@"
diff --git a/docs/appendices/file-formats/railpack-json.md b/docs/appendices/file-formats/railpack-json.md
@@ -0,0 +1,3 @@
+# railpack.json
+
+The `railpack.json` file is used to configure an application when built with the `railpack` builder. Please refer to the [railpack.json documentation](https://railpack.com/config/file) for more information.
diff --git a/docs/deployment/builders/railpack.md b/docs/deployment/builders/railpack.md
@@ -0,0 +1,172 @@
+# Railpack
+
+> [!IMPORTANT]
+> New as of 0.32.0
+
+The `railpack` builder builds apps via [Railpack](https://railpack.com/), a buildpack alternative.
+
+## Usage
+
+### Requirements
+
+Before using Railpacks, the following steps must be taken:
+
+- Install the `railpack` cli: The `railpack` cli tool is not included by default with Dokku or as a dependency. It must also be installed as shown on [this page](https://railpack.com/installation).
+- Create a `buildkit` builder: Railpack uses buildkit.
+       ```shell
+       docker run --rm --privileged -d --name buildkit moby/buildkit
+       ```
+- Set the buildkit builder: Update the `/etc/default/dokku` file to set `BUILDKIT_HOST`:
+       ```shell
+       touch /etc/default/dokku
+       echo "export BUILDKIT_HOST='docker-container://buildkit'" >> /etc/default/dokku
+       ````
+
+### Detection
+
+This builder will be auto-detected in the following case:
+
+- A `railpack.json` exists in the root of the app repository.
+
+The builder may also be selected via the `builder:set` command
+
+```shell
+dokku builder:set node-js-app selected railpack
+```
+
+### Supported languages
+
+See the [upstream railpack documentation](https://railpack.com/) for further information on what languages and frameworks are supported.
+
+### Build-time configuration variables
+
+For security reasons - and as per [Docker recommendations](https://github.com/docker/docker/issues/13490) - railpack-based deploys have variables available only during runtime.
+
+For users that require customization in the `build` phase, you may use build arguments via the [docker-options plugin](/docs/advanced-usage/docker-options.md). All environment variables set by the `config` plugin are automatically exported within the railpack build environment, and thus `--env` only requires setting a key without a value.
+
+```shell
+dokku docker-options:add node-js-app build '--env NODE_ENV'
+```
+
+Alternatively, a full value may be provided in the form of `--env KEY=VALUE`:
+
+```shell
+dokku docker-options:add node-js-app build '--env NODE_ENV=production'
+```
+
+### Changing the `railpack.json` location
+
+The `railpack.json` is expected to be found in a specific directory, depending on the deploy approach:
+
+- The `WORKDIR` of the Docker image for deploys resulting from `git:from-image` and `git:load-image` commands.
+- The root of the source code tree for all other deploys (git push, `git:from-archive`, `git:sync`).
+
+Sometimes it may be desirable to set a different path for a given app, e.g. when deploying from a monorepo. This can be done via the `railpackjson-path` property:
+
+```shell
+dokku builder-railpack:set node-js-app railpackjson-path .dokku/railpack.json
+```
+
+The value is the path to the desired file *relative* to the base search directory, and will never be treated as absolute paths in any context. If that file does not exist within the repository, the build will fail.
+
+The default value may be set by passing an empty value for the option:
+
+```shell
+dokku builder-railpack:set node-js-app railpackjson-path
+```
+
+The `railpackjson-path` property can also be set globally. The global default is `railpack.json`, and the global value is used when no app-specific value is set.
+
+```shell
+dokku builder-railpack:set --global railpackjson-path railpack2.json
+```
+
+The default value may be set by passing an empty value for the option.
+
+```shell
+dokku builder-railpack:set --global railpackjson-path
+```
+
+### Disabling cache
+
+Cache is enabled by default, but can be disabled by setting the `no-cache` property to `true`:
+
+```shell
+dokku builder-railpack:set node-js-app no-cache true
+```
+
+The default value may be set by passing an empty value for the option:
+
+```shell
+dokku builder-railpack:set node-js-app no-cache
+```
+
+The `no-cache` property can also be set globally. The global default is `false`, and the global value is used when no app-specific value is set.
+
+```shell
+dokku builder-railpack:set --global no-cache true
+```
+
+The default value may be set by passing an empty value for the option.
+
+```shell
+dokku builder-railpack:set --global no-cache
+```
+
+### Displaying builder-railpack reports for an app
+
+You can get a report about the app's storage status using the `builder-railpack:report` command:
+
+```shell
+dokku builder-railpack:report
+```
+
+```
+=====> node-js-app builder-railpack information
+       Builder-railpack computed railpackjson path: railpack2.json
+       Builder-railpack global railpackjson path:   railpack.json
+       Builder-railpack railpackjson path:          railpack2.json
+       Builder-railpack computed no cache:          true
+       Builder-railpack global no cache:            false
+       Builder-railpack no cache:                   true
+=====> python-sample builder-railpack information
+       Builder-railpack computed railpackjson path: railpack.json
+       Builder-railpack global railpackjson path:   railpack.json
+       Builder-railpack railpackjson path:
+       Builder-railpack computed no cache:          false
+       Builder-railpack global no cache:            false
+       Builder-railpack no cache:
+=====> ruby-sample builder-railpack information
+       Builder-railpack computed railpackjson path: railpack.json
+       Builder-railpack global railpackjson path:   railpack.json
+       Builder-railpack railpackjson path:
+       Builder-railpack computed no cache:          false
+       Builder-railpack global no cache:            false
+       Builder-railpack no cache:
+```
+
+You can run the command for a specific app also.
+
+```shell
+dokku builder-railpack:report node-js-app
+```
+
+```
+=====> node-js-app builder-railpack information
+       Builder-railpack computed railpackjson path: railpack2.json
+       Builder-railpack global railpackjson path:   railpack.json
+       Builder-railpack railpackjson path:          railpack2.json
+       Builder-railpack computed no cache:          true
+       Builder-railpack global no cache:            false
+       Builder-railpack no cache:                   true
+```
+
+You can pass flags which will output only the value of the specific information you want. For example:
+
+```shell
+dokku builder-railpack:report node-js-app --builder-railpack-no-cache
+```
+
+```
+true
+```
diff --git a/docs/template.html b/docs/template.html
@@ -150,6 +150,7 @@
             <a href="/{{NAME}}/deployment/builders/lambda/" class="list-group-item">Lambda Builder</a>
             <a href="/{{NAME}}/deployment/builders/nixpacks/" class="list-group-item">Nixpacks Builder</a>
             <a href="/{{NAME}}/deployment/builders/null/" class="list-group-item">Null Builder</a>
+            <a href="/{{NAME}}/deployment/builders/railpack/" class="list-group-item">Railpack Builder</a>
 
             <a href="#" class="list-group-item disabled">Deployment Methods</a>
             <a href="/{{NAME}}/deployment/methods/git/" class="list-group-item">Git Deployment</a>

diff --git a/plugins/builder-railpack/builder-build b/plugins/builder-railpack/builder-build
@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+source "$PLUGIN_CORE_AVAILABLE_PATH/common/functions"
+source "$PLUGIN_AVAILABLE_PATH/builder-railpack/internal-functions"
+source "$PLUGIN_AVAILABLE_PATH/config/functions"
+set -eo pipefail
+[[ $DOKKU_TRACE ]] && set -x
+
+trigger-builder-railpack-builder-build() {
+  declare desc="builder-railpack builder-build plugin trigger"
+  declare trigger="builder-build"
+  declare BUILDER_TYPE="$1" APP="$2" SOURCECODE_WORK_DIR="$3"
+
+  if [[ "$BUILDER_TYPE" != "railpack" ]]; then
+    return
+  fi
+
+  dokku_log_info1 "Building $APP from railpack"
+
+  if ! command -v "railpack" &>/dev/null; then
+    dokku_log_fail "Missing railpack, install it"
+  fi
+
+  local IMAGE=$(get_app_image_name "$APP")
+  local DOCKER_BUILD_LABEL_ARGS=("--label=dokku" "--label=org.label-schema.schema-version=1.0" "--label=org.label-schema.vendor=dokku" "--label=com.dokku.image-stage=build" "--label=com.dokku.builder-type=railpack" "--label=com.dokku.app-name=$APP")
+
+  pushd "$SOURCECODE_WORK_DIR" &>/dev/null
+
+  plugn trigger pre-build "$BUILDER_TYPE" "$APP" "$SOURCECODE_WORK_DIR"
+
+  no_cache="$(fn-builder-railpack-computed-no-cache "$APP")"
+  RAILPACK_ARGS=""
+  if [[ "$no_cache" == "true" ]]; then
+    RAILPACK_ARGS="$RAILPACK_ARGS --no-cache"
+  fi
+
+  local DOCKER_ARGS=$(: | plugn trigger docker-args-build "$APP" "$BUILDER_TYPE")
+  DOCKER_ARGS+=$(: | plugn trigger docker-args-process-build "$APP" "$BUILDER_TYPE")
+
+  # strip --link, --volume and -v args from DOCKER_ARGS
+  local DOCKER_ARGS=$(sed -e "s/^--link=[[:graph:]]\+[[:blank:]]\?//g" -e "s/^--link[[:blank:]]\?[[:graph:]]\+[[:blank:]]\?//g" -e "s/^--volume=[[:graph:]]\+[[:blank:]]\?//g" -e "s/^--volume[[:blank:]]\?[[:graph:]]\+[[:blank:]]\?//g" -e "s/^-v[[:blank:]]\?[[:graph:]]\+[[:blank:]]\?//g" <<<"$DOCKER_ARGS")
+  declare -a ARG_ARRAY
+  eval "ARG_ARRAY=($DOCKER_ARGS)"
+
+  eval "$(config_export app "$APP" --merged)"
+
+  if [[ -f "$SOURCECODE_WORK_DIR/Procfile" ]]; then
+    if procfile-util exists --process-type release; then
+      procfile-util delete --process-type release
+    fi
+  fi
+
+  # shellcheck disable=SC2086
+  if ! railpack build "${ARG_ARRAY[@]}" $RAILPACK_ARGS --name "$IMAGE-build" "$SOURCECODE_WORK_DIR"; then
+    dokku_log_warn "Failure building image"
+    return 1
+  fi
+
+  if ! suppress_output "$DOCKER_BIN" image build -f "$PLUGIN_AVAILABLE_PATH/builder-railpack/dockerfiles/builder-build.Dockerfile" --build-arg APP_IMAGE="$IMAGE-build" "${DOCKER_BUILD_LABEL_ARGS[@]}" $DOKKU_GLOBAL_BUILD_ARGS -t "$IMAGE" "$SOURCECODE_WORK_DIR"; then
+    "$DOCKER_BIN" image remove "$IMAGE-build"
+    dokku_log_warn "Failure injecting docker labels and custom entrypoint on image"
+    return 1
+  fi
+
+  "$DOCKER_BIN" image remove "$IMAGE-build"
+
+  plugn trigger post-build "$BUILDER_TYPE" "$APP" "$SOURCECODE_WORK_DIR"
+  popd &>/dev/null || pushd "/tmp" >/dev/null
+}
+
+trigger-builder-railpack-builder-build "$@"
diff --git a/plugins/builder-railpack/builder-detect b/plugins/builder-railpack/builder-detect
@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+source "$PLUGIN_AVAILABLE_PATH/config/functions"
+set -eo pipefail
+[[ $DOKKU_TRACE ]] && set -x
+
+trigger-builder-railpack-builder-detect() {
+  declare desc="builder-railpack builder-detect plugin trigger"
+  declare trigger="builder-detect"
+  declare APP="$1" SOURCECODE_WORK_DIR="$2"
+
+  if [[ -f "$SOURCECODE_WORK_DIR/railpack.json" ]]; then
+    echo "railpack"
+    return
+  fi
+}
+
+trigger-builder-railpack-builder-detect "$@"
diff --git a/plugins/builder-railpack/builder-release b/plugins/builder-railpack/builder-release
@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+source "$PLUGIN_CORE_AVAILABLE_PATH/common/functions"
+set -eo pipefail
+[[ $DOKKU_TRACE ]] && set -x
+
+trigger-builder-railpack-builder-release() {
+  declare desc="builder-railpack builder-release plugin trigger"
+  declare trigger="builder-release"
+  declare BUILDER_TYPE="$1" APP="$2" IMAGE_TAG="$3"
+
+  if [[ "$BUILDER_TYPE" != "railpack" ]]; then
+    return
+  fi
+
+  local IMAGE=$(get_app_image_name "$APP" "$IMAGE_TAG")
+  plugn trigger pre-release-builder "$BUILDER_TYPE" "$APP" "$IMAGE"
+
+  TMP_WORK_DIR="$(mktemp -d "/tmp/dokku-${DOKKU_PID}-${FUNCNAME[0]}.XXXXXX")"
+  trap "rm -rf '$TMP_WORK_DIR' >/dev/null" RETURN INT TERM EXIT
+
+  local DOCKER_BUILD_LABEL_ARGS="--label=org.label-schema.schema-version=1.0 --label=org.label-schema.vendor=dokku --label=com.dokku.app-name=$APP  --label=com.dokku.image-stage=release --label=dokku"
+  if ! suppress_output "$DOCKER_BIN" image build "${DOCKER_BUILD_LABEL_ARGS[@]}" $DOKKU_GLOBAL_BUILD_ARGS -f "$PLUGIN_AVAILABLE_PATH/builder-railpack/dockerfiles/builder-release.Dockerfile" --build-arg APP_IMAGE="$IMAGE" -t "$IMAGE" "$TMP_WORK_DIR"; then
+    dokku_log_warn "Failure injecting docker labels on image"
+    return 1
+  fi
+
+  plugn trigger post-release-builder "$BUILDER_TYPE" "$APP" "$IMAGE"
+}
+
+trigger-builder-railpack-builder-release "$@"
diff --git a/plugins/builder-railpack/commands b/plugins/builder-railpack/commands
@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -eo pipefail
+[[ $DOKKU_TRACE ]] && set -x
+source "$PLUGIN_AVAILABLE_PATH/builder-railpack/help-functions"
+
+case "$1" in
+  help | builder-railpack:help)
+    cmd-builder-railpack-help "$@"
+    ;;
+
+  *)
+    exit "$DOKKU_NOT_IMPLEMENTED_EXIT"
+    ;;
+
+esac
diff --git a/plugins/builder-railpack/core-post-extract b/plugins/builder-railpack/core-post-extract
@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+source "$PLUGIN_CORE_AVAILABLE_PATH/common/functions"
+source "$PLUGIN_AVAILABLE_PATH/builder-railpack/internal-functions"
+set -eo pipefail
+[[ $DOKKU_TRACE ]] && set -x
+
+trigger-builder-railpack-core-post-extract() {
+  declare desc="builder-railpack post-extract plugin trigger"
+  declare trigger="post-extract"
+  declare APP="$1" SOURCECODE_WORK_DIR="$2"
+  local NEW_RAILPACK_JSON="$(fn-builder-railpack-computed-railpackjson-path "$APP")"
+
+  pushd "$TMP_WORK_DIR" >/dev/null
+
+  if [[ -z "$NEW_RAILPACK_JSON" ]]; then
+    return
+  fi
+
+  if [[ ! -f "$NEW_RAILPACK_JSON" ]]; then
+    rm -f railpack.json
+    return
+  fi
+
+  if [[ "$NEW_RAILPACK_JSON" != "railpack.json" ]]; then
+    mv "$NEW_RAILPACK_JSON" railpack.json
+  fi
+  popd &>/dev/null || pushd "/tmp" >/dev/null
+}
+
+trigger-builder-railpack-core-post-extract "$@"
diff --git a/plugins/builder-railpack/dockerfiles/builder-build.Dockerfile b/plugins/builder-railpack/dockerfiles/builder-build.Dockerfile
@@ -0,0 +1,4 @@
+ARG APP_IMAGE
+FROM $APP_IMAGE
+
+ENTRYPOINT []
diff --git a/plugins/builder-railpack/dockerfiles/builder-release.Dockerfile b/plugins/builder-railpack/dockerfiles/builder-release.Dockerfile
@@ -0,0 +1,2 @@
+ARG APP_IMAGE
+FROM $APP_IMAGE
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		dokku ALL=NOPASSWD:SETENV:/usr/bin/docker,/usr/bin/docker-container-healthchecker,/usr/bin/docker-image-labeler,/usr/bin/lambda-builder,/usr/bin/nixpacks,/usr/bin/pack
		dokku ALL=NOPASSWD:SETENV:/usr/bin/docker,/usr/bin/docker-container-healthchecker,/usr/bin/docker-image-labeler,/usr/bin/lambda-builder,/usr/bin/nixpacks,/usr/bin/railpack,/usr/bin/pack
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# railpack.json

		The `railpack.json` file is used to configure an application when built with the `railpack` builder. Please refer to the [railpack.json documentation](https://railpack.com/config/file) for more information.