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

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

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

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

**BuildKit:**

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

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

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

```sh
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](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.