Add a multistage Docker build example that uses the standalone builds (#15)

Author: zanieb

.github/workflows/ci.yaml

@@ -39,6 +39,15 @@ jobs:
           cache-to: type=gha,mode=min,scope=uv-docker-example-multistage
           outputs: type=docker,dest=/tmp/uv-docker-example-multistage.tar
 
+      - name: Build and export (standalone)
+        uses: docker/build-push-action@v6
+        with:
+          file: standalone.Dockerfile
+          tags: uv-docker-example-standalone:latest
+          cache-from: type=gha,scope=uv-docker-example-standalone
+          cache-to: type=gha,mode=min,scope=uv-docker-example-standalone
+          outputs: type=docker,dest=/tmp/uv-docker-example-standalone.tar
+
       - name: Upload artifact
         uses: actions/upload-artifact@v4
         with:
@@ -51,6 +60,12 @@ jobs:
           name: uv-docker-example-multistage
           path: /tmp/uv-docker-example-multistage.tar
 
+      - name: Upload artifact (standalone)
+        uses: actions/upload-artifact@v4
+        with:
+          name: uv-docker-example-standalone
+          path: /tmp/uv-docker-example-standalone.tar
+
   test:
     name: "test image"
     runs-on: ubuntu-latest
@@ -70,10 +85,17 @@ jobs:
           name: uv-docker-example-multistage
           path: /tmp
 
+      - name: Download artifact (standalone)
+        uses: actions/download-artifact@v4
+        with:
+          name: uv-docker-example-standalone
+          path: /tmp
+  
       - name: Load images
         run: |
           docker load --input /tmp/uv-docker-example.tar
           docker load --input /tmp/uv-docker-example-multistage.tar
+          docker load --input /tmp/uv-docker-example-standalone.tar
           docker image ls -a
 
       - name: Test command line
@@ -86,3 +108,6 @@ jobs:
 
       - name: Test command line (multistage)
         run: docker run uv-docker-example-multistage:latest hello
+
+      - name: Test command line (standalone)
+        run: docker run uv-docker-example-standalone:latest hello

README.md

@@ -53,6 +53,10 @@ The [`Dockerfile`](./Dockerfile) defines the image and includes:
 The [`multistage.Dockerfile`](./multistage.Dockerfile) example extends the `Dockerfile` example to
 use multistage builds to reduce the final size of the image.
 
+The [`standalone.Dockerfile`](./standalone.Dockerfile) example extends the `multistage.Dockerfile`
+example to use a managed Python interpreter in a multistage build instead of the system interpreter
+that comes with the base image.
+
 ### Dockerignore file
 
 The [`.dockerignore`](./.dockerignore) file includes an entry for the `.venv` directory to ensure the

multistage.Dockerfile

@@ -7,7 +7,8 @@ ENV UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy
 
 # Disable Python downloads, because we want to use the system interpreter
 # across both images. If using a managed Python version, it needs to be
-# copied from the build image into the final image.
+# copied from the build image into the final image; see `standalone.Dockerfile`
+# for an example.
 ENV UV_PYTHON_DOWNLOADS=0
 
 WORKDIR /app

standalone.Dockerfile

@@ -0,0 +1,38 @@
+# An example of using standalone Python builds with multistage images.
+
+# First, build the application in the `/app` directory
+FROM ghcr.io/astral-sh/uv:bookworm-slim AS builder
+ENV UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy
+
+# Configure the Python directory so it is consistent
+ENV UV_PYTHON_INSTALL_DIR /python
+
+# Only use the managed Python version
+ENV UV_PYTHON_PREFERENCE=only-managed
+
+# Install Python before the project for caching
+RUN uv python install 3.12
+
+WORKDIR /app
+RUN --mount=type=cache,target=/root/.cache/uv \
+    --mount=type=bind,source=uv.lock,target=uv.lock \
+    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
+    uv sync --frozen --no-install-project --no-dev
+ADD . /app
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --frozen --no-dev
+
+# Then, use a final image without uv
+FROM debian:bookworm-slim
+
+# Copy the Python version
+COPY --from=builder --chown=python:python /python /python
+
+# Copy the application from the builder
+COPY --from=builder --chown=app:app /app /app
+
+# Place executables in the environment at the front of the path
+ENV PATH="/app/.venv/bin:$PATH"
+
+# Run the FastAPI application by default
+CMD ["fastapi", "dev", "--host", "0.0.0.0", "/app/src/uv_docker_example"]