BuildKit Frontend Reference

Complete reference documentation for the Railpack BuildKit frontend. For a full example of how to use the frontend for a production build, see the running railpack in production guide.

Expected

To use the Railpack BuildKit frontend, you must provide a build plan file (e.g. railpack-plan.json) generated by the railpack prepare command. This file describes how your app should be built and must be accessible to the build process.

You must specify the path to the build plan file:

For Docker (with BuildKit enabled):

docker buildx build \
  --build-arg BUILDKIT_SYNTAX="ghcr.io/railwayapp/railpack-frontend" \
  -f /path/to/railpack-plan.json \
  /path/to/app/to/build

For BuildKit directly:

buildctl build \
  --local context=/path/to/app/to/build \
  --local dockerfile=/path/to/dir/containing/railpack-plan.json \
  --frontend=gateway.v0 \
  --opt source=ghcr.io/railwayapp/railpack:railpack-frontend \
  --output type=docker,name=test

The build plan file does not need to be in the same directory as your app, but you must reference it correctly with the -f flag (Docker) or --local dockerfile (BuildKit).

Configuration

You can pass advanced options to the frontend using the --opt flag (for BuildKit) or as --build-arg (for Docker). The following options are supported:

Flag	Description	Default
--cache-key	Unique ID to prefix to cache keys for cache invalidation.
--secrets-hash	Hash of all secret values, used to invalidate cache when secrets change.
--github-token	GitHub token to increase API rate limits for private repositories or package installs.

Example

Docker:

docker buildx build \
  --build-arg BUILDKIT_SYNTAX="ghcr.io/railwayapp/railpack-frontend" \
  --build-arg cache-key=my-key \
  --build-arg secrets-hash=abc123 \
  --build-arg github-token=ghp_xxx \
  --build-arg FOO=bar \
  -f /path/to/railpack-plan.json \
  /path/to/app/to/build

BuildKit:

buildctl build \
  --frontend=railwayapp/railpack \
  --opt cache-key=my-key \
  --opt secrets-hash=abc123 \
  --opt github-token=ghp_xxx \
  --opt build-arg:FOO=bar

Secrets

To use secrets in your build, you must:

1. Pass secret names to railpack prepare (so they are included in the build plan):

railpack prepare /dir/to/build --env STRIPE_LIVE_KEY=sk_live_asdf

2. Pass secret values to the build using Docker or BuildKit:

Docker:

STRIPE_LIVE_KEY=asdfasdf docker buildx build \
  --build-arg BUILDKIT_SYNTAX="ghcr.io/railwayapp/railpack-frontend" \
  -f /path/to/railpack-plan.json \
  --secret id=STRIPE_LIVE_KEY,env=STRIPE_LIVE_KEY \
  /path/to/app/to/build

BuildKit:

buildctl build \
  --local context=/path/to/app/to/build \
  --local dockerfile=/path/to/dir/containing/railpack-plan.json \
  --frontend=gateway.v0 \
  --opt source=ghcr.io/railwayapp/railpack:railpack-frontend \
  --secret id=STRIPE_LIVE_KEY,env=STRIPE_LIVE_KEY \
  --output type=docker,name=test

Layer Invalidation

To ensure build layers are invalidated when secret values change, compute a hash of your secret values and pass it as a build argument:

--build-arg secrets-hash=$(echo -n "STRIPE_LIVE_KEY=sk_live_asdf" | sha256sum | awk '{print $1}')

This ensures the build cache is properly invalidated when secrets change.

GitHub Token

If provided, the GitHub token is passed to Mise as the GITHUB_TOKEN (Docs). This increases the rate limits when fetching info from the GitHub API.

Once passed, this token will be accessible to the build context, so you should not pass a token that the owner of the build code should not have access to.