[Request]: Support Docker/BuildKit named build contexts in container build
- Dominant language
- Swift
- Stars
- 49.9k
- Forks
- 1.8k
- Avg merge
- 1d 20h
- Merged PRs (30d)
- 22
Description
### Feature or enhancement request details
`container build` should support Docker/BuildKit named build contexts, equivalent to Docker/Buildx and Podman `--build-context name=value`.
This is a Dockerfile/BuildKit feature used by higher-level build tooling to pass additional local directories, Git contexts, URLs, OCI layouts, or image references into a build without copying them under the primary build context. Typical Dockerfile usage is:
```Dockerfile
FROM alpine
COPY --from=deps /some/file /some/file
```
with a CLI invocation like:
```sh
container build \
--build-context deps=/path/to/deps \
-t example:latest \
.
```
Today `container build --help` does not expose `--build-context`, and the public build RPC/config path appears to carry only one primary context directory. That means tools that rely on named contexts cannot transparently use Apple `container` as a Docker-compatible builder even though the underlying builder is BuildKit-based.
### Why this matters
Named contexts are not only a convenience feature. They are used by libraries and build systems that need to:
- avoid copying large generated/source trees into the main context;
- keep Dockerfile context boundaries explicit;
- consume additional local source roots in monorepos;
- pin or lock base images via `docker-image://...` contexts;
- match Docker/Buildx and Podman behavior for existing consumers.
For example, AWS CDK-style container asset builders can receive a user-supplied map of build contexts. Without this flag, such libraries must either reject Apple `container` for those builds or switch to a separate BuildKit path and only load the final OCI image into `container` afterward.
### Existing ecosystem support
Docker/Buildx supports named build contexts:
```sh
docker buildx build --build-context deps=/path/to/deps .
docker buildx build --build-context base=docker-image://alpine:latest .
```
Podman supports the same concept:
```sh
podman build --build-context deps=/path/to/deps .
podman build --build-context base=docker-image://alpine:latest .
```
Direct BuildKit supports the underlying mechanism through Dockerfile frontend options. For local named contexts this is roughly:
```sh
buildctl build \
--frontend=dockerfile.v0 \
--local context=. \
--local dockerfile=. \
--local deps=/path/to/deps \
--opt context:deps=local:deps
```
For image/OCI contexts BuildKit frontend attrs use forms such as:
```sh
--opt context:base=docker-image://alpine:latest
--opt context:base=oci-layout:/path/to/oci-layout@sha256:...
```
So the underlying BuildKit machinery already supports this. The missing piece seems to be Apple `container` CLI/API/shim plumbing for multiple named contexts and the corresponding context transfer/serving logic.
### Suggested behavior
Add support for one or more `--build-context name=value` flags to `container build`, matching Docker/Podman syntax where practical.
At minimum, support these common values:
- `name=/absolute/or/relative/local/path`
- `name=docker-image://registry/name:tag`
- `name=docker-image://registry/name@sha256:...`
- `name=oci-layout:/path/to/layout@sha256:...`
- URL/Git contexts if they are already supported by the selected Dockerfile frontend
The local path case likely needs the build request/shim protocol to carry more than the current primary context and expose each named local context to BuildKit as a separate local source.
### Current workaround
The practical workaround is to bypass `container build`, run BuildKit directly with named context frontend options, export an OCI archive, and then load the result into Apple `container`:
```sh
buildctl build ... --output type=oci,dest=image.tar
container image load -i image.tar
container image tag example:latest
```
That works, but it loses the simplicity of `container build` and requires users/tools to manage a separate BuildKit daemon, auth, cache, and networking behavior.
### Code of Conduct
- [x] I agree to follow this project's Code of Conduct
Contributor guide
Research direction
Start by tracing the `container build` CLI, the public build RPC/config path, and the shim or context-serving logic described in the issue. Compare how the existing primary context reaches BuildKit, then verify that repeated `--build-context name=value` entries support local contexts and the requested Dockerfile `COPY --from` behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- docker, swift
- Domain
- backend-api-design, build-system, cli
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100