BuildKit Frontend Reference

If you are a platform, use the BuildKit frontend to build projects. If you want to build a single container, use the other railpack subcommands and ignore this documentation.

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

Using Railpack as a BuildKit Frontend

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

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).

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-frontend:latest \
  --output type=docker,name=test

buildctl is a lower-level interface to BuildKit. Its arguments and semantics are similar to docker buildx, but not identical.

Configuration

Pass advanced options to the frontend using --opt with BuildKit or --build-arg with Docker:

Flag	Description
cache-key	Prefix used to isolate mount cache IDs
secrets-hash	Hash used to invalidate layers when secrets change
github-token	Token used to increase GitHub API rate limits

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 \
  -f /path/to/railpack-plan.json \
  /path/to/app/to/build

BuildKit:

buildctl build \
  --frontend=gateway.v0 \
  --opt source=ghcr.io/railwayapp/railpack-frontend:latest \
  --opt build-arg:cache-key=my-key \
  --opt build-arg:secrets-hash=abc123 \
  --opt build-arg:github-token=ghp_xxx

The build-arg: prefix is required only with buildctl so the argument structure matches docker buildx.

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=sk_live_123 \
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:

STRIPE_LIVE_KEY=sk_live_123 \
buildctl build \
  --frontend=gateway.v0 \
  --opt source=ghcr.io/railwayapp/railpack-frontend:latest \
  --local context=/path/to/app/to/build \
  --local dockerfile=/path/to/dir/containing/railpack-plan.json \
  --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:

secrets_hash=$(
  echo -n "STRIPE_LIVE_KEY=sk_live_asdf" |
    sha256sum |
    awk '{print $1}'
)

--build-arg secrets-hash="$secrets_hash"

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.