From 6a6e8c7c14655eee21000079b80ea675f7e16867 Mon Sep 17 00:00:00 2001 From: Andrei Baibaratsky Date: Sat, 13 Aug 2022 13:50:23 +0200 Subject: [PATCH 1/2] docs: build contexts and bake options Signed-off-by: Andrei Baibaratsky --- docs/advanced/export-docker.md | 72 ++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) diff --git a/docs/advanced/export-docker.md b/docs/advanced/export-docker.md index a8b7083e6..d2d9c894a 100644 --- a/docs/advanced/export-docker.md +++ b/docs/advanced/export-docker.md @@ -33,3 +33,75 @@ jobs: run: | docker image inspect myimage:latest ``` + + +## Usage of the built image in other build steps + +[By default](https://github.com/docker/setup-buildx-action#customizing), `docker/setup-buildx-action@v2` +uses `docker-container` as a build driver, so the docker images are not available in the builder container. +To use them, you may use [build contexts](https://github.com/docker/buildx/blob/master/docs/reference/buildx_build.md#-additional-build-contexts---build-context): + +```yaml +name: ci + +on: + push: + branches: + - 'main' + +jobs: + docker: + runs-on: ubuntu-latest + steps: + - + name: Checkout + uses: actions/checkout@v3 + - + name: Set up Docker Buildx + uses: docker/setup-buildx-action@v2 + - + name: Build base image + uses: docker/build-push-action@v3 + with: + context: base + load: true + tags: my-base-image:latest + - + name: Build image from my-base-image:latest + uses: docker/build-push-action@v3 + with: + context: . + build-contexts: | + base-image=docker-image://my-base-image:latest + tags: myimage:latest +``` + +Where `base-image`is the name of the base image (or stage name if specified) in your Dockerfile: +```Dockerfile +FROM base-image +``` + +### Bake alternative + +You may also want to use [bake](https://docs.docker.com/build/bake/build-contexts/#using-a-result-of-one-target-as-a-base-image-in-another-target) +and build the base image and the target image in one build step: +```terraform +# docker-bake.hcl +target "base" { + dockerfile = "baseapp.Dockerfile" +} + +target "app" { + contexts = { + baseapp = "target:base" + } +} +``` + +```yaml + - + name: Build + uses: docker/bake-action@v2 + with: + target: app +``` From 0f5a7d48d5bf7b6abae4f9325152dee483752fd3 Mon Sep 17 00:00:00 2001 From: CrazyMax Date: Fri, 7 Oct 2022 18:20:56 +0200 Subject: [PATCH 2/2] docs: named contexts Signed-off-by: CrazyMax --- README.md | 4 +- docs/advanced/export-docker.md | 76 +------------------------- docs/advanced/named-contexts.md | 95 +++++++++++++++++++++++++++++++++ 3 files changed, 100 insertions(+), 75 deletions(-) create mode 100644 docs/advanced/named-contexts.md diff --git a/README.md b/README.md index adf5a743d..5d80f2f65 100644 --- a/README.md +++ b/README.md @@ -22,12 +22,13 @@ ___ * [Secrets](docs/advanced/secrets.md) * [Isolated builders](docs/advanced/isolated-builders.md) * [Push to multi-registries](docs/advanced/push-multi-registries.md) - * [Copy between registries](docs/advanced/copy-between-registries.md) + * [Copy between registries](docs/advanced/copy-between-registries.md) * [Cache](docs/advanced/cache.md) * [Local registry](docs/advanced/local-registry.md) * [Export image to Docker](docs/advanced/export-docker.md) * [Share built image between jobs](docs/advanced/share-image-jobs.md) * [Test your image before pushing it](docs/advanced/test-before-push.md) + * [Named contexts](docs/advanced/named-contexts.md) * [Handle tags and labels](docs/advanced/tags-labels.md) * [Update DockerHub repo description](docs/advanced/dockerhub-desc.md) * [Customizing](#customizing) @@ -176,6 +177,7 @@ jobs: * [Export image to Docker](docs/advanced/export-docker.md) * [Share built image between jobs](docs/advanced/share-image-jobs.md) * [Test your image before pushing it](docs/advanced/test-before-push.md) +* [Named contexts](docs/advanced/named-contexts.md) * [Handle tags and labels](docs/advanced/tags-labels.md) * [Update DockerHub repo description](docs/advanced/dockerhub-desc.md) diff --git a/docs/advanced/export-docker.md b/docs/advanced/export-docker.md index d2d9c894a..22174a295 100644 --- a/docs/advanced/export-docker.md +++ b/docs/advanced/export-docker.md @@ -1,7 +1,7 @@ # Export image to Docker -You may want your build result to be available in the Docker client through `docker images` to be able to use it -in another step of your workflow: +You may want your build result to be available in the Docker client through +`docker images` to be able to use it in another step of your workflow: ```yaml name: ci @@ -33,75 +33,3 @@ jobs: run: | docker image inspect myimage:latest ``` - - -## Usage of the built image in other build steps - -[By default](https://github.com/docker/setup-buildx-action#customizing), `docker/setup-buildx-action@v2` -uses `docker-container` as a build driver, so the docker images are not available in the builder container. -To use them, you may use [build contexts](https://github.com/docker/buildx/blob/master/docs/reference/buildx_build.md#-additional-build-contexts---build-context): - -```yaml -name: ci - -on: - push: - branches: - - 'main' - -jobs: - docker: - runs-on: ubuntu-latest - steps: - - - name: Checkout - uses: actions/checkout@v3 - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v2 - - - name: Build base image - uses: docker/build-push-action@v3 - with: - context: base - load: true - tags: my-base-image:latest - - - name: Build image from my-base-image:latest - uses: docker/build-push-action@v3 - with: - context: . - build-contexts: | - base-image=docker-image://my-base-image:latest - tags: myimage:latest -``` - -Where `base-image`is the name of the base image (or stage name if specified) in your Dockerfile: -```Dockerfile -FROM base-image -``` - -### Bake alternative - -You may also want to use [bake](https://docs.docker.com/build/bake/build-contexts/#using-a-result-of-one-target-as-a-base-image-in-another-target) -and build the base image and the target image in one build step: -```terraform -# docker-bake.hcl -target "base" { - dockerfile = "baseapp.Dockerfile" -} - -target "app" { - contexts = { - baseapp = "target:base" - } -} -``` - -```yaml - - - name: Build - uses: docker/bake-action@v2 - with: - target: app -``` diff --git a/docs/advanced/named-contexts.md b/docs/advanced/named-contexts.md new file mode 100644 index 000000000..76cf20025 --- /dev/null +++ b/docs/advanced/named-contexts.md @@ -0,0 +1,95 @@ +# Named contexts + +You can define [additional build contexts](https://docs.docker.com/engine/reference/commandline/buildx_build/#build-context) +that can be accessed in your Dockerfile with `FROM name` or `--from=name`. When +Dockerfile defines a stage with the same name it is overwritten. + +This can be useful with GitHub Actions to reuse results from other builds or +pin an image to a spcific tag in your workflow. + +## Pin image to a specific tag + +Replace `alpine:latest` with a pinned one: + +```dockerfile +# syntax=docker/dockerfile:1 +FROM alpine +RUN echo "Hello World" +``` + +```yaml +name: ci + +on: + push: + branches: + - 'main' + +jobs: + docker: + runs-on: ubuntu-latest + steps: + - + name: Checkout + uses: actions/checkout@v3 + - + name: Set up Docker Buildx + uses: docker/setup-buildx-action@v2 + - + name: Build + uses: docker/build-push-action@v3 + with: + context: . + build-contexts: | + alpine=docker-image://alpine:3.16 + tags: myimage:latest +``` + +## Usage of the built image in other build steps + +By default, the [`setup-buildx` action](https://github.com/docker/setup-buildx-action#about) +uses `docker-container` as a build driver, so built Docker images are not +available in the builder container. + +With named contexts you can reuse the built image: + +```dockerfile +# syntax=docker/dockerfile:1 +FROM alpine +RUN echo "Hello World" +``` + +```yaml +name: ci + +on: + push: + branches: + - 'main' + +jobs: + docker: + runs-on: ubuntu-latest + steps: + - + name: Checkout + uses: actions/checkout@v3 + - + name: Set up Docker Buildx + uses: docker/setup-buildx-action@v2 + - + name: Build base image + uses: docker/build-push-action@v3 + with: + context: base + load: true + tags: my-base-image:latest + - + name: Build + uses: docker/build-push-action@v3 + with: + context: . + build-contexts: | + alpine=docker-image://my-base-image:latest + tags: myimage:latest +```