update dockerfile build stages to optimize build caching of the devcontiner stage

Author: ilude

Dockerfile

@@ -4,39 +4,9 @@ ARG PYTHON_VERSION=3.12-slim-bookworm
 FROM python:${PYTHON_VERSION} as base
 LABEL maintainer="Mike Glenn <mglenn@ilude.com>"
 
-# User management setup (previously in user_base stage)
-ARG PUID=${PUID:-1000}
-ARG PGID=${PGID:-1000}
-
-ARG USER=anvil
-ENV USER=${USER}
-
-ARG PROJECT_NAME
-ENV PROJECT_NAME=${PROJECT_NAME}
-
-ARG PROJECT_PATH=/srv
-ENV PROJECT_PATH=${PROJECT_PATH}
-
-ARG ONBOARD_PORT=9830
-ENV ONBOARD_PORT=${ONBOARD_PORT}
-
-ENV HOME=/home/${USER}
-ARG TERM_SHELL=zsh
-ENV TERM_SHELL=${TERM_SHELL}
-
 ARG TZ=America/New_York
 ENV TZ=${TZ}
 
-### Remove legacy vendor/deps path usage; rely on system site-packages managed by uv
-ENV PYTHONUNBUFFERED=TRUE
-ENV UV_LINK_MODE=copy
-ENV UV_SYSTEM_PYTHON=1
-# Install project dependencies into the system Python prefix instead of a project .venv
-# See: https://docs.astral.sh/uv/concepts/projects/config/#project-environment-path
-ENV UV_PROJECT_ENVIRONMENT=/usr/local
-# Allow modifying the system environment inside containers
-ENV UV_BREAK_SYSTEM_PACKAGES=1
-
 ENV DEBIAN_FRONTEND=noninteractive
 ENV DEBCONF_NONINTERACTIVE_SEEN=true
 
@@ -64,14 +34,36 @@ ENV LC_ALL en_US.UTF-8
 # Install uv
 COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
 
+# ----------------------------------------------------------------------
+# User setup
+# Sets up the non-root user, group, home directory, project path, and shell
+# This section is responsible for creating the runtime user and permissions
+# ----------------------------------------------------------------------
+
+# User management setup (previously in user_base stage)
+ARG PUID=${PUID:-1000}
+ARG PGID=${PGID:-1000}
+
+ARG USER=anvil
+ENV USER=${USER}
+
+ENV HOME=/home/${USER}
+
+ARG PROJECT_PATH=/srv
+ENV PROJECT_PATH=${PROJECT_PATH}
+
+WORKDIR $PROJECT_PATH
+
 RUN sed -i 's/UID_MAX .*/UID_MAX    100000/' /etc/login.defs && \
     groupadd --gid ${PGID} ${USER} && \
-    useradd --uid ${PUID} --gid ${PGID} -s /bin/${TERM_SHELL} -m ${USER} && \
+    useradd --uid ${PUID} --gid ${PGID} -s /bin/sh -m ${USER} && \
     mkdir -p ${PROJECT_PATH} && \
     chown -R ${USER}:${USER} ${PROJECT_PATH} && \
-    chown -R ${USER}:${USER} ${HOME} && \
-    # set the shell for root too
-    chsh -s /bin/${TERM_SHELL}
+    chown -R ${USER}:${USER} ${HOME}
+
+# ----------------------------------------------------------------------
+# --- docker-entrypoint setup section ---
+# ----------------------------------------------------------------------
 
 COPY --chmod=755 <<-"EOF" /usr/local/bin/docker-entrypoint.sh
 #!/bin/bash
@@ -105,13 +97,26 @@ echo "Running: $@"
 exec "$@"
 EOF
 
-WORKDIR $PROJECT_PATH
 ENTRYPOINT [ "/usr/local/bin/docker-entrypoint.sh" ]
 
-##############################
-# Begin build
-##############################
-FROM base as build
+
+
+### Remove legacy vendor/deps path usage; rely on system site-packages managed by uv
+ENV PYTHONUNBUFFERED=TRUE
+ENV UV_LINK_MODE=copy
+ENV UV_SYSTEM_PYTHON=1
+# Install project dependencies into the system Python prefix instead of a project .venv
+# See: https://docs.astral.sh/uv/concepts/projects/config/#project-environment-path
+ENV UV_PROJECT_ENVIRONMENT=/usr/local
+# Allow modifying the system environment inside containers
+ENV UV_BREAK_SYSTEM_PACKAGES=1
+
+ENV ONBOARD_PORT=${ONBOARD_PORT:-9830}
+
+# ----------------------------------------------------------------------
+# --- Build-base image stage
+# ----------------------------------------------------------------------
+FROM base as build-base
 
 # Install build dependencies needed for compiling Python packages
 RUN --mount=type=cache,target=/var/cache/apt \
