audit: idempotency, hardening, and consistency improvements

.github/workflows/build-caddy.yml

@@ -161,13 +161,13 @@ jobs:
                   echo "Resolving cache-handler HEAD commit..."
                   CACHE_HANDLER_REF="$(
                       retry git ls-remote --heads https://github.com/caddyserver/cache-handler.git \
-                      | awk '/refs\/heads\/master/ {print $1}'
+                      | awk '/refs\/heads\/main/ {print $1}'
                   )"
 
                   echo "Resolving transform-encoder HEAD commit..."
                   TRANSFORM_ENCODER_REF="$(
                       retry git ls-remote --heads https://github.com/caddyserver/transform-encoder.git \
-                      | awk '/refs\/heads\/master/ {print $1}'
+                      | awk '/refs\/heads\/main/ {print $1}'
                   )"
 
                   echo "Resolving caddy-security version..."
@@ -193,11 +193,14 @@ jobs:
                   echo "Resolved fingerprint: ${BUILD_FINGERPRINT}"
 
                   # ── 3c: Compare with published image fingerprint ──
-                  # Authenticate to GHCR with the automatically-provided GITHUB_TOKEN
-                  # before running docker manifest inspect. This ensures the inspect
-                  # succeeds even on the first run (before Step 5 logins), and avoids
-                  # a race condition where the inspect could fail if the image is not
-                  # publicly accessible.
+                  # Pre-authenticate to GHCR using the auto-provided GITHUB_TOKEN
+                  # before running docker manifest inspect. This must happen here
+                  # (Step 3) rather than relying solely on the later docker/login-action
+                  # in Step 5, because Step 5 is conditional on should_build == 'true'.
+                  # Without this pre-auth, manifest inspect would fail on the very first
+                  # run (no published image) or when the package visibility is private,
+                  # causing the fingerprint comparison to silently default to
+                  # 'no-published-image' and trigger unnecessary rebuilds.
                   echo "${{ secrets.GITHUB_TOKEN }}" \
                       | docker login ghcr.io -u "${{ github.actor }}" --password-stdin \
                       2>/dev/null || true
@@ -221,14 +224,22 @@ jobs:
                       CHANGE_SUMMARY="No published image found — performing initial build."
                   elif [[ "${BUILD_FINGERPRINT}" != "${PUBLISHED_FINGERPRINT}" ]]; then
                       SHOULD_BUILD="true"
-                      # Human-readable diff
+                      # Human-readable diff — compare only the parts that are present
+                      # in both fingerprints; guard against unequal part counts (e.g.,
+                      # if a new plugin is added to the fingerprint schema).
                       CHANGE_SUMMARY="Component changes detected:"$'\n'
                       IFS='|' read -ra NEW_PARTS <<< "${BUILD_FINGERPRINT}"
                       IFS='|' read -ra OLD_PARTS <<< "${PUBLISHED_FINGERPRINT}"
-                      for i in "${!NEW_PARTS[@]}"; do
-                          NEW="${NEW_PARTS[$i]}"
+                      NEW_COUNT="${#NEW_PARTS[@]}"
+                      OLD_COUNT="${#OLD_PARTS[@]}"
+                      if [[ "${NEW_COUNT}" != "${OLD_COUNT}" ]]; then
+                          CHANGE_SUMMARY+="  - Fingerprint schema changed: new has ${NEW_COUNT} parts, published has ${OLD_COUNT} parts"$'\n'
+                      fi
+                      MAX_IDX=$(( NEW_COUNT > OLD_COUNT ? NEW_COUNT : OLD_COUNT ))
+                      for (( i=0; i<MAX_IDX; i++ )); do
+                          NEW="${NEW_PARTS[$i]:-MISSING}"
                           OLD="${OLD_PARTS[$i]:-MISSING}"
-                          if [[ "$NEW" != "$OLD" ]]; then
+                          if [[ "${NEW}" != "${OLD}" ]]; then
                               CHANGE_SUMMARY+="  - CHANGED: ${NEW}  (was: ${OLD})"$'\n'
                           fi
                       done
@@ -413,6 +424,14 @@ jobs:
 
             # ──────────────────────────────────────────────────────────
             # STEP 7 — Smoke test and module validation
