docs: document remote Docker host for local development (#692)

* docs: document remote Docker and BuildKit setup for local development Generated-by: aiautocommit * chore: ignore local mise configuration file Generated-by: aiautocommit * docs(guides): explain why to use a remote Docker host Generated-by: aiautocommit * docs(config): update environment variables documentation - Document how Railpack reads environment variables from its process environment - Relocate and update description for `RAILPACK_DISABLE_CACHES` - Fix table formatting and minor phrasing Generated-by: aiautocommit * docs: clarify remote docker host guide for local development Generated-by: aiautocommit * docs: update BuildKit setup instructions to use docker command Generated-by: aiautocommit
2026-09-30 23:43:13 +00:00 · 2026-08-14 14:30:08 -06:00
parent 58a6c5af8a
commit 2750ff6b8e
4 changed files with 39 additions and 8 deletions
@@ -56,3 +56,5 @@ examples/**/.claude
 ### Mise ###
 # Local mise env selector (enables mise.dev.toml tools when present)
 .miserc.toml
+# Local env overrides (DOCKER_HOST, etc.)
+mise.local.toml
@@ -16,7 +16,6 @@ often prefixed with `RAILPACK_`.
 | `RAILPACK_PACKAGES`            | Install additional Mise packages. In the format `pkg[@version]`. The version is optional; if not provided, the latest version is used. Allows list.                             |
 | `RAILPACK_BUILD_APT_PACKAGES`  | Install additional Apt packages during build. Allows list.                                                                                                                      |
 | `RAILPACK_DEPLOY_APT_PACKAGES` | Install additional Apt packages in the final image. Allows list.                                                                                                                |
-| `RAILPACK_DISABLE_CACHES`      | Specify specific BuildKit cache keys to disable, or `*` to disable all caches. Allows list.                                                                                     |

 Variables which allow a list use space-separated values. For example:

@@ -30,7 +29,11 @@ To configure more parts of the build, it is recommended to use a [config file](/

 These environment variables affect the behavior of Railpack:

-| Name              | Description                                 |
-| :---------------- | :------------------------------------------ |
-| `FORCE_COLOR`     | Force colored output even when not in a TTY |
-| `RAILPACK_VERBOSE` | Enable verbose logging (equivalent to `--verbose` flag) |
+They are read directly from Railpack's process environment; do not pass them
+with `--env`.
+
+| Name                      | Description                                                                 |
+| :------------------------ | :-------------------------------------------------------------------------- |
+| `FORCE_COLOR`             | Force colored output even when not in a TTY                                 |
+| `RAILPACK_VERBOSE`        | Enable verbose logging (equivalent to the `--verbose` flag)                 |
+| `RAILPACK_DISABLE_CACHES` | Disable specific BuildKit cache keys, or `*` to disable all caches. Allows list. |
@@ -56,7 +56,8 @@ through the `BUILDKIT_HOST` environment variable. The easiest way to do this is
 to run a BuildKit instance as a container:

 ```bash
-mise run setup
+docker run --rm --privileged -d --name buildkit moby/buildkit
+export BUILDKIT_HOST='docker-container://buildkit'
 ```

 Now you can build your image using Railpack:
@@ -28,6 +28,30 @@ mise run setup
 This command starts a BuildKit container (check out `mise.toml` in the root
 directory for more information).

+### Remote Docker host
+
+Integration tests and local builds store images and BuildKit cache on
+the Docker host. Point Docker at another machine to keep tens of
+gigabytes of that data off your laptop if you are actively working on Railpack.
+
+Set this in a `mise.local.toml`:
+
+```toml
+[env]
+DOCKER_HOST = "ssh://user@host"
+```
+
+Leave `BUILDKIT_HOST` unset unless the remote container is not named
+`buildkit`. Use key/agent SSH auth. The remote host needs a running
+privileged `buildkit` container.
+
+Confirm the engine with `docker info` (`Name` is the hostname):
+
+```bash
+docker info -f '{{.Name}} {{.OperatingSystem}}'
+docker context inspect -f '{{.Endpoints.docker.Host}}'
+```
+
 Use the `cli` task to run the Railpack CLI (this is like `railpack --help`)

 ```bash
@@ -60,8 +84,9 @@ Pro-tip: point your agent at this guide.

 ## Building directly with BuildKit

-**👋 Requirement**: an instance of BuildKit must be running locally.
-Run `mise run setup` to start a BuildKit container.
+**👋 Requirement**: an instance of BuildKit must be reachable from the
+Docker CLI. Run `mise run setup` to start a local BuildKit container, or
+point Docker at a remote host (see [Remote Docker host](#remote-docker-host)).

 Railpack will instantiate a BuildKit client and communicate over GRPC in
 order to build the generated LLB.