# Docker builds

Build Docker images on a Groundbox builder: BuildKit on our box with 8 vCPUs and 16 GB, and a layer cache that is kept per project between builds. A second build of the same Dockerfile reuses every layer that did not change. On every plan.

## From a terminal or an agent

```
export GROUNDBOX_API_KEY=gbx_...   # a key with builds:write
groundbox build -t ghcr.io/acme/app:latest --push .
groundbox build --load -t app .   # back into your local docker
```

`groundbox build` takes the flags of `docker build` and runs `docker buildx build` against the project's builder. It prints the steps, and at the end how many came from the cache. Without `--push`, `--load` or `--output` the image stays in the builder's cache only.

`groundbox build setup` registers a buildx builder named `groundbox` (and makes it the default), so plain `docker buildx build` uses it; `groundbox build stop` removes it.

## In GitHub Actions

```
- uses: Ground-box/setup-build@v1
  with:
    api-key: ${{ secrets.GROUNDBOX_API_KEY }}
- uses: docker/build-push-action@v6
  with:
    push: true
    tags: ghcr.io/acme/app:latest
```

One step before `docker/build-push-action`, which works unchanged. It works on Groundbox runners, GitHub-hosted runners and your own. Remove any `cache-from` and `cache-to`: the builder keeps the cache.

## Projects and the cache

- A project names a cache: the repository by default (`--project` or the action's `project` input to choose).
- The cache is the team's own: no other team's build can read it or write to it. Build secrets go through BuildKit secrets (`--secret`) and are never stored in it.
- Each project's cache holds up to 50 GB; the least recently used layers go first. Clear it on the Docker builds page.
- The builder starts on the first build (under a minute) and stops after 10 idle minutes. The cache stays.

## Price

Builder time is billed like CI time at the 8-vCPU runner's price, $0.011 a minute, per second, from the builder's start to its stop (including the idle minutes). The cache is included.

## Limits

- Images are built natively for `linux/amd64`. `linux/arm64` runs under QEMU emulation: it works, slowly.
- One connection to the builder lasts at most an hour, so a single build over an hour is cut.
- The build context goes to the builder over HTTPS: a large context (without a `.dockerignore`) adds upload time.