+            # Module names verified against each upstream's registered caddy
+            # module identifier (as output by `caddy list-modules`):
+            #   docker_proxy              → lucaslorentz/caddy-docker-proxy
+            #   dns.providers.cloudflare  → caddy-dns/cloudflare
+            #   http.ip_sources.cloudflare → WeidiDeng/caddy-cloudflare-ip
+            #   http.handlers.cache       → caddyserver/cache-handler
+            #   caddy.logging.encoders.transform → caddyserver/transform-encoder
+            #   security                  → greenpau/caddy-security
             # ──────────────────────────────────────────────────────────
             - name: Smoke Test and Module Validation
               if: steps.decide.outputs.should_build == 'true'
@@ -570,12 +589,14 @@ jobs:
                   MINOR="$(echo "${VERSION}" | cut -d. -f1-2)"
                   DIGEST="${{ steps.push.outputs.digest }}"
 
-                  # Push semver major/minor tags to GHCR only. DockerHub does not
-                  # enforce tag immutability by default (it is an opt-in paid feature),
-                  # but we intentionally omit these mutable floating tags from DockerHub
-                  # to avoid silently updating images that users may have pinned to "2"
-                  # or "2.11" expecting stability. GHCR users are expected to understand
-                  # the floating-tag contract.
+                  # Semver major/minor (floating) tags are pushed to GHCR only.
+                  # DockerHub tag immutability is an opt-in Enterprise/Teams feature
+                  # and is NOT enabled on the atnplex org. We intentionally omit
+                  # floating tags from DockerHub to avoid silently overwriting a tag
+                  # that users may have pinned expecting it to be stable (e.g.,
+                  # image: atnplex/caddy:2 in a compose file). GHCR users pulling
+                  # floating tags are expected to understand the contract. For fully
+                  # reproducible deployments, always pin to a digest.
                   GHCR_IMAGE="${GHCR_REGISTRY}/${{ github.repository_owner }}/${IMAGE_NAME}"
                   docker buildx imagetools create \
                       --tag "${GHCR_IMAGE}:${MAJOR}" \
@@ -599,6 +620,10 @@ jobs:
 
             # ──────────────────────────────────────────────────────────
             # STEP 11 — Update README badges (always runs)
+            # NOTE: date -d 'next monday' is a GNU coreutils extension.
+            # This step always runs on ubuntu-latest which ships GNU coreutils.
+            # If the runner OS is ever changed (e.g., to macos-latest), replace
+            # `date -d 'next monday'` with a Python/gdate equivalent.
             # ──────────────────────────────────────────────────────────
             - name: Update README Badges
               if: always()
@@ -785,4 +810,3 @@ jobs:
                   docker rmi "caddy-test:${{ github.run_id }}" 2>/dev/null || true
                   docker buildx prune --filter "until=1h" --force 2>/dev/null || true
                   rm -f scout_output.md modules.txt
-

README.md

@@ -116,15 +116,21 @@ labels:
 
 ## Tag Strategy
 