@@ -141,7 +146,10 @@ RUN --mount=type=cache,target=/var/cache/apt \
     apt-get autoclean -y && \
     rm -rf /var/lib/apt/lists/*
 
-WORKDIR ${PROJECT_PATH}
+# ----------------------------------------------------------------------
+# --- Build-base image stage
+# ----------------------------------------------------------------------
+FROM build-base as build
 
 # Copy lockfile and root pyproject for reproducible resolution
 COPY uv.lock* pyproject.toml ${PROJECT_PATH}/
@@ -154,9 +162,10 @@ RUN --mount=type=cache,target=/root/.cache/uv \
     --mount=type=cache,target=/root/.cache/pip \
     uv sync --no-editable --no-dev
 
-##############################
-# Begin production
-##############################
+
+# ----------------------------------------------------------------------
+# --- Production image stage ---
+# ----------------------------------------------------------------------
 FROM base as production
 
 # Copy application code into the project directory root (creates ${PROJECT_PATH}/app)
@@ -179,23 +188,20 @@ RUN mkdir -p ${PROJECT_PATH}/static/icons && \
 # Run the app with gunicorn via uv without a shell
 CMD ["uv", "run", "--no-sync", "-m", "gunicorn", "run:app", "--bind", "0.0.0.0:9830", "--access-logfile", "-", "--error-logfile", "-"]
 
-##############################
-# Begin devcontainer
-##############################
-FROM build as devcontainer
+# ----------------------------------------------------------------------
+# --- development os packages image stage ---
+# ----------------------------------------------------------------------
+FROM build-base as development-base
 
 RUN --mount=type=cache,target=/var/cache/apt \
     --mount=type=cache,target=/var/lib/apt/lists \
     apt-get update && apt-get install -y --no-install-recommends \
-    bash \
     bash-completion \
-    build-essential \
     coreutils \
     docker.io \
     dnsutils \
     exa \
     gh \
-    git \
     gnuplot \
     gnuplot-x11 \
     graphviz \
@@ -204,17 +210,11 @@ RUN --mount=type=cache,target=/var/cache/apt \
     iputils-ping \
     jq \
     less \
-    libjpeg-dev \
-    libpng-dev \
     libpq-dev \
-    libssl-dev \
-    libxml2-dev \
-    libxslt-dev \
     libzmq3-dev \
     make \
     nodejs \
     npm \
-    openssh-client \
     passwd \
     python3-pip \
     python3-setuptools \
@@ -235,7 +235,18 @@ RUN --mount=type=cache,target=/var/cache/apt \
     apt-get autoclean -y && \
     rm -rf /var/lib/apt/lists/* && \
     echo ${USER} ALL=\(root\) NOPASSWD:ALL > /etc/sudoers.d/${USER} && \
-    chmod 0440 /etc/sudoers.d/${USER}
+    chmod 0440 /etc/sudoers.d/${USER} && \
+    # set the shell for $USER and root
+    chsh -s "$(which zsh)" ${USER}  && \
+    chsh -s "$(which zsh)" root
+
+# ----------------------------------------------------------------------
+# --- development os packages image stage ---
+# ----------------------------------------------------------------------
+FROM development-base as devcontainer
+
+# Copy lockfile and root pyproject for reproducible resolution
+COPY uv.lock* pyproject.toml ${PROJECT_PATH}/
 
 # Install Python dependencies into the system environment (run as root)
 RUN --mount=type=cache,target=/tmp/.cache/uv \
@@ -245,8 +256,6 @@ RUN --mount=type=cache,target=/tmp/.cache/uv \
     chown -R $USER:$USER /usr/local/lib/python3.12/site-packages/ && \
     chown -R $USER:$USER /usr/local/bin
 
-# Copy application code after dependency installation (keep package layout)
-COPY --chown=${USER}:${USER} app ${PROJECT_PATH}/
 
 # Switch to non-root user for development
 USER ${USER}

pyproject.toml

@@ -37,17 +37,6 @@ line-length = 88
 skip-string-normalization = true
 target-version = ['py312']
 
-[tool.setuptools]
-py-modules = ["run"]
-packages = ["app"]
-
-#[tool.uv]
-# Using a single-project layout; default packaging behavior is enabled
-
-[build-system]
-requires = ["setuptools>=45", "wheel", "uv"]
-build-backend = "setuptools.build_meta"
-
 [dependency-groups]
 dev = [
     "behave",

pytest.ini

@@ -5,4 +5,5 @@ python_paths = .
 [pytest]
 ; By default exclude integration tests. Run with `pytest -q -m "integration"` to include them.
 addopts = --strict-markers --strict-config --verbosity=2 -m "not integration"
+pythonpath = .
 markers = integration: mark a test as an integration test that may require external services