perf(docker): preserve dependency caches across release versions (#1425)

Preserve dependency caches across release versions and preserve build argument comments.

Changing BUILD_VERSION invalidated OS-package and Python-dependency installation layers in both Docker stages, even when the dependencies are unchanged. Docker makes an in-scope build argument available to subsequent RUN instructions, so declaring it early makes a release-version change affect those cache keys.

With the change, the second build reuses the builder OS-package, locked Python-dependency and runtime OS-package layers. Without the change, all three installation steps would run again.

Co-authored-by: David Siegel <dsiegel@MacBook-Air-von-David.local>

Dockerfile

@@ -10,11 +10,6 @@ ARG PYTHON_VERSION=3.13.15
 # If BUILD_FROM is set (Home Assistant), use it; otherwise use python-slim.
 FROM ${BUILD_FROM:-python:${PYTHON_VERSION}-slim} AS builder
 
-# Home Assistant supplies BUILD_VERSION from config.yaml. Use it for the
-# installed package as well as the dashboard when building an add-on.
-ARG BUILD_VERSION=dev
-ENV EOS_BUILD_VERSION=${BUILD_VERSION}
-
 # uv: pinned, copied as a static binary (no extra Python packages installed).
 COPY --from=ghcr.io/astral-sh/uv:0.12.7 /uv /bin/uv
 
@@ -44,6 +39,10 @@ RUN --mount=type=cache,target=/root/.cache/uv \
 # Project sources and generated version (pyproject reads version from version.txt).
 COPY src/ ./src
 COPY scripts/get_version.py ./scripts/get_version.py
+# Home Assistant supplies BUILD_VERSION from config.yaml. Use it for the
+# installed package as well as the dashboard when building an add-on.
+ARG BUILD_VERSION=dev
+ENV EOS_BUILD_VERSION=${BUILD_VERSION}
 RUN python scripts/get_version.py > version.txt
 
 # Install the project itself. Editable, because akkudoktoreos.core.version
@@ -55,21 +54,6 @@ RUN --mount=type=cache,target=/root/.cache/uv \
 
 FROM ${BUILD_FROM:-python:${PYTHON_VERSION}-slim} AS runtime
 
-# Supplied by Home Assistant, docker-compose and CI; "dev" marks an
-# unversioned local build. CI stamps org.opencontainers.image.version via
-# docker/metadata-action, so it is not set here.
-ARG BUILD_VERSION=dev
-
-LABEL \
-    io.hass.version="${BUILD_VERSION}" \
-    io.hass.type="addon" \
-    io.hass.arch="aarch64|amd64" \
-    source="https://github.com/Akkudoktor-EOS/EOS" \
-    org.opencontainers.image.source="https://github.com/Akkudoktor-EOS/EOS" \
-    org.opencontainers.image.licenses="Apache-2.0"
-
-ENV EOS_BUILD_VERSION=${BUILD_VERSION}
-
 ENV EOS_DIR="/opt/eos"
 # Create persistent data directory similar to home assistant add-on
 # - EOS_DATA_DIR: Persistent data directory
@@ -117,6 +101,21 @@ COPY --from=builder /opt/venv /opt/venv
 # Editable install: the venv only points at the source tree, so it must be present.
 COPY src/ ./src
 
+# Supplied by Home Assistant, docker-compose and CI; "dev" marks an
+# unversioned local build. CI stamps org.opencontainers.image.version via
+# docker/metadata-action, so it is not set here.
+ARG BUILD_VERSION=dev
+
+LABEL \
+    io.hass.version="${BUILD_VERSION}" \
+    io.hass.type="addon" \
+    io.hass.arch="aarch64|amd64" \
+    source="https://github.com/Akkudoktor-EOS/EOS" \
+    org.opencontainers.image.source="https://github.com/Akkudoktor-EOS/EOS" \
+    org.opencontainers.image.licenses="Apache-2.0"
+
+ENV EOS_BUILD_VERSION=${BUILD_VERSION}
+
 ENTRYPOINT []
 
 EXPOSE 8503