update

mithenks · mithenks · commit 73d6f22aafe3 · 2026-03-20T21:53:55.000+01:00
diff --git a/.github/workflows/rebuild-3_14-on-upstream-update.yml b/.github/workflows/rebuild-3_14-on-upstream-update.yml
@@ -0,0 +1,73 @@
+name: Rebuild 3.14 On Upstream Update
+
+on:
+  schedule:
+    - cron: "0 */6 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  rebuild-if-upstream-changed:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install skopeo
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y skopeo
+
+      - name: Read latest upstream digest
+        id: latest
+        run: |
+          set -euo pipefail
+          digest="$(skopeo inspect --format '{{.Digest}}' docker://python:3.14-slim-bookworm)"
+          echo "digest=${digest}" >> "$GITHUB_OUTPUT"
+
+      - name: Read stored digest
+        id: stored
+        run: |
+          set -euo pipefail
+          file=".github/state/python-3.14-slim-bookworm.digest"
+          if [ -f "$file" ]; then
+            echo "digest=$(cat "$file")" >> "$GITHUB_OUTPUT"
+          else
+            echo "digest=" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Print digest comparison
+        run: |
+          echo "latest: ${{ steps.latest.outputs.digest }}"
+          echo "stored: ${{ steps.stored.outputs.digest }}"
+
+      - name: Login to Docker Hub
+        if: steps.latest.outputs.digest != steps.stored.outputs.digest
+        run: |
+          echo "${{ secrets.DOCKERHUB_TOKEN }}" | docker login -u "${{ secrets.DOCKERHUB_USERNAME }}" --password-stdin
+
+      - name: Build and push 3.14 images
+        if: steps.latest.outputs.digest != steps.stored.outputs.digest
+        run: |
+          set -euo pipefail
+          bash ./build-and-push-3_14.sh
+
+      - name: Persist latest digest
+        if: steps.latest.outputs.digest != steps.stored.outputs.digest
+        run: |
+          set -euo pipefail
+          mkdir -p .github/state
+          echo "${{ steps.latest.outputs.digest }}" > .github/state/python-3.14-slim-bookworm.digest
+
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add .github/state/python-3.14-slim-bookworm.digest
+          git commit -m "chore: track python 3.14 slim-bookworm digest" || exit 0
+          git push
+
+      - name: Skip build when unchanged
+        if: steps.latest.outputs.digest == steps.stored.outputs.digest
+        run: echo "Upstream python:3.14-slim-bookworm digest unchanged. Skipping build."
diff --git a/Dockerfile b/Dockerfile
@@ -8,6 +8,10 @@ FROM python:${PYTHON_VERSION}-slim-bookworm AS base
 ARG DOCKER_USER=bob
 ARG DOCKER_GROUP=bob
 
+# Persist runtime metadata used by fix-perm.sh in downstream images
+ENV DOCKER_USER=${DOCKER_USER} \
+    DOCKER_GROUP=${DOCKER_GROUP}
+
 # Add normal user that will use the container
 RUN set -ex; addgroup --gid 1000 ${DOCKER_GROUP} && \
     adduser --ingroup ${DOCKER_GROUP} --uid 1000 --disabled-password ${DOCKER_USER} 
diff --git a/README.md b/README.md
@@ -4,8 +4,10 @@ Docker images used for ZCS Python applications.
 
 Supported python versions:
 
-- `3.12`
 - `3.11`
+- `3.12`
+- `3.13`
+- `3.14`
 
 Supported torch versions:
 
@@ -15,26 +17,82 @@ Supported torch versions:
 - `2.5.1`
 - `2.6.0`
 - `2.7.0`
+- `2.8.0`
+- `2.9.0`
+- `2.9.1`
 
 Supported platforms:
 
 - `linux/amd64`
 - `linux/arm64`
 
-## Example usage
+## Image variants
 
-ZCS Python docker images are available in three flavours:
+ZCS Python docker images are available in four flavours:
 
 - `base`: base image, mainly used by other stages
 - `dev`: image for local development
-- `dist`: image used for application distribution
+- `dist`: image used for application distribution (currently identical to `base`; naming is kept for standardization)
 - `torch-cpu`: image for distributing the final application with torch-cpu library
 
