From 86f43c11f1c93f40aa315612f25cc3cb6bf20455 Mon Sep 17 00:00:00 2001
From: CrazyMax <crazy-max@users.noreply.github.com>
Date: Sun, 18 Sep 2022 00:24:58 +0200
Subject: [PATCH] update and split docs
Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>
---
README.md | 208 +++++--------------------------
docs/advanced/buildkit-config.md | 67 ++++++++++
docs/advanced/install-default.md | 28 +++++
docs/advanced/standalone.md | 29 +++++
4 files changed, 154 insertions(+), 178 deletions(-)
create mode 100644 docs/advanced/buildkit-config.md
create mode 100644 docs/advanced/install-default.md
create mode 100644 docs/advanced/standalone.md
diff --git a/README.md b/README.md
index 4f59763..1d05d9b 100644
--- a/README.md
+++ b/README.md
@@ -8,23 +8,21 @@
GitHub Action to set up Docker [Buildx](https://github.com/docker/buildx).
-This action will create and boot a builder that can be used in the following steps of your workflow if you're using
-[buildx](https://github.com/docker/buildx). By default, the `docker-container` [builder driver](https://github.com/docker/buildx/blob/master/docs/reference/buildx_create.md#driver)
-will be used to be able to build multi-platform images and export cache thanks to the [BuildKit](https://github.com/moby/buildkit)
-container.
+This action will create and boot a builder that can be used in the following
+steps of your workflow if you're using Buildx or the [`build-push` action](https://github.com/docker/build-push-action/).
+By default, the [`docker-container` driver](https://docs.docker.com/build/building/drivers/docker-container/)
+will be used to be able to build multi-platform images and export cache using
+a [BuildKit](https://github.com/moby/buildkit) container.
___
* [Usage](#usage)
- * [Quick start](#quick-start)
- * [With QEMU](#with-qemu)
- * [Install by default](#install-by-default)
- * [BuildKit daemon configuration](#buildkit-daemon-configuration)
- * [Registry mirror](#registry-mirror)
- * [Max parallelism](#max-parallelism)
- * [Standalone mode](#standalone-mode)
+* [Advanced usage](#advanced-usage)
+ * [Install by default](docs/advanced/install-default.md)
+ * [BuildKit daemon configuration](docs/advanced/buildkit-config.md)
+ * [Standalone mode](docs/advanced/standalone.md)
* [Customizing](#customizing)
* [inputs](#inputs)
* [outputs](#outputs)
@@ -35,39 +33,6 @@ ___
## Usage
-### Quick start
-
-```yaml
-name: ci
-
-on:
- push:
-
-jobs:
- buildx:
- runs-on: ubuntu-latest
- steps:
- -
- name: Checkout
- uses: actions/checkout@v3
- -
- name: Set up Docker Buildx
- id: buildx
- uses: docker/setup-buildx-action@v2
- -
- name: Inspect builder
- run: |
- echo "Name: ${{ steps.buildx.outputs.name }}"
- echo "Endpoint: ${{ steps.buildx.outputs.endpoint }}"
- echo "Status: ${{ steps.buildx.outputs.status }}"
- echo "Flags: ${{ steps.buildx.outputs.flags }}"
- echo "Platforms: ${{ steps.buildx.outputs.platforms }}"
-```
-
-### With QEMU
-
-If you want support for more platforms you can use our [setup-qemu](https://github.com/docker/setup-qemu-action) action:
-
```yaml
name: ci
@@ -82,133 +47,20 @@ jobs:
name: Checkout
uses: actions/checkout@v3
-
+ # Add support for more platforms with QEMU (optional)
+ # https://github.com/docker/setup-qemu-action
name: Set up QEMU
uses: docker/setup-qemu-action@v2
-
name: Set up Docker Buildx
- id: buildx
uses: docker/setup-buildx-action@v2
- -
- name: Available platforms
- run: echo ${{ steps.buildx.outputs.platforms }}
```
-### Install by default
+## Advanced usage
-If you want set up the `docker build` command as an alias to `docker buildx build`:
-
-```yaml
-name: ci
-
-on:
- push:
-
-jobs:
- buildx:
- runs-on: ubuntu-latest
- steps:
- -
- name: Checkout
- uses: actions/checkout@v3
- -
- uses: docker/setup-buildx-action@v2
- id: buildx
- with:
- install: true
- -
- name: Build
- run: |
- docker build . # will run buildx
-```
-
-### BuildKit daemon configuration
-
-You can provide a [BuildKit configuration](https://github.com/moby/buildkit/blob/master/docs/buildkitd.toml.md)
-to your builder if you're using the [`docker-container` driver](https://github.com/docker/buildx/blob/master/docs/reference/buildx_create.md#driver)
-(default) with the `config` or `config-inline` inputs:
-
-#### Registry mirror
-
-You can configure a registry mirror using an inline block directly in your
-workflow with the `config-inline` input:
-
-```yaml
-name: ci
-
-on:
- push:
-
-jobs:
- buildx:
- runs-on: ubuntu-latest
- steps:
- -
- name: Set up Docker Buildx
- uses: docker/setup-buildx-action@v2
- with:
- config-inline: |
- [registry."docker.io"]
- mirrors = ["mirror.gcr.io"]
-```
-
-#### Max parallelism
-
-You can limit the parallelism of the BuildKit solver which is particularly
-useful for low-powered machines.
-
-You can use the `config-inline` input like the
-previous example, or you can use a dedicated BuildKit config file from your
-repo if you want with the `config` input:
-
-```toml
-# .github/buildkitd.toml
-[worker.oci]
- max-parallelism = 4
-```
-
-```yaml
-name: ci
-
-on:
- push:
-
-jobs:
- buildx:
- runs-on: ubuntu-latest
- steps:
- -
- name: Set up Docker Buildx
- uses: docker/setup-buildx-action@v2
- with:
- config: .github/buildkitd.toml
-```
-
-### Standalone mode
-
-If you don't have the Docker CLI installed on the GitHub Runner, buildx binary
-is invoked directly, instead of calling it as a docker plugin. This can be
-useful if you want to use the `kubernetes` driver in your self-hosted runner:
-
-```yaml
-name: ci
-
-on:
- push:
-
-jobs:
- buildx:
- runs-on: ubuntu-latest
- steps:
- -
- name: Set up Docker Buildx
- uses: docker/setup-buildx-action@v2
- with:
- driver: kubernetes
- -
- name: Build
- run: |
- buildx build .
-```
+* [Install by default](docs/advanced/install-default.md)
+* [BuildKit daemon configuration](docs/advanced/buildkit-config.md)
+* [Standalone mode](docs/advanced/standalone.md)
## Customizing
@@ -216,17 +68,17 @@ jobs:
Following inputs can be used as `step.with` keys
-| Name | Type | Description |
-|--------------------|---------|-----------------------------------|
-| `version` | String | [buildx](https://github.com/docker/buildx) version. (eg. `v0.3.0`, `latest`, `https://github.com/docker/buildx.git#master`) |
-| `driver` | String | Sets the [builder driver](https://github.com/docker/buildx/blob/master/docs/reference/buildx_create.md#driver) to be used (default `docker-container`) |
-| `driver-opts` | CSV | List of additional [driver-specific options](https://github.com/docker/buildx/blob/master/docs/reference/buildx_create.md#driver-opt) (eg. `image=moby/buildkit:master`) |
-| `buildkitd-flags` | String | [Flags for buildkitd](https://github.com/moby/buildkit/blob/master/docs/buildkitd.toml.md) daemon (since [buildx v0.3.0](https://github.com/docker/buildx/releases/tag/v0.3.0)) |
-| `install` | Bool | Sets up `docker build` command as an alias to `docker buildx` (default `false`) |
-| `use` | Bool | Switch to this builder instance (default `true`) |
-| `endpoint` | String | [Optional address for docker socket](https://github.com/docker/buildx/blob/master/docs/reference/buildx_create.md#description) or context from `docker context ls` |
-| `config`¹ | String | [BuildKit config file](https://github.com/docker/buildx/blob/master/docs/reference/buildx_create.md#config) |
-| `config-inline`¹ | String | Same as `config` but inline |
+| Name | Type | Description |
+|-------------------|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `version` | String | [Buildx](https://github.com/docker/buildx) version. (eg. `v0.3.0`, `latest`, `https://github.com/docker/buildx.git#master`) |
+| `driver` | String | Sets the [builder driver](https://docs.docker.com/engine/reference/commandline/buildx_create/#driver) to be used (default `docker-container`) |
+| `driver-opts` | CSV | List of additional [driver-specific options](https://docs.docker.com/engine/reference/commandline/buildx_create/#driver-opt) (eg. `image=moby/buildkit:master`) |
+| `buildkitd-flags` | String | [Flags for buildkitd](https://docs.docker.com/engine/reference/commandline/buildx_create/#buildkitd-flags) daemon (since [buildx v0.3.0](https://github.com/docker/buildx/releases/tag/v0.3.0)) |
+| `install` | Bool | Sets up `docker build` command as an alias to `docker buildx` (default `false`) |
+| `use` | Bool | Switch to this builder instance (default `true`) |
+| `endpoint` | String | [Optional address for docker socket](https://docs.docker.com/engine/reference/commandline/buildx_create/#description) or context from `docker context ls` |
+| `config`¹ | String | [BuildKit config file](https://docs.docker.com/engine/reference/commandline/buildx_create/#config) |
+| `config-inline`¹ | String | Same as `config` but inline |
> * ¹ `config` and `config-inline` are mutually exclusive
@@ -257,15 +109,15 @@ Following outputs are available
The following [official docker environment variables](https://docs.docker.com/engine/reference/commandline/cli/#environment-variables) are supported:
-| Name | Type | Default | Description |
-|-----------------|---------|-------------|-------------------------------------------------|
-| `DOCKER_CONFIG` | String | `~/.docker` | The location of your client configuration files |
+| Name | Type | Default | Description |
+|-----------------|--------|-------------|-------------------------------------------------|
+| `DOCKER_CONFIG` | String | `~/.docker` | The location of your client configuration files |
## Notes
### BuildKit container logs
-To display BuildKit container logs (when `docker-container` driver is used) you have to [enable step debug logging](https://docs.github.com/en/actions/managing-workflow-runs/enabling-debug-logging#enabling-step-debug-logging)
+To display BuildKit container logs (when `docker-container` driver is used) you have to [enable step debug logging](https://docs.github.com/en/actions/managing-workflow-runs/enabling-debug-logging#enabling-step-debug-logging),
or you can also enable debugging in the [setup-buildx action step](https://github.com/docker/setup-buildx-action):
```yaml
diff --git a/docs/advanced/buildkit-config.md b/docs/advanced/buildkit-config.md
new file mode 100644
index 0000000..d552795
--- /dev/null
+++ b/docs/advanced/buildkit-config.md
@@ -0,0 +1,67 @@
+# BuildKit daemon configuration
+
+You can provide a [BuildKit configuration](https://github.com/moby/buildkit/blob/master/docs/buildkitd.toml.md)
+to your builder if you're using the [`docker-container` driver](https://docs.docker.com/build/building/drivers/docker-container/)
+(default) with the `config` or `config-inline` inputs:
+
+## Registry mirror
+
+You can configure a registry mirror using an inline block directly in your
+workflow with the `config-inline` input:
+
+```yaml
+name: ci
+
+on:
+ push:
+
+jobs:
+ buildx:
+ runs-on: ubuntu-latest
+ steps:
+ -
+ name: Checkout
+ uses: actions/checkout@v3
+ -
+ name: Set up Docker Buildx
+ uses: docker/setup-buildx-action@v2
+ with:
+ config-inline: |
+ [registry."docker.io"]
+ mirrors = ["mirror.gcr.io"]
+```
+
+## Max parallelism
+
+You can limit the parallelism of the BuildKit solver which is particularly
+useful for low-powered machines.
+
+You can use the `config-inline` input like the previous example, or you can use
+a dedicated BuildKit config file from your repo if you want with the
+`config` input:
+
+```toml
+# .github/buildkitd.toml
+[worker.oci]
+ max-parallelism = 4
+```
+
+```yaml
+name: ci
+
+on:
+ push:
+
+jobs:
+ buildx:
+ runs-on: ubuntu-latest
+ steps:
+ -
+ name: Checkout
+ uses: actions/checkout@v3
+ -
+ name: Set up Docker Buildx
+ uses: docker/setup-buildx-action@v2
+ with:
+ config: .github/buildkitd.toml
+```
diff --git a/docs/advanced/install-default.md b/docs/advanced/install-default.md
new file mode 100644
index 0000000..ca95d5c
--- /dev/null
+++ b/docs/advanced/install-default.md
@@ -0,0 +1,28 @@
+# Install by default
+
+If you want set up the `docker build` command as an alias to
+`docker buildx build`:
+
+```yaml
+name: ci
+
+on:
+ push:
+
+jobs:
+ buildx:
+ runs-on: ubuntu-latest
+ steps:
+ -
+ name: Checkout
+ uses: actions/checkout@v3
+ -
+ name: Set up Docker Buildx
+ uses: docker/setup-buildx-action@v2
+ with:
+ install: true
+ -
+ name: Build
+ run: |
+ docker build . # will run buildx
+```
diff --git a/docs/advanced/standalone.md b/docs/advanced/standalone.md
new file mode 100644
index 0000000..53abf91
--- /dev/null
+++ b/docs/advanced/standalone.md
@@ -0,0 +1,29 @@
+# Standalone mode
+
+If you don't have the Docker CLI installed on the GitHub Runner, Buildx binary
+is invoked directly, instead of calling it as a docker plugin. This can be
+useful if you want to use the `kubernetes` driver in your self-hosted runner:
+
+```yaml
+name: ci
+
+on:
+ push:
+
+jobs:
+ buildx:
+ runs-on: ubuntu-latest
+ steps:
+ -
+ name: Checkout
+ uses: actions/checkout@v3
+ -
+ name: Set up Docker Buildx
+ uses: docker/setup-buildx-action@v2
+ with:
+ driver: kubernetes
+ -
+ name: Build
+ run: |
+ buildx build .
+```