docs: multi platform docker images

closes #3978

www/docs/cookbooks/multi-platform-docker-images.md

@@ -0,0 +1,64 @@
+# Multi-platform Docker images
+
+On GoReleaser there are two main ways of doing that: the easier one is to use
+the [ko integration][ko].
+
+If you don't want to, or can't, use Ko for whatever reason, this guide is for
+you!
+
+## Creating Multi-platform docker images with GoReleaser
+
+GoReleaser splits the build and publish phase, which makes its usage less
+obvious.
+
+First, you need to define one `dockers` item for each platform you want to
+build. Usually, you would tag it like `myorg/myimage:version-platform`.
+It is also important to use `buildx`. Here's an example:
+
+```yaml
+# .goreleaser.yaml
+dockers:
+- image_templates:
+  - 'myorg/myuser:{{ .Tag }}-amd64'
+  use: buildx
+  build_flag_templates:
+  - "--pull"
+  - "--platform=linux/amd64"
+- image_templates:
+  - 'myorg/myuser:{{ .Tag }}-arm64'
+  use: buildx
+  build_flag_templates:
+  - "--pull"
+  - "--platform=linux/arm64"
+  goarch: arm64
+
+```
+
+This will, on build time, create two Docker images (`myorg/myuser:v1.2.3-amd64`
+and `myorg/myuser:v1.2.3-arm64`).
+
+Now, if we want to make them both available as a single image
+(`myorg/myuser:v1.2.3`), we'll need to add a manifest configuration that will
+publish them behind that single name. Here's how it would look like:
+
+```yaml
+# .goreleaser.yaml
+docker_manifests:
+- name_template: 'myorg/myuser:{{ .Tag }}'
+  image_templates:
+  - 'myorg/myuser:{{ .Tag }}-amd64'
+  - 'myorg/myuser:{{ .Tag }}-arm64'
+```
+
+And that is it!
+
+## Other things to pay attention to
+
+For `buildx` to work properly, you'll need to install `qemu`. On GitHub actions,
+the easiest way is to use
+[docker/setup-qemu-action](https://github.com/docker/setup-qemu-action).
+
+It's also important that the `FROM` in your `Dockerfile` is multi-platform,
+otherwise it'll not work.
+
+As long as you have Qemu and Docker set up, everything should just work.

www/mkdocs.yml

@@ -184,7 +184,8 @@ nav:
   - About: cookbooks/index.md
   - Blog Posts: cookbooks/blog-posts.md
   - Add a new cookbook: cookbooks/contributing.md
-  - cookbooks//build-go-modules.md
+  - cookbooks/multi-platform-docker-images.md
+  - cookbooks/build-go-modules.md
   - cookbooks/cgo-and-crosscompiling.md
   - cookbooks/debconf-templates.md
   - cookbooks/using-jfrog-cli-to-publish-to-artifactory.md