+Notes:
+
+- The `dist` image is currently equivalent to `base`; the separate tag is preserved to keep image naming conventions consistent across pipelines.
+
+## Why these image variants
+
+### Non-root default user (`base` / `dist`)
+
+Running Python applications as a non-root user is a safer default for production workloads.
+
+Benefits:
+
+- Reduces container breakout impact, because processes do not run with root privileges.
+- Prevents accidental writes to protected system locations.
+- Aligns with Kubernetes and platform security policies that discourage or block root containers.
+- Improves day-2 operations by making file ownership and runtime behavior more predictable.
+
+How to use `dist`:
+
+- Use `dist` for deployable application images.
+- Keep `dist` in CI/CD pipelines even if it is currently equivalent to `base`, so naming remains consistent as the platform evolves.
+- Build application layers on top of `dist` and keep runtime as the default non-root user.
+
+### Host user mapping (`dev`)
+
+The `dev` image includes `fix-perm.sh` to remap container UID/GID to the host user during build.
+
+Benefits:
+
+- Files created from the container are owned by the host developer user, not by root or an unexpected UID.
+- Prevents permission conflicts in bind-mounted source directories.
+- Preserves repository integrity by avoiding ownership drift that can break local tooling.
+- Makes local development smoother across Linux hosts and CI runners with different user IDs.
+
+### Preinstalled PyTorch (`torch-cpu`)
+
+The `torch-cpu` image provides a ready-to-use runtime with PyTorch already installed.
+
+Benefits:
+
+- Faster application builds due to reduced dependency installation work.
+- Better reproducibility when the PyTorch version is pinned in the image tag.
+- Fewer network-related build failures in downstream projects.
+- Simpler application Dockerfiles for ML services that always require PyTorch.
+
+## Example usage
+
 ### Docker image for local development
 
-The docker image for local development support permissions mapping between host user and docker user. 
+Use the `dev` image when you want a local environment that behaves like your host machine from a file ownership perspective.
+
+Why this matters in practice:
 
-Dockerfile definition to use `dev` image in local environment mapping the image `bob` user to host user:
+- Source files generated inside the container remain writable from your host user.
+- Git operations on bind-mounted repositories avoid permission issues.
+- Teams with different host UID/GID values can still use the same Dockerfile pattern.
+
+The following Dockerfile snippet maps container user/group IDs to your host IDs during build:
 
 ```docker
 FROM zcscompany/python:3.11-dev AS dev
@@ -49,55 +107,102 @@ RUN /fix-perm.sh
 USER bob
 ```
 
-Build command: 
+Build command:
+
 ```bash
 docker build --build-arg FIX_UID="$(id -u)" --build-arg FIX_GID="$(id -g)" .
 ```
 
+What happens during build:
+
+- `FIX_UID` and `FIX_GID` are set from your current host user.
+- `/fix-perm.sh` updates container user/group IDs to match the host values.
+- The final image still runs as non-root, but with host-compatible ownership.
+
 ### Docker image for target application with torch-cpu library
 
-Dockerfile definition
+Use this image when your runtime always requires PyTorch CPU support and you want to avoid reinstalling it in every downstream build.
+
+Typical scenarios:
+
+- ML inference services running on CPU-only nodes.
+- Batch workloads where startup/build time should be minimized.
+- CI pipelines where deterministic dependency layers improve reliability.
+
+Dockerfile definition:
 
 ```docker
 FROM zcscompany/python:3.11-torch-cpu-2.4.0
 
 # Copy application requirement file
-COPY --chown=bob:bob app/requirements.txt .
+COPY --chown=${DOCKER_USER}:${DOCKER_GROUP} app/requirements.txt .
 
 # Install app requirements
 RUN pip install --user --no-cache-dir --disable-pip-version-check -r requirements.txt
 
 # Copy application code
-COPY --chown=bob:bob app/ .
+COPY --chown=${DOCKER_USER}:${DOCKER_GROUP} app/ .
 
-# Build and install the library
-RUN python -m build && \
-    pip install --user --no-cache-dir --disable-pip-version-check --editable .
+# Run application
+CMD ["python", "app.py"]
 ```
 
+Notes:
+
+- Keep the `torch-cpu` tag version explicit to guarantee reproducible environments.
+- Install only application-specific requirements in child images.
+
 ### Docker image for target application
 
+Use `dist` as the default base for deployable Python applications that do not need preinstalled PyTorch.
+
+Why use this variant:
+
+- Consistent naming in CI/CD (`*-dist` tags) across projects and stages.
+- Non-root runtime by default for safer production deployments.
+- Clean separation between development (`dev`) and deployment (`dist`) concerns.
+
 ```docker
 FROM zcscompany/python:3.11-dist
 
 # Copy application requirement file
-COPY --chown=bob:bob app/requirements.txt .
+COPY --chown=${DOCKER_USER}:${DOCKER_GROUP} app/requirements.txt .
 
 # Install app requirements
 RUN pip install --user --no-cache-dir --disable-pip-version-check -r requirements.txt
 
 # Copy application code
-COPY --chown=bob:bob app/ .
+COPY --chown=${DOCKER_USER}:${DOCKER_GROUP} app/ .
 
-# Build and install the library
-RUN python -m build && \
-    pip install --user --no-cache-dir --disable-pip-version-check --editable .
+# Run application
+CMD ["python", "app.py"]
 ```
 
+Even though `dist` is currently equivalent to `base`, keeping `dist` in application Dockerfiles is recommended so future image specialization can be adopted without changing downstream naming conventions.
+
 ## Docker hub repository
 
+The images in this repository are published to Docker Hub and versioned by tag.
+
+Docker Hub page:
+
 https://hub.docker.com/r/zcscompany/python
 
