From e8be67170354be99cab63342412148d0cc4cacb2 Mon Sep 17 00:00:00 2001
From: Carlos Alexandro Becker <caarlos0@users.noreply.github.com>
Date: Thu, 4 May 2023 02:28:12 +0000
Subject: [PATCH] docs: multi platform docker images

closes #3978
---
 .../cookbooks/multi-platform-docker-images.md | 64 +++++++++++++++++++
 www/mkdocs.yml                                |  3 +-
 2 files changed, 66 insertions(+), 1 deletion(-)
 create mode 100644 www/docs/cookbooks/multi-platform-docker-images.md

diff --git a/www/docs/cookbooks/multi-platform-docker-images.md b/www/docs/cookbooks/multi-platform-docker-images.md
new file mode 100644
index 000000000..f010d22c4
--- /dev/null
+++ b/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.
diff --git a/www/mkdocs.yml b/www/mkdocs.yml
index 1f94e1b15..9998222d2 100644
--- a/www/mkdocs.yml
+++ b/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