From 653cdd7f8a385504edc81479ce4dd0f1132b42b6 Mon Sep 17 00:00:00 2001
From: Junhao Liao <junhao@junhao.ca>
Date: Thu, 25 Sep 2025 15:03:11 -0400
Subject: [PATCH 01/14] feat(docker): Generate unique identifier for each
 clp-package dev image build.

---
 taskfiles/docker-images.yaml             |  1 +
 tools/docker-images/clp-package/build.sh | 17 ++++++++++++++++-
 2 files changed, 17 insertions(+), 1 deletion(-)

diff --git a/taskfiles/docker-images.yaml b/taskfiles/docker-images.yaml
index 9a546f713c..c3e6ca57b5 100644
--- a/taskfiles/docker-images.yaml
+++ b/taskfiles/docker-images.yaml
@@ -12,3 +12,4 @@ tasks:
       - ":package"
     cmds:
       - "./build.sh"
+      - "rsync -a 'image.id' '{{.G_PACKAGE_BUILD_DIR}}'"
diff --git a/tools/docker-images/clp-package/build.sh b/tools/docker-images/clp-package/build.sh
index 39df1a1105..f44e40bc1e 100755
--- a/tools/docker-images/clp-package/build.sh
+++ b/tools/docker-images/clp-package/build.sh
@@ -4,11 +4,26 @@ set -eu
 set -o pipefail
 
 script_dir="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
+iid_file="${script_dir}/image.id"
 repo_root=${script_dir}/../../../
 
+# Remove the previous image after the build to allow layer reuse.
+prev_image_id=""
+if [[ -f "$iid_file" ]]; then
+    prev_image_id=$(cat "$iid_file")
+fi
+cleanup() {
+    if [[ -n "$prev_image_id" ]] && docker image inspect "$prev_image_id" >/dev/null 2>&1; then
+        echo "Removing previous image $prev_image_id"
+        docker image remove "$prev_image_id"
+    fi
+}
+trap cleanup EXIT
+
 build_cmd=(
     docker build
-    --tag "clp-package:dev"
+    --iidfile "$iid_file"
+    --tag "clp-package:dev-${USER}-$(date +%s)"
     "$repo_root"
     --file "${script_dir}/Dockerfile"
 )

From 0c8c69937b98c40f8e6e3e7c59b03cdecfca1ab9 Mon Sep 17 00:00:00 2001
From: Junhao Liao <junhao@junhao.ca>
Date: Thu, 25 Sep 2025 15:45:35 -0400
Subject: [PATCH 02/14] update inline doc about image reuse for clarity

---
 tools/docker-images/clp-package/build.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tools/docker-images/clp-package/build.sh b/tools/docker-images/clp-package/build.sh
index f44e40bc1e..590b35a086 100755
--- a/tools/docker-images/clp-package/build.sh
+++ b/tools/docker-images/clp-package/build.sh
@@ -7,7 +7,7 @@ script_dir="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
 iid_file="${script_dir}/image.id"
 repo_root=${script_dir}/../../../
 
-# Remove the previous image after the build to allow layer reuse.
+# Remove the previous image to save space, but only after the build so its contents can be reused.
 prev_image_id=""
 if [[ -f "$iid_file" ]]; then
     prev_image_id=$(cat "$iid_file")

From d79cb5fa2b3cbc2aeedd45949c70d86b9ea88411 Mon Sep 17 00:00:00 2001
From: Junhao Liao <junhao@junhao.ca>
Date: Fri, 26 Sep 2025 04:20:15 -0400
Subject: [PATCH 03/14] refactor(docker): update clp-package build script to
 modify image ID file path.

---
 taskfiles/docker-images.yaml             | 2 +-
 tools/docker-images/clp-package/build.sh | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/taskfiles/docker-images.yaml b/taskfiles/docker-images.yaml
index c3e6ca57b5..1d723518c2 100644
--- a/taskfiles/docker-images.yaml
+++ b/taskfiles/docker-images.yaml
@@ -12,4 +12,4 @@ tasks:
       - ":package"
     cmds:
       - "./build.sh"
-      - "rsync -a 'image.id' '{{.G_PACKAGE_BUILD_DIR}}'"
+      - "rsync -a '{{.G_BUILD_DIR}}/clp-package-image.id' '{{.G_PACKAGE_BUILD_DIR}}'"
diff --git a/tools/docker-images/clp-package/build.sh b/tools/docker-images/clp-package/build.sh
index 590b35a086..28186ce9bc 100755
--- a/tools/docker-images/clp-package/build.sh
+++ b/tools/docker-images/clp-package/build.sh
@@ -4,8 +4,8 @@ set -eu
 set -o pipefail
 
 script_dir="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
