handbook/docs/deploy/dockerfile.md

Dockerfile & build

Every service runs containerized as the shared services account: uid/gid 1337, fixed fleet-wide. Build your image to be uid-agnostic so it runs cleanly as that account.

FROM python:3.12-slim
ENV HOME=/tmp                                  # services account has no home dir; $HOME must be writable

WORKDIR /app
RUN apt-get update \
    && apt-get install -y --no-install-recommends git \
    && rm -rf /var/lib/apt/lists/*             # include git ONLY if the container itself needs it

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt   # deps before code — see layer caching

COPY . .
RUN chmod -R a+rwX /app                         # writable by any uid — this is "uid-agnostic"
CMD ["python", "-m", "yourapp"]

• HOME=/tmp — the services account has no home dir; anything writing to $HOME (caches, configs) needs a writable target.
• git — include it only if the container itself needs it (e.g. you pip install from git, or the app shells out to git). The build and host always have git; this is about what's inside the image.
• chmod -R a+rwX /app — makes the app tree writable by any uid, so it runs as 1337.

Layer caching

Copy the deps file and install before COPY . .. Docker caches layers in order, so deps only reinstall when the deps file changes — not on every code edit. Get this backwards and every one-line change triggers a full dependency reinstall.

COPY requirements.txt .                              # pip baseline
RUN pip install --no-cache-dir -r requirements.txt   # cached until deps change
COPY . .                                             # changes every build

Getting your files into the image

COPY . . grabs the whole repo, but be explicit about anything that needs its own place — assets, templates, a config the app reads at runtime. In COPY <src> <dest>, <src> is relative to the build context (your repo) and <dest> is a path in the image.

COPY ./config.toml /app/config.toml   # a single file into a specific path
COPY ./assets /app/assets             # a whole directory (tree mirrors ./assets/)

!!! warning "Don't COPY secrets into the image" Anything sensitive stays out of the image — no COPY ./secrets.env. Secrets live on the host and are injected read-only at runtime (see Secrets). Add them to .dockerignore so a blanket COPY . . can't sweep them in.

Faster builds with uv (optional)

uv is a drop-in for pip that reads the same pyproject.toml — no lockfile needed in the image. Swap the deps layer and add UV_COMPILE_BYTECODE so containers don't pay the first-import .pyc compile cost:

FROM python:3.12-slim
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/   # pull the uv binary from its image
ENV HOME=/tmp
ENV UV_COMPILE_BYTECODE=1                                # compile bytecode at build, not first cold start

WORKDIR /app
COPY pyproject.toml .
RUN uv pip install --system .                            # --system: into the image's Python, no venv/lock
COPY . .
RUN chmod -R a+rwX /app
CMD ["python", "-m", "yourapp"]

Checklist

• HOME=/tmp
• chmod -R a+rwX /app (uid-agnostic; runs as the services account, 1337)
• deps installed before the code copy (layer caching) — pip or uv pip install
• git in the image if the container needs it
• using uv? add ENV UV_COMPILE_BYTECODE=1

See Compose convention for the compose.yaml, and Secrets for credentials.