# 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](../guides/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):

```sh
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:

```sh
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:**

```sh
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:**

```sh
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):

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

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

**Docker:**

```sh
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:**

```sh
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:

```sh
--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](https://mise.jdx.dev/getting-started.html#github-api-rate-limiting)).
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.