-iid_file="${script_dir}/image.id"
 repo_root=${script_dir}/../../../
+iid_file="${repo_root}/build/clp-package-image.id"
 
 # Remove the previous image to save space, but only after the build so its contents can be reused.
 prev_image_id=""

From e0dc40fff16cba15e69e9edf6546cf2406c1227b Mon Sep 17 00:00:00 2001
From: Junhao Liao <junhao.liao@yscope.com>
Date: Fri, 26 Sep 2025 18:00:57 -0400
Subject: [PATCH 04/14] Use `<` operator instead of `cat` for reading file -
 Apply suggestions from code review

Co-authored-by: kirkrodrigues <2454684+kirkrodrigues@users.noreply.github.com>
---
 tools/docker-images/clp-package/build.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tools/docker-images/clp-package/build.sh b/tools/docker-images/clp-package/build.sh
index 28186ce9bc..17e18d7ea1 100755
--- a/tools/docker-images/clp-package/build.sh
+++ b/tools/docker-images/clp-package/build.sh
@@ -10,7 +10,7 @@ iid_file="${repo_root}/build/clp-package-image.id"
 # Remove the previous image to save space, but only after the build so its contents can be reused.
 prev_image_id=""
 if [[ -f "$iid_file" ]]; then
-    prev_image_id=$(cat "$iid_file")
+    prev_image_id=$(<"$iid_file")
 fi
 cleanup() {
     if [[ -n "$prev_image_id" ]] && docker image inspect "$prev_image_id" >/dev/null 2>&1; then

From ec09d98d9de0c37bccaebf65ce18a1e3afa3d17f Mon Sep 17 00:00:00 2001
From: Junhao Liao <junhao.liao@yscope.com>
Date: Fri, 26 Sep 2025 18:01:46 -0400
Subject: [PATCH 05/14] Add period in removing image prompt - Apply suggestions
 from code review

Co-authored-by: kirkrodrigues <2454684+kirkrodrigues@users.noreply.github.com>
---
 tools/docker-images/clp-package/build.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tools/docker-images/clp-package/build.sh b/tools/docker-images/clp-package/build.sh
index 17e18d7ea1..94e36c9629 100755
--- a/tools/docker-images/clp-package/build.sh
+++ b/tools/docker-images/clp-package/build.sh
@@ -14,7 +14,7 @@ if [[ -f "$iid_file" ]]; then
 fi
 cleanup() {
     if [[ -n "$prev_image_id" ]] && docker image inspect "$prev_image_id" >/dev/null 2>&1; then
-        echo "Removing previous image $prev_image_id"
+        echo "Removing previous image $prev_image_id."
         docker image remove "$prev_image_id"
     fi
 }

From a2a8f0800c84596f7dab1a1241c1209eb02b0ee2 Mon Sep 17 00:00:00 2001
From: Junhao Liao <junhao@junhao.ca>
Date: Fri, 26 Sep 2025 18:57:03 -0400
Subject: [PATCH 06/14] move remove_prev_image() to the top

---
 tools/docker-images/clp-package/build.sh | 17 +++++++++--------
 1 file changed, 9 insertions(+), 8 deletions(-)

diff --git a/tools/docker-images/clp-package/build.sh b/tools/docker-images/clp-package/build.sh
index 94e36c9629..77998dc4d5 100755
--- a/tools/docker-images/clp-package/build.sh
+++ b/tools/docker-images/clp-package/build.sh
@@ -3,22 +3,23 @@
 set -eu
 set -o pipefail
 
+# Remove the previous image only after the build so its contents can be reused.
+remove_prev_image() {
+    if [[ -n "$prev_image_id" ]] && docker image inspect "$prev_image_id" >/dev/null 2>&1; then
+        echo "Removing previous image $prev_image_id."
+        docker image remove "$prev_image_id"
+    fi
+}
+trap remove_prev_image EXIT
+
 script_dir="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
 repo_root=${script_dir}/../../../
 iid_file="${repo_root}/build/clp-package-image.id"
 
-# Remove the previous image to save space, but only after the build so its contents can be reused.
 prev_image_id=""
 if [[ -f "$iid_file" ]]; then
     prev_image_id=$(<"$iid_file")
 fi
-cleanup() {
-    if [[ -n "$prev_image_id" ]] && docker image inspect "$prev_image_id" >/dev/null 2>&1; then
-        echo "Removing previous image $prev_image_id."
-        docker image remove "$prev_image_id"
-    fi
-}
-trap cleanup EXIT
 
 build_cmd=(
     docker build

From 7a05377dd4c46288964ba11ca80f0a80451617e1 Mon Sep 17 00:00:00 2001
From: Junhao Liao <junhao.liao@yscope.com>
Date: Sun, 28 Sep 2025 22:41:04 -0400
Subject: [PATCH 07/14] Remove the command that copies the image id into the
 package - Apply suggestions from code review

---
 taskfiles/docker-images.yaml | 1 -
 1 file changed, 1 deletion(-)

diff --git a/taskfiles/docker-images.yaml b/taskfiles/docker-images.yaml
index 1d723518c2..9a546f713c 100644
--- a/taskfiles/docker-images.yaml
+++ b/taskfiles/docker-images.yaml
@@ -12,4 +12,3 @@ tasks:
       - ":package"
     cmds:
       - "./build.sh"
-      - "rsync -a '{{.G_BUILD_DIR}}/clp-package-image.id' '{{.G_PACKAGE_BUILD_DIR}}'"

From be5a5175d9b0e9918bbda233f2b5817c0db6181e Mon Sep 17 00:00:00 2001
From: Junhao Liao <junhao@junhao.ca>
Date: Mon, 29 Sep 2025 13:09:13 -0400
Subject: [PATCH 08/14] refactor(docker): Improve clp-package image cleanup and
 tagging logic.

---
 tools/docker-images/clp-package/build.sh | 35 ++++++++++++++++--------
 1 file changed, 24 insertions(+), 11 deletions(-)

diff --git a/tools/docker-images/clp-package/build.sh b/tools/docker-images/clp-package/build.sh
index 77998dc4d5..f96d8fc0e2 100755
--- a/tools/docker-images/clp-package/build.sh
+++ b/tools/docker-images/clp-package/build.sh
@@ -3,15 +3,6 @@
 set -eu
 set -o pipefail
 
-# Remove the previous image only after the build so its contents can be reused.
-remove_prev_image() {
-    if [[ -n "$prev_image_id" ]] && docker image inspect "$prev_image_id" >/dev/null 2>&1; then
-        echo "Removing previous image $prev_image_id."
-        docker image remove "$prev_image_id"
-    fi
-}
-trap remove_prev_image EXIT
-
 script_dir="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
 repo_root=${script_dir}/../../../
 iid_file="${repo_root}/build/clp-package-image.id"
@@ -21,10 +12,23 @@ if [[ -f "$iid_file" ]]; then
     prev_image_id=$(<"$iid_file")
 fi
 
+temp_iid_file="$(mktemp)"
+new_image_id=""
+
+remove_prev_image() {
+    if [[ -n "$prev_image_id" && "$prev_image_id" != "$new_image_id" ]]; then
+        if docker image inspect "$prev_image_id" >/dev/null 2>&1; then
+            echo "Removing previous image $prev_image_id."
+            docker image remove "$prev_image_id"
+        fi
+    fi
+    rm -f "$temp_iid_file"
+}
+trap remove_prev_image EXIT
+
 build_cmd=(
     docker build
-    --iidfile "$iid_file"
-    --tag "clp-package:dev-${USER}-$(date +%s)"
+    --iidfile "$temp_iid_file"
     "$repo_root"
     --file "${script_dir}/Dockerfile"
 )
@@ -38,3 +42,12 @@ then
 fi
 
 "${build_cmd[@]}"
+
+if [[ -s "$temp_iid_file" ]]; then
+    new_image_id=$(<"$temp_iid_file")
+    echo "$new_image_id" > "$iid_file"
+
+    short_id=${new_image_id#sha256:}
+    short_id=${short_id:0:4}
+    docker tag "$new_image_id" "clp-package:dev-${USER}-${short_id}"
+fi

From aa4919f3298897ef47dc0fecdf5f0c1c83717991 Mon Sep 17 00:00:00 2001
From: Junhao Liao <junhao@junhao.ca>
Date: Mon, 29 Sep 2025 18:37:06 -0400
Subject: [PATCH 09/14] rename remove_prev_image ->
 remove_prev_image_and_temp_file; move remove_prev_image_and_temp_file to the
 top of the script.

---
 tools/docker-images/clp-package/build.sh | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/tools/docker-images/clp-package/build.sh b/tools/docker-images/clp-package/build.sh
index f96d8fc0e2..d21a1086df 100755
--- a/tools/docker-images/clp-package/build.sh
+++ b/tools/docker-images/clp-package/build.sh
@@ -3,6 +3,17 @@
 set -eu
 set -o pipefail
 
+remove_prev_image_and_temp_file() {
+    if [[ -n "$prev_image_id" && "$prev_image_id" != "$new_image_id" ]]; then
+        if docker image inspect "$prev_image_id" >/dev/null 2>&1; then
+            echo "Removing previous image $prev_image_id."
+            docker image remove "$prev_image_id"
+        fi
+    fi
+    rm -f "$temp_iid_file"
+}
+trap remove_prev_image_and_temp_file EXIT
+
 script_dir="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
 repo_root=${script_dir}/../../../
 iid_file="${repo_root}/build/clp-package-image.id"
@@ -15,17 +26,6 @@ fi
 temp_iid_file="$(mktemp)"
 new_image_id=""
 
-remove_prev_image() {
-    if [[ -n "$prev_image_id" && "$prev_image_id" != "$new_image_id" ]]; then
-        if docker image inspect "$prev_image_id" >/dev/null 2>&1; then
-            echo "Removing previous image $prev_image_id."
-            docker image remove "$prev_image_id"
-        fi
-    fi
-    rm -f "$temp_iid_file"
-}
-trap remove_prev_image EXIT
-
 build_cmd=(
     docker build
     --iidfile "$temp_iid_file"

From c9d9959c920ac38155287147e5353d14db243c2b Mon Sep 17 00:00:00 2001
From: Junhao Liao <junhao@junhao.ca>
Date: Mon, 29 Sep 2025 20:46:20 -0400
Subject: [PATCH 10/14] docs: add docker version requirements into the dev
 docs.

---
 docs/src/dev-docs/building-package.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/docs/src/dev-docs/building-package.md b/docs/src/dev-docs/building-package.md
index 13777691cd..2964063a4e 100644
--- a/docs/src/dev-docs/building-package.md
+++ b/docs/src/dev-docs/building-package.md
@@ -10,6 +10,11 @@ prebuilt version instead, check out the [releases](https://github.com/y-scope/cl
     environment.
   * It should be possible to build a package for a different environment, it just requires a some
     extra configuration.
+* [Docker]
+  * `containerd.io` >= 1.7.18
+  * `docker-buildx-plugin` >= 0.15.1
+  * `docker-ce` >= 27.0.3
+  * `docker-ce-cli` >= 27.0.3
 * Python 3.9 or newer
 * python3-dev
 * python3-venv (for the version of Python installed)
@@ -80,6 +85,7 @@ task docker-images:package
 
 This will create a Docker image named `clp-package:dev`.
 
+[Docker]: https://docs.docker.com/engine/install/
 [Task]: https://taskfile.dev/
 [uv]: https://docs.astral.sh/uv/
 [y-scope/clp#1352]: https://github.com/y-scope/clp/issues/1352

From 074650c447c45706470de3809551c568cf28e7e5 Mon Sep 17 00:00:00 2001
From: Junhao Liao <junhao@junhao.ca>
Date: Mon, 29 Sep 2025 20:59:23 -0400
Subject: [PATCH 11/14] refactor(docker): Use fallback user variable for dev
 image tagging.

---
 tools/docker-images/clp-package/build.sh | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/tools/docker-images/clp-package/build.sh b/tools/docker-images/clp-package/build.sh
index d21a1086df..35ca85af6b 100755
--- a/tools/docker-images/clp-package/build.sh
+++ b/tools/docker-images/clp-package/build.sh
@@ -47,7 +47,8 @@ if [[ -s "$temp_iid_file" ]]; then
     new_image_id=$(<"$temp_iid_file")
     echo "$new_image_id" > "$iid_file"
 
+    user="${USER:-$(id -un 2>/dev/null || whoami 2>/dev/null || echo unknown)}"
     short_id=${new_image_id#sha256:}
     short_id=${short_id:0:4}
-    docker tag "$new_image_id" "clp-package:dev-${USER}-${short_id}"
+    docker tag "$new_image_id" "clp-package:dev-${user}-${short_id}"
 fi

From 2b73559f9b74e41b67021a30187a61fda67fb2ce Mon Sep 17 00:00:00 2001
From: Junhao Liao <junhao@junhao.ca>
Date: Mon, 29 Sep 2025 22:13:54 -0400
Subject: [PATCH 12/14] reformat

---
 tools/docker-images/clp-package/build.sh | 25 ++++++++++++------------
 1 file changed, 13 insertions(+), 12 deletions(-)

diff --git a/tools/docker-images/clp-package/build.sh b/tools/docker-images/clp-package/build.sh
index 35ca85af6b..226deee42f 100755
--- a/tools/docker-images/clp-package/build.sh
+++ b/tools/docker-images/clp-package/build.sh
@@ -4,18 +4,19 @@ set -eu
 set -o pipefail
 
 remove_prev_image_and_temp_file() {
-    if [[ -n "$prev_image_id" && "$prev_image_id" != "$new_image_id" ]]; then
-        if docker image inspect "$prev_image_id" >/dev/null 2>&1; then
-            echo "Removing previous image $prev_image_id."
-            docker image remove "$prev_image_id"
-        fi
-    fi
     rm -f "$temp_iid_file"
+
+    [[ -z "$prev_image_id" || "$prev_image_id" == "$new_image_id" ]] && return
+
+    if docker image inspect "$prev_image_id" >/dev/null 2>&1; then
+        echo "Removing previous image $prev_image_id."
+        docker image remove "$prev_image_id"
+    fi
 }
 trap remove_prev_image_and_temp_file EXIT
 
-script_dir="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
-repo_root=${script_dir}/../../../
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" &> /dev/null && pwd)"
+repo_root="${script_dir}/../../../"
 iid_file="${repo_root}/build/clp-package-image.id"
 
 prev_image_id=""
@@ -33,7 +34,7 @@ build_cmd=(
     --file "${script_dir}/Dockerfile"
 )
 
-if command -v git >/dev/null && git -C "$script_dir" rev-parse --is-inside-work-tree >/dev/null ;
+if command -v git >/dev/null && git -C "$script_dir" rev-parse --is-inside-work-tree >/dev/null;
 then
     build_cmd+=(
         --label "org.opencontainers.image.revision=$(git -C "$script_dir" rev-parse HEAD)"
@@ -44,11 +45,11 @@ fi
 "${build_cmd[@]}"
 
 if [[ -s "$temp_iid_file" ]]; then
-    new_image_id=$(<"$temp_iid_file")
+    new_image_id="$(<"$temp_iid_file")"
     echo "$new_image_id" > "$iid_file"
 
     user="${USER:-$(id -un 2>/dev/null || whoami 2>/dev/null || echo unknown)}"
-    short_id=${new_image_id#sha256:}
-    short_id=${short_id:0:4}
+    short_id="${new_image_id#sha256:}"
+    short_id="${short_id:0:4}"
     docker tag "$new_image_id" "clp-package:dev-${user}-${short_id}"
 fi

From fba7d3bf3b96429a3c3bef7a52ed9e8bfd727a57 Mon Sep 17 00:00:00 2001
From: Junhao Liao <junhao@junhao.ca>
Date: Mon, 29 Sep 2025 22:15:22 -0400
Subject: [PATCH 13/14] rename remove_prev_image_and_temp_file ->
 remove_temp_file_and_prev_image

---
 tools/docker-images/clp-package/build.sh | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/tools/docker-images/clp-package/build.sh b/tools/docker-images/clp-package/build.sh
index 226deee42f..cdf565b29b 100755
--- a/tools/docker-images/clp-package/build.sh
+++ b/tools/docker-images/clp-package/build.sh
@@ -3,7 +3,7 @@
 set -eu
 set -o pipefail
 
-remove_prev_image_and_temp_file() {
+remove_temp_file_and_prev_image() {
     rm -f "$temp_iid_file"
 
     [[ -z "$prev_image_id" || "$prev_image_id" == "$new_image_id" ]] && return
@@ -13,7 +13,7 @@ remove_prev_image_and_temp_file() {
         docker image remove "$prev_image_id"
     fi
 }
-trap remove_prev_image_and_temp_file EXIT
+trap remove_temp_file_and_prev_image EXIT
 
 script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" &> /dev/null && pwd)"
 repo_root="${script_dir}/../../../"

From c778427ec22bf11978d9a7b68bfbc1f4a8f43ba4 Mon Sep 17 00:00:00 2001
From: Junhao Liao <junhao@junhao.ca>
Date: Mon, 29 Sep 2025 22:17:33 -0400
Subject: [PATCH 14/14] revert spaces

---
 tools/docker-images/clp-package/build.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tools/docker-images/clp-package/build.sh b/tools/docker-images/clp-package/build.sh
index cdf565b29b..a7d19d997a 100755
--- a/tools/docker-images/clp-package/build.sh
+++ b/tools/docker-images/clp-package/build.sh
@@ -15,7 +15,7 @@ remove_temp_file_and_prev_image() {
 }
 trap remove_temp_file_and_prev_image EXIT
 
-script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" &> /dev/null && pwd)"
+script_dir="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
 repo_root="${script_dir}/../../../"
 iid_file="${repo_root}/build/clp-package-image.id"