From 1576323820c269c06cd1d370c055ac12895992ad Mon Sep 17 00:00:00 2001
From: ergosteur <1992147+ergosteur@users.noreply.github.com>
Date: Fri, 7 Aug 2026 16:12:20 +0000
Subject: [PATCH] Document what --docker does

The usage line listed --docker but nothing said what it did, so the only way to
find out was to read the runcmd generation.

Two things are worth stating beyond "installs Docker". The install runs on
first boot of each clone rather than during the build, because the snippet is a
runcmd and the template is never booted, so every clone fetches Docker itself
and nothing is baked into the image. And the non-Alpine, non-Arch path uses the
convenience script from get.docker.com, so those guests get Docker CE from
Docker's repo rather than the distro package.

Also records that the cloud-init user lands in the docker group, which is
root-equivalent on that guest, and that the flag is positional.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 README.md                   | 18 +++++++++++++++---
 build-cloudinit-template.sh | 10 ++++++++++
 2 files changed, 25 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 1460c83..d9ae9f3 100644
--- a/README.md
+++ b/README.md
@@ -17,13 +17,25 @@ sudo ./build-cloudinit-template.sh <VMID> <alpine|ubuntu|debian|fedora|almalinux
 
 It downloads the cloud image (cached under `/var/tmp/pve-cloudinit-images`),
 imports it, generates a cloud-init vendor snippet that installs the QEMU guest
-agent and optionally Docker, then converts the VM to a template. Storage,
-bridge, memory, cores, disk size, SSH keys and the cloud-init password are all
-overridable by environment variable; run with `--help` for the full list.
+agent, then converts the VM to a template. Storage, bridge, memory, cores, disk
+size, SSH keys and the cloud-init password are all overridable by environment
+variable; run with `--help` for the full list.
 
 The snippet storage must have the **Snippets** content type enabled, which is
 off by default. The script checks this up front rather than failing later.
 
+`--docker`, which must be the third argument, adds a Docker install to the
+snippet, suffixes the template name with `-docker` and tags it `docker`. Alpine
+and Arch use their own packages; the others use the convenience script from
+`get.docker.com`, so they get Docker CE rather than the distro build. The
+cloud-init user is added to the `docker` group, which is root-equivalent on
+that guest.
+
+Note that the install happens on first boot of each *clone*, not during the
+build — the snippet is a `runcmd` and the template itself is never booted. Each
+clone therefore fetches Docker itself and reboots once. Nothing is baked into
+the template image.
+
 ### Version pins
 
 The distributions fall into two groups, which is the thing worth understanding
diff --git a/build-cloudinit-template.sh b/build-cloudinit-template.sh
index 2f82d3c..6847ff1 100755
--- a/build-cloudinit-template.sh
+++ b/build-cloudinit-template.sh
@@ -4,6 +4,16 @@
 # Usage:
 #   ./build-cloudinit-template.sh <VMID> <alpine|ubuntu|debian|fedora|almalinux|arch> [--docker]
 #
+# --docker adds a Docker install to the cloud-init snippet, names the template
+# with a -docker suffix and tags it "docker". Alpine and Arch use their own
+# packages; the rest use Docker's convenience script from get.docker.com, so
+# they get Docker CE rather than the distro build. The cloud-init user is added
+# to the docker group, which is root-equivalent on that guest.
+#
+# The install runs on first boot of each clone, not while building: the snippet
+# is a runcmd and the template is never booted. So every clone fetches Docker
+# itself, and the template stays generic. It must be the third argument.
+#
 # Optional overrides (env vars):
 #   STORAGE          Proxmox storage pool for disks   (default: local-btrfs)
 #   SNIPPET_STORAGE  Storage holding cloud-init snippets, must have the