From 084097626557502de98775403741f057ebb91eea Mon Sep 17 00:00:00 2001
From: Jose Diaz-Gonzalez <email@josediazgonzalez.com>
Date: Mon, 15 Sep 2025 00:21:50 -0400
Subject: [PATCH] fix: add references to BUILDKIT_HOST for setup and fix tests

---
 docs/deployment/builders/railpack.md | 13 +++++++++++--
 tests/unit/builder-railpack.bats     |  8 ++++++++
 2 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/docs/deployment/builders/railpack.md b/docs/deployment/builders/railpack.md
index 3483c7d72..dc0d634fb 100644
--- a/docs/deployment/builders/railpack.md
+++ b/docs/deployment/builders/railpack.md
@@ -9,9 +9,18 @@ The `railpack` builder builds apps via [Railpack](https://railpack.com/), a buil
 
 ### Requirements
 
-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).
+Before using Railpacks, the following steps must be taken:
 
-Builds will proceed with the `railpack` cli for the app from then on.
+- 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
 
diff --git a/tests/unit/builder-railpack.bats b/tests/unit/builder-railpack.bats
index 017123f0c..069960a07 100644
--- a/tests/unit/builder-railpack.bats
+++ b/tests/unit/builder-railpack.bats
@@ -4,6 +4,14 @@ load test_helper
 
 setup_file() {
   install_railpack
+  docker run --rm --privileged -d --name buildkit moby/buildkit:latest
+  touch /etc/default/dokku
+  sudo tee -a /etc/default/dokku <<<"export BUILDKIT_HOST='docker-container://buildkit'"
+}
+
+teardown_file() {
+  docker container stop buildkit || true
+  docker container rm buildkit || true
 }
 
 setup() {