feat(dist): Docker Hub publish parity with Create-Node-App

Pin image to PyPI VERSION, multi-arch buildx tags, and smoke the
ulisesjeremias/create-awesome-python-app channel.

Author: ulises-jeremias

.github/workflows/publish-docker.yml

@@ -1,27 +1,96 @@
 name: Publish Docker image
+
+# Triggers on release tags for the CLI package. Version comes directly
+# from the tag ref (create-awesome-python-app@X.Y.Z).
 on:
   push:
     tags:
       - "create-awesome-python-app@*"
+  # Manual trigger to rebuild an image for an existing version.
   workflow_dispatch:
     inputs:
       version:
-        description: "Package version"
+        description: "Package version (e.g. 0.1.0)"
         required: true
+
+permissions:
+  contents: read
+
 jobs:
   docker:
+    name: Build and push Docker image
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - name: Login to Docker Hub
-        uses: docker/login-action@v3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Resolve version
+        id: version
+        env:
+          TAG_REF: ${{ github.ref_name }}
+          INPUT_VERSION: ${{ github.event.inputs.version }}
+        run: |
+          if [ -n "$INPUT_VERSION" ]; then
+            VERSION="$INPUT_VERSION"
+          else
+            # Tag format: create-awesome-python-app@X.Y.Z
+            VERSION="${TAG_REF#create-awesome-python-app@}"
+          fi
+          MAJOR=$(echo "$VERSION" | cut -d. -f1)
+          MINOR=$(echo "$VERSION" | cut -d. -f2)
+          {
+            echo "version=$VERSION"
+            echo "major=$MAJOR"
+            echo "minor=$MINOR"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Set up QEMU
+        # Required so buildx can cross-build linux/arm64 on the x86_64
+        # ubuntu-latest runner.
+        uses: docker/setup-qemu-action@96fe6ef7f33517b61c61be40b68a1882f3264fb8 # v4.2.0
+        with:
+          platforms: linux/arm64
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4.2.0
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@af1e73f918a031802d376d3c8bbc3fe56130a9b0 # v4.4.0
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Extract Docker metadata
+        id: meta
+        uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0
+        with:
+          images: ulisesjeremias/create-awesome-python-app
+          # `latest` is pushed on tag pushes AND on explicit workflow_dispatch
+          # runs (which always execute against main, so they represent the
+          # current release).
+          tags: |
+            type=raw,value=latest
+            type=raw,value=${{ steps.version.outputs.version }}
+            type=raw,value=${{ steps.version.outputs.major }}.${{ steps.version.outputs.minor }}
+            type=raw,value=v${{ steps.version.outputs.major }}
+          labels: |
+            org.opencontainers.image.title=create-awesome-python-app
+            org.opencontainers.image.description=Composable scaffolding CLI for production-ready Python apps
+            org.opencontainers.image.url=https://github.com/Create-Python-App/create-python-app
+            org.opencontainers.image.source=https://github.com/Create-Python-App/create-python-app
+            org.opencontainers.image.licenses=MIT
+            org.opencontainers.image.version=${{ steps.version.outputs.version }}
+
       - name: Build and push
-        uses: docker/build-push-action@v6
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
         with:
           context: .
           push: true
-          tags: |
-            ${{ secrets.DOCKERHUB_USERNAME }}/create-awesome-python-app:latest
+          platforms: linux/amd64,linux/arm64
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          build-args: |
+            VERSION=${{ steps.version.outputs.version }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.github/workflows/smoke-distribution.yml

@@ -2,6 +2,7 @@ name: Distribution smoke tests
 
 # Smoke-tests each published distribution channel:
 #   uvx      — PyPI via uvx
+#   docker   — pull & run ulisesjeremias/create-awesome-python-app:latest
 #   homebrew — brew install on macos-latest
 #   aur      — makepkg inside an archlinux container
 #   versions — cross-check channel versions against PyPI
@@ -30,6 +31,25 @@ jobs:
           uvx create-awesome-python-app@latest --version
           uvx create-awesome-python-app@latest --help | head -5
 
+  docker:
+    name: Docker Hub
+    runs-on: ubuntu-latest
+    steps:
+      - name: Pull image
+        run: docker pull ulisesjeremias/create-awesome-python-app:latest
+
+      - name: Verify --version
+        run: |
+          VERSION=$(docker run --rm ulisesjeremias/create-awesome-python-app:latest --version 2>&1)
+          echo "docker version: $VERSION"
+          echo "$VERSION" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$' || {
+            echo "::error::Unexpected version output: $VERSION"
+            exit 1
+          }
+
+      - name: Verify --help
+        run: docker run --rm ulisesjeremias/create-awesome-python-app:latest --help | head -5
+
   homebrew:
     name: Homebrew (Create-Python-App/tap)
     runs-on: macos-latest
@@ -104,6 +124,9 @@ jobs:
           PYPI=$(curl -sfL https://pypi.org/pypi/create-awesome-python-app/json | \
                  python3 -c "import json,sys; print(json.load(sys.stdin)['info']['version'])")
 
+          DOCKER=$(docker run --rm ulisesjeremias/create-awesome-python-app:latest --version 2>&1 \
+                   || echo "unavailable")
+
           HOMEBREW=$(curl -sfL \
                     https://raw.githubusercontent.com/Create-Python-App/homebrew-tap/main/Formula/create-awesome-python-app.rb | \
                     grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1 || echo "unavailable")
@@ -115,12 +138,15 @@ jobs:
 
           echo "Channel versions:"
           echo "  pypi:     $PYPI"
+          echo "  docker:   $DOCKER"
           echo "  homebrew: $HOMEBREW"
           echo "  aur:      $AUR"
 
-          if [ "$HOMEBREW" != "unavailable" ] && [ "$HOMEBREW" != "$PYPI" ]; then
-            echo "::warning::Version mismatch: pypi=$PYPI homebrew=$HOMEBREW"
-          fi
+          for CHANNEL_VER in "$DOCKER" "$HOMEBREW"; do
+            if [ "$CHANNEL_VER" != "unavailable" ] && [ "$CHANNEL_VER" != "$PYPI" ]; then
+              echo "::warning::Version mismatch vs pypi=$PYPI: $CHANNEL_VER"
+            fi
+          done
           if [ "$AUR" != "unavailable" ] && [ "$AUR" != "$PYPI" ]; then
             echo "::warning::Version mismatch: pypi=$PYPI aur=$AUR (AUR may lag)"
           fi

Dockerfile

@@ -1,5 +1,21 @@
-FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim
-WORKDIR /app
-COPY . .
-RUN uv sync --frozen --no-dev
-ENTRYPOINT ["uv", "run", "create-awesome-python-app"]
+# syntax=docker/dockerfile:1.9
+FROM python:3.12-slim-bookworm
+
+# VERSION is passed at build time by the publish workflow so the image
+# is pinned to a specific PyPI package version (makes each image
+# reproducible for its tag).
+ARG VERSION=latest
+
+# hadolint ignore=DL3013
+RUN useradd --create-home --uid 1000 --shell /bin/bash app \
+  && if [ "$VERSION" = "latest" ]; then \
+       pip install --no-cache-dir create-awesome-python-app; \
+     else \
+       pip install --no-cache-dir "create-awesome-python-app==${VERSION}"; \
+     fi
+
+USER app
+WORKDIR /home/app
+
+ENTRYPOINT ["create-awesome-python-app"]
+CMD ["--help"]

README.md

@@ -4,6 +4,7 @@
 [![Lint](https://github.com/Create-Python-App/create-python-app/actions/workflows/lint.yml/badge.svg)](https://github.com/Create-Python-App/create-python-app/actions/workflows/lint.yml)
 [![Typecheck](https://github.com/Create-Python-App/create-python-app/actions/workflows/type-check.yml/badge.svg)](https://github.com/Create-Python-App/create-python-app/actions/workflows/type-check.yml)
 [![PyPI](https://img.shields.io/pypi/v/create-awesome-python-app.svg)](https://pypi.org/project/create-awesome-python-app/)
+[![Docker](https://img.shields.io/docker/v/ulisesjeremias/create-awesome-python-app?style=flat-square&label=Docker&logo=docker&color=2496ED)](https://hub.docker.com/r/ulisesjeremias/create-awesome-python-app)
 [![AUR](https://img.shields.io/aur/version/create-awesome-python-app?label=AUR&logo=archlinux)](https://aur.archlinux.org/packages/create-awesome-python-app)
 [![Homebrew](https://img.shields.io/badge/homebrew-Create--Python--App%2Ftap-orange?logo=homebrew)](https://github.com/Create-Python-App/homebrew-tap)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
@@ -39,6 +40,10 @@ brew install create-awesome-python-app
 
 # AUR
 yay -S create-awesome-python-app
+
+# Docker
+docker run --rm -it -v "${PWD}:/app" -w /app \
+  ulisesjeremias/create-awesome-python-app my-app
 ```
 
 Or pin a version:
@@ -106,8 +111,18 @@ uv sync --group dev
 
 ## Docker
 
+Published image: [`ulisesjeremias/create-awesome-python-app`](https://hub.docker.com/r/ulisesjeremias/create-awesome-python-app)
+
+```bash
+docker run --rm ulisesjeremias/create-awesome-python-app:0.1.0 --version
+docker run --rm -it -v "${PWD}:/app" -w /app \
+  ulisesjeremias/create-awesome-python-app my-app --template fastapi-starter --no-interactive
+```
+
+Local build (installs the given PyPI version into the image):
+
 ```bash
-docker build -t create-awesome-python-app .
+docker build --build-arg VERSION=0.1.0 -t create-awesome-python-app .
 docker run --rm create-awesome-python-app --help
 ```
 

docs/DISTRIBUTION_SETUP.md

@@ -40,7 +40,19 @@ Then:
 
 ## Docker Hub
 
-Create a write token and set `DOCKERHUB_USERNAME` / `DOCKERHUB_TOKEN`.
+Image: [`ulisesjeremias/create-awesome-python-app`](https://hub.docker.com/r/ulisesjeremias/create-awesome-python-app)
+
+Secrets (already used by CNA; reuse the same Hub account):
+
+- `DOCKERHUB_USERNAME` — e.g. `ulisesjeremias`
+- `DOCKERHUB_TOKEN` — Hub access token with write scope
+
+Verify:
+
+```bash
+gh workflow run "Publish Docker image" --repo Create-Python-App/create-python-app -f version=0.1.0
+docker run --rm ulisesjeremias/create-awesome-python-app:0.1.0 --version
+```
 
 ## AUR (`AUR_SSH_PRIVATE_KEY`, `AUR_REPO_TOKEN`)