From c5dc8c889b88880d6bcc8fea20a9a0634e1be766 Mon Sep 17 00:00:00 2001
From: Zanie Blue <contact@zanie.dev>
Date: Thu, 20 Jun 2024 19:24:01 -0500
Subject: [PATCH] Add documentation for using uv in a Docker image

---
 docs/docker.md | 105 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 105 insertions(+)
 create mode 100644 docs/docker.md

diff --git a/docs/docker.md b/docs/docker.md
new file mode 100644
index 000000000000..9e1cf3e05ca0
--- /dev/null
+++ b/docs/docker.md
@@ -0,0 +1,105 @@
+# Using uv in Docker
+
+## Installing uv
+
+uv can be installed by copying from our Docker image:
+
+```dockerfile
+FROM ghcr.io/astral-sh/uv:latest as uv
+FROM python:3.12-slim-bullseye
+COPY --from=uv /uv /bin/uv
+```
+
+Or with our standalone installer:
+
+```dockerfile
+FROM python:3.12-slim-bullseye
+RUN apt-get update && apt-get install -y curl --no-install-recommends
+RUN curl -LsSf https://astral.sh/uv/install.sh | sh
+ENV PATH="/root/.cargo/bin/:$PATH"
+```
+
+Note this requires `curl` to be available.
+
+In either case, it is best practice to pin to a specific uv version.
+
+## Installing a package
+
+Once uv is installed in an image, it can be used to install some packages.
+
+The system Python environment is safe to use this context, since a container is already isolated. The `--system` flag can be used to install in the system environment:
+
+```dockerfile
+RUN uv pip install --system ruff
+```
+
+To use the system Python environment by default, set the `UV_SYSTEM_PYTHON` variable:
+
+```dockerfile
+ENV UV_SYSTEM_PYTHON=1
+```
+
+Alternatively, a virtual environment can be created and activated:
+
+```dockerfile
+RUN uv venv /opt/venv
+# Use the virtual environment automatically
+ENV VIRTUAL_ENV=/opt/venv
+# Place entry points in the environment at the front of the path
+ENV PATH="/opt/venv/bin:$PATH"
+```
+
+When using a virtual environment, the `--system` flag should be omitted from uv invocations:
+
+```dockerfile
+RUN uv pip install ruff
+```
+
+## Installing requirements
+
+To install requirements files, copy them into the container:
+
+```dockerfile
+COPY requirements.txt .
+RUN uv pip install -r requirements.txt
+```
+
+## Installing a project
+
+When installing a project alongside requirements, it is prudent to separate copying the requirements from the rest of the source code. This allows the dependencies of the project (which do not change often) to be cached separately from the project itself (which changes very frequently).
+
+```dockerfile
+COPY pyproject.toml .
+RUN uv pip install -r pyproject.toml
+COPY . .
+RUN uv pip install -e .
+```
+
+## Optimizations
+
+### Using uv temporarily
+
+If uv isn't needed in the final image, the binary can be mounted in each invocation:
+
+```dockerfile
+RUN --mount=from=uv,source=/uv,target=/bin/uv \
+    uv pip install --system ruff
+```
+
+### Caching
+
+A [cache mount](https://docs.docker.com/build/guide/mounts/#add-a-cache-mount) can be used to improve performance across builds:
+
+```dockerfile
+RUN --mount=type=cache,target=/root/.cache/uv \
+ ./uv pip install -r requirements.txt -->
+```
+
+Note the cache directory's location can be determined with the `uv cache dir` command.
+Alternatively, the cache can be set to a constant location:
+
+```dockerfile
+ENV UV_CACHE_DIR=/opt/uv-cache/
+```
+
+If not mounting the cache, image size can be reduced with `--no-cache` flag.