Enhance documentation

Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>
docker · Feb 17, 2021 · a63b18d · a63b18d
1 parent af867d4
commit a63b18d
Show file tree

Hide file tree

Showing 12 changed files with 594 additions and 499 deletions.
diff --git a/README.md b/README.md
diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md
@@ -59,8 +59,7 @@ jobs:
         uses: docker/build-push-action@v2
         with:
           context: .
-          file: ./Dockerfile
-          platforms: linux/386,linux/amd64,linux/arm/v6,linux/arm/v7,linux/arm64,linux/ppc64le,linux/s390x
+          platforms: linux/amd64,linux/arm64
           tags: docker.io/user/app:latest
           outputs: type=oci,dest=/tmp/image.tar
       -

diff --git a/UPGRADE.md b/UPGRADE.md
@@ -63,7 +63,6 @@ steps:
     uses: docker/build-push-action@v2
     with:
       context: .
-      file: ./Dockerfile
       pull: true
       push: true
       build-args: |
@@ -136,7 +135,6 @@ steps:
     uses: docker/build-push-action@v2
     with:
       context: .
-      file: ./Dockerfile
       push: ${{ github.event_name != 'pull_request' }}
       tags: ${{ steps.prep.outputs.tags }}
       labels: |
@@ -145,5 +143,5 @@ steps:
         org.opencontainers.image.revision=${{ github.sha }}
 ```
 
-> You can also use the [Docker meta action](https://github.com/crazy-max/ghaction-docker-meta) to handle tags and
-> labels based on GitHub actions events and Git metadata. A workflow example is available in the [README](README.md#handle-tags-and-labels).
+> You can also use the [Docker meta action to handle tags and labels](docs/advanced/tags-labels.md) based on GitHub
+> actions events and Git metadata.
diff --git a/docs/advanced/cache.md b/docs/advanced/cache.md
@@ -0,0 +1,107 @@
+# Cache
+
+* [Registry cache](#registry-cache)
+* [GitHub cache](#github-cache)
+
+> More info about buildx cache: https://github.com/docker/buildx#--cache-fromnametypetypekeyvalue
+
+## Registry cache
+
+You can import/export cache from a cache manifest or (special) image configuration on the registry.
+
+```yaml
+name: ci
+
+on:
+  push:
+    branches:
+      - 'master'
+
+jobs:
+  docker:
+    runs-on: ubuntu-latest
+    steps:
+      -
+        name: Checkout
+        uses: actions/checkout@v2
+      -
+        name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v1
+      -
+        name: Login to DockerHub
+        uses: docker/login-action@v1 
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      -
+        name: Build and push
+        uses: docker/build-push-action@v2
+        with:
+          context: .
+          push: true
+          tags: user/app:latest
+          cache-from: type=registry,ref=user/app:latest
+          cache-to: type=inline
+```
+
+## GitHub cache
+
+> :warning: At the moment caches are copied over the existing cache so it [keeps growing](https://github.com/docker/build-push-action/issues/252).
+> The `Move cache` step is used as a temporary fix (see https://github.com/moby/buildkit/issues/1896).
+
+> :rocket: There is a new cache backend using GitHub cache being developed that will lighten your workflow.
+> More info: https://github.com/docker/buildx/pull/535
+
+You can leverage [GitHub cache](https://docs.github.com/en/actions/configuring-and-managing-workflows/caching-dependencies-to-speed-up-workflows)
+using [actions/cache](https://github.com/actions/cache) with this action:
+
+```yaml
+name: ci
+
+on:
+  push:
+    branches:
+      - 'master'
+
+jobs:
+  docker:
+    runs-on: ubuntu-latest
+    steps:
+      -
+        name: Checkout
+        uses: actions/checkout@v2
+      -
+        name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v1
+      -
+        name: Cache Docker layers
+        uses: actions/cache@v2
+        with:
+          path: /tmp/.buildx-cache
+          key: ${{ runner.os }}-buildx-${{ github.sha }}
+          restore-keys: |
+            ${{ runner.os }}-buildx-
+      -
+        name: Login to DockerHub
+        uses: docker/login-action@v1 
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      -
+        name: Build and push
+        uses: docker/build-push-action@v2
+        with:
+          context: .
+          push: true
+          tags: user/app:latest
+          cache-from: type=local,src=/tmp/.buildx-cache
+          cache-to: type=local,dest=/tmp/.buildx-cache-new
+      -
+        # Temp fix
+        # https://github.com/docker/build-push-action/issues/252
+        # https://github.com/moby/buildkit/issues/1896
+        name: Move cache
+        run: |
+          rm -rf /tmp/.buildx-cache
+          mv /tmp/.buildx-cache-new /tmp/.buildx-cache
+```
diff --git a/docs/advanced/dockerhub-desc.md b/docs/advanced/dockerhub-desc.md
@@ -0,0 +1,48 @@
+# Update DockerHub repo description
+
+You can update the [DockerHub repository description](https://docs.docker.com/docker-hub/repos/) using
+a third party action called [DockerHub Description](https://github.com/peter-evans/dockerhub-description)
+with this action:
+
+```yaml
+name: ci
+
+on:
+  push:
+    branches:
+      - 'master'
+
+jobs:
+  docker:
+    runs-on: ubuntu-latest
+    steps:
+      -
+        name: Checkout
+        uses: actions/checkout@v2
+      -
+        name: Set up QEMU
+        uses: docker/setup-qemu-action@v1
+      -
+        name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v1
+      -
+        name: Login to DockerHub
+        uses: docker/login-action@v1 
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      -
+        name: Build and push
+        uses: docker/build-push-action@v2
+        with:
+          context: .
+          push: true
+          tags: user/app:latest
+      -
+        name: Update repo description
+        uses: peter-evans/dockerhub-description@v2
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_PASSWORD }}
+          repository: user/app
+```
diff --git a/docs/advanced/export-docker.md b/docs/advanced/export-docker.md
@@ -0,0 +1,35 @@
+# 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:
+
+```yaml
+name: ci
+
+on:
+  push:
+    branches:
+      - 'master'
+
+jobs:
+  docker:
+    runs-on: ubuntu-latest
+    steps:
+      -
+        name: Checkout
+        uses: actions/checkout@v2
+      -
+        name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v1
+      -
+        name: Build
+        uses: docker/build-push-action@v2
+        with:
+          context: .
+          load: true
+          tags: myimage:latest
+      -
+        name: Inspect
+        run: |
+          docker image inspect myimage:latest
+```
diff --git a/docs/advanced/isolated-builders.md b/docs/advanced/isolated-builders.md
@@ -0,0 +1,44 @@
+# Isolated builders
+
+```yaml
+name: ci
+
+on:
+  push:
+    branches:
+      - 'master'
+
+jobs:
+  docker:
+    runs-on: ubuntu-latest
+    steps:
+      -
+        name: Checkout
+        uses: actions/checkout@v2
+      -
+        uses: docker/setup-buildx-action@v1
+        id: builder1
+      -
+        uses: docker/setup-buildx-action@v1
+        id: builder2
+      -
+        name: Builder 1 name
+        run: echo ${{ steps.builder1.outputs.name }}
+      -
+        name: Builder 2 name
+        run: echo ${{ steps.builder2.outputs.name }}
+      -
+        name: Build against builder1
+        uses: docker/build-push-action@v2
+        with:
+          builder: ${{ steps.builder1.outputs.name }}
+          context: .
+          target: mytarget1
+      -
+        name: Build against builder2
+        uses: docker/build-push-action@v2
+        with:
+          builder: ${{ steps.builder2.outputs.name }}
+          context: .
+          target: mytarget2
+```
diff --git a/docs/advanced/local-registry.md b/docs/advanced/local-registry.md
@@ -0,0 +1,44 @@
+# Local registry
+
+For testing purposes you may need to create a [local registry](https://hub.docker.com/_/registry) to push images into:
+
+```yaml
+name: ci
+
+on:
+  push:
+    branches:
+      - 'master'
+
+jobs:
+  docker:
+    runs-on: ubuntu-latest
+    services:
+      registry:
+        image: registry:2
+        ports:
+          - 5000:5000
+    steps:
+      -
+        name: Checkout
+        uses: actions/checkout@v2
+      -
+        name: Set up QEMU
+        uses: docker/setup-qemu-action@v1
+      -
+        name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v1
+        with:
+          driver-opts: network=host
+      -
+        name: Build and push to local registry
+        uses: docker/build-push-action@v2
+        with:
+          context: .
+          push: true
+          tags: localhost:5000/name/app:latest
+      -
+        name: Inspect
+        run: |
+          docker buildx imagetools inspect localhost:5000/name/app:latest
+```
diff --git a/docs/advanced/multi-platform.md b/docs/advanced/multi-platform.md
@@ -0,0 +1,44 @@
+# Multi-platform image
+
+You can build multi-platform images using the [`platforms` input](../../README.md#inputs) as described below.
+
+> :bulb: List of available platforms will be displayed and available through our [setup-buildx](https://github.com/docker/setup-buildx-action#about) action.
+
+> :bulb: If you want support for more platforms, you can use QEMU with our [setup-qemu](https://github.com/docker/setup-qemu-action) action.
+
+```yaml
+name: ci
+
+on:
+  push:
+    branches:
+      - 'master'
+
+jobs:
+  docker:
+    runs-on: ubuntu-latest
+    steps:
+      -
+        name: Checkout
+        uses: actions/checkout@v2
+      -
+        name: Set up QEMU
+        uses: docker/setup-qemu-action@v1
+      -
+        name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v1
+      -
+        name: Login to DockerHub
+        uses: docker/login-action@v1 
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+      -
+        name: Build and push
+        uses: docker/build-push-action@v2
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: user/app:latest
+```