+In most cases you can use these images directly in your application Dockerfiles (for example `FROM zcscompany/python:3.11-dist`) without rebuilding this repository locally.
+
+This is useful when you want:
+
+- Faster CI pipelines, because base images are already prebuilt.
+- Consistent environments across teams and projects.
+- Simpler onboarding, since developers can pull and use images immediately.
+
+Example commands:
+
+```bash
+docker pull zcscompany/python:3.11-dist
+docker run --rm -it zcscompany/python:3.11-dist python --version
+```
+
 
 ## Support
 
diff --git a/build-and-push-3_13.sh b/build-and-push-3_13.sh
@@ -10,7 +10,7 @@ docker buildx build --platform linux/amd64,linux/arm64 --sbom=true --provenance=
 
 docker buildx build --platform linux/amd64,linux/arm64 --sbom=true --provenance=true --builder=container --pull ${PUSH} --target dev --build-arg PYTHON_VERSION=3.13 -t zcscompany/python:3.13-dev .
 
-docker buildx build --platform linux/amd64,linux/arm64 --sbom=true --provenance=true --builder=container --pull ${PUSH} --target base --build-arg PYTHON_VERSION=3.13 -t zcscompany/python:3.13-dist .
+docker buildx build --platform linux/amd64,linux/arm64 --sbom=true --provenance=true --builder=container --pull ${PUSH} --target dist --build-arg PYTHON_VERSION=3.13 -t zcscompany/python:3.13-dist .
 
 docker buildx build --platform linux/amd64,linux/arm64 --sbom=true --provenance=true --builder=container --pull ${PUSH} --target torch-cpu --build-arg PYTHON_VERSION=3.13 --build-arg TORCH_VERSION=2.6.0 -t zcscompany/python:3.13-torch-cpu-2.6.0 .
 
diff --git a/build-and-push-3_14.sh b/build-and-push-3_14.sh
@@ -10,7 +10,7 @@ docker buildx build --platform linux/amd64,linux/arm64 --sbom=true --provenance=
 
 docker buildx build --platform linux/amd64,linux/arm64 --sbom=true --provenance=true --builder=container --pull ${PUSH} --target dev --build-arg PYTHON_VERSION=3.14 -t zcscompany/python:3.14-dev .
 
-docker buildx build --platform linux/amd64,linux/arm64 --sbom=true --provenance=true --builder=container --pull ${PUSH} --target base --build-arg PYTHON_VERSION=3.14 -t zcscompany/python:3.14-dist .
+docker buildx build --platform linux/amd64,linux/arm64 --sbom=true --provenance=true --builder=container --pull ${PUSH} --target dist --build-arg PYTHON_VERSION=3.14 -t zcscompany/python:3.14-dist .
 
 docker buildx build --platform linux/amd64,linux/arm64 --sbom=true --provenance=true --builder=container --pull ${PUSH} --target torch-cpu --build-arg PYTHON_VERSION=3.14 --build-arg TORCH_VERSION=2.9.0 -t zcscompany/python:3.14-torch-cpu-2.9.0 .
 
diff --git a/build-and-push.sh b/build-and-push.sh
@@ -10,13 +10,13 @@ docker buildx build --platform linux/amd64,linux/arm64 --sbom=true --provenance=
 
 docker buildx build --platform linux/amd64,linux/arm64 --sbom=true --provenance=true --builder=container --pull ${PUSH} --target dev -t zcscompany/python:3.11-dev .
 
-docker buildx build --platform linux/amd64,linux/arm64 --sbom=true --provenance=true --builder=container --pull ${PUSH} --target base -t zcscompany/python:3.11-dist .
+docker buildx build --platform linux/amd64,linux/arm64 --sbom=true --provenance=true --builder=container --pull ${PUSH} --target dist -t zcscompany/python:3.11-dist .
 
 docker buildx build --platform linux/amd64,linux/arm64 --sbom=true --provenance=true --builder=container --pull ${PUSH} --target base --build-arg PYTHON_VERSION=3.12 -t zcscompany/python:3.12-base .
 
 docker buildx build --platform linux/amd64,linux/arm64 --sbom=true --provenance=true --builder=container --pull ${PUSH} --target dev --build-arg PYTHON_VERSION=3.12 -t zcscompany/python:3.12-dev .
 
-docker buildx build --platform linux/amd64,linux/arm64 --sbom=true --provenance=true --builder=container --pull ${PUSH} --target base --build-arg PYTHON_VERSION=3.12 -t zcscompany/python:3.12-dist .
+docker buildx build --platform linux/amd64,linux/arm64 --sbom=true --provenance=true --builder=container --pull ${PUSH} --target dist --build-arg PYTHON_VERSION=3.12 -t zcscompany/python:3.12-dist .
 
 docker buildx build --platform linux/amd64,linux/arm64 --sbom=true --provenance=true --builder=container --pull ${PUSH} --target torch-cpu --build-arg TORCH_VERSION=2.4.0 -t zcscompany/python:3.11-torch-cpu-2.4.0 .
 