-| Tag | Description |
-|:---|:---|
-| `latest` | Always points to the most recent successful build |
-| `2` · `2.11` · `2.11.2` | Semantic version pins at major / minor / patch |
-| `2.11.2-2026.03.28` | Version + build date for fully reproducible deployments |
-| `sha-abc1234` | Git SHA of the Dockerfile at build time |
-
-For production deployments requiring immutability, use the digest from the
-[Releases](https://github.com/atnplex/caddy/releases) page.
+| Tag | Registry | Description |
+|:---|:---|:---|
+| `latest` | GHCR · DockerHub | Always points to the most recent successful build |
+| `2` · `2.11` | GHCR only | Floating semver major / minor tags — updated on every build |
+| `2.11.2` | GHCR · DockerHub | Patch-level version pin |
+| `2.11.2-2026.03.28` | GHCR · DockerHub | Version + build date for fully reproducible deployments |
+| `sha-abc1234` | GHCR · DockerHub | Git SHA of the Dockerfile at build time |
+
+> **Note:** Floating major/minor tags (`2`, `2.11`) are only pushed to GHCR.
+> DockerHub receives only immutable tags (patch version, date-stamped, and SHA)
+> to prevent silent overwrites for users who may have pinned these tags in
+> compose files expecting stability.
+>
+> For production deployments requiring full immutability, pin to a digest from
+> the [Releases](https://github.com/atnplex/caddy/releases) page.
 
 ---
 
@@ -212,6 +218,13 @@ using your personal account credentials.
 In **Settings → Branches**, protect the `main` branch and allow the
 Renovate bot to bypass protection rules for automerge to work.
 
+### 5. Repository About Section (GitHub UI — one-time)
+Set the repository **About** section via **Settings → General → Description**
+(or the gear icon on the repo homepage):
+- **Description:** `Hardened multi-arch custom Caddy image with docker-proxy, Cloudflare DNS/IP, cache-handler, transform-encoder, and caddy-security modules`
+- **Website:** `https://hub.docker.com/r/atnplex/caddy`
+- **Topics:** `caddy`, `docker`, `reverse-proxy`, `cloudflare`, `homelab`, `xcaddy`, `github-actions`
+
 ---
 
 ## Releases

docker/caddy/Dockerfile

@@ -1,10 +1,13 @@
 # ─────────────────────────────────────────────────────────────────
 # Stage 1: Builder
 # ─────────────────────────────────────────────────────────────────
-# IMPORTANT: The tag here (CADDY_VERSION-builder) must match the
-# CADDY_VERSION ARG in Stage 2. When upgrading Caddy, update both
-# the ARG default below AND the digest here together.
-# The SHA digest is version-specific; Renovate keeps it up to date.
+# IMPORTANT: The ARG default below AND the tag in the FROM line must
+# always be kept in sync. When upgrading Caddy, update BOTH the ARG
+# default AND the image tag (and its SHA digest) together in one commit.
+# The FROM tag cannot reference the ARG directly because ARGs declared
+# before the first FROM are not in scope inside the build stage.
+# Renovate keeps the SHA digest up to date automatically; the tag and
+# ARG default must be updated manually (or via a Renovate customManager).
 ARG CADDY_VERSION=2.11.2
 FROM caddy:${CADDY_VERSION}-builder@sha256:84dfc3479309c690643ada9279b3e0b4352ce56b0ec8fd802c668f42b546e98f AS builder
 
@@ -72,8 +75,12 @@ ENV TZ=America/Los_Angeles \
     XDG_DATA_HOME=/data
 
 # Create non-root caddy user/group and add to docker group for socket access.
-# We check for an existing docker group (e.g., inherited from the base image)
-# before creating one, to avoid silently using a mismatched GID.
+# getent is used to check whether a docker group already exists in the base
+# image (e.g., Alpine may ship one with a different GID than the host). If it
+# already exists we skip creation to avoid a mismatched GID silently adding the
+# caddy user to the wrong group. If your host docker.sock GID differs from the
+# group created here, pass --group-add $(stat -c '%g' /var/run/docker.sock)
+# in your docker run / compose file (as shown in the README Quick Start).
 # Provision persistent data and config directories with correct ownership.
 RUN addgroup -S caddy && \
     adduser -S -G caddy caddy && \
@@ -101,9 +108,14 @@ COPY --from=builder /usr/share/zoneinfo/America/Los_Angeles \
 RUN rm -rf /tmp/* /var/tmp/* && \
     find / -xdev -type d -perm -0002 ! -path "/tmp*" -exec chmod 755 {} +
 
-# Healthcheck uses caddy environ (lightweight internal check).
-# wget is not present in this minimal Alpine image.
-# Port 2019 (admin API) is loopback-only and not exposed externally.
+# Healthcheck uses `caddy environ` rather than an HTTP probe against the
+# admin API (port 2019) because:
+#   1. The admin API is loopback-only and disabled in some deployments.
+#   2. `caddy environ` exits 0 iff the binary is functional without
+#      requiring any network listener to be up.
+#   3. The command is lightweight and produces no side effects.
+# If you expose the admin API and prefer an HTTP liveness probe, replace
+# with: CMD wget -qO- http://localhost:2019/ || exit 1
 HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 \
     CMD ["/usr/bin/caddy", "environ"]