Skip to content

refactor(docker): slim multi-stage build, drop image size by ~58% - #233

Merged
matrixise merged 2 commits into
masterfrom
worktree-dockerfile-multistage-slim
Sep 25, 2026
Merged

matrixise merged 2 commits into
masterfrom
worktree-dockerfile-multistage-slim

Conversation

@matrixise

@matrixise matrixise commented Jun 11, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Reworks the Dockerfile into a real two-stage build and trims the image from ~625 MB to ~233 MB (-63%), while switching dependency installation to uv sync against pyproject.toml + uv.lock (following the project-wide migration in #247).

Changes

  • Real multi-stage: a builder stage (python:3.13-slim + build toolchain) resolves and installs every dependency group into an isolated venv at /opt/venv; the final dev stage (python:3.13-slim) copies only that venv plus runtime/interactive tooling. build-essential/gcc no longer ship in the final image.
  • uv-based install: the uv binary is copied from the official ghcr.io/astral-sh/uv:0.12.1 image (matching the version pinned in mise.toml) instead of being pip-installed; uv sync --frozen --all-groups installs into a dedicated venv via UV_PROJECT_ENVIRONMENT=/opt/venv, with a uv cache mount for fast rebuilds.
  • Base image: python:3.13 → python:3.13-slim.
  • apt cache mounts on /var/lib/apt/lists with sharing=locked.
  • New .dockerignore to shrink the build context and keep .env/secrets, .venv/, and cache directories out of it, while keeping pyproject.toml and uv.lock in.
  • New task docker:build:cached: builds the image reusing Docker's build cache instead of --no-cache, for faster local rebuilds. The existing task docker:build keeps its --no-cache behavior unchanged.

The final dev stage stays the last stage, so docker build -t python.ie/website-dev . (used by task docker:build, no --target) keeps producing the image consumed by both the web and test compose services, with no changes needed to docker-compose.yml invocations.

Validation

  • docker build succeeds, both with and without the build cache.
  • Multi-stage separation confirmed: docker history on the final image shows no trace of gcc/build-essential/uv (they only exist in the builder stage, which was verified to build standalone via docker build --target builder).
  • Smoke tests inside the image: Python 3.13.15, Django 6.0.8, Wagtail 7.3.4, ruff 0.15.16, psql 17.11, fish 4.0.2.
  • python pythonie/manage.py check --settings=pythonie.settings.tests reports 0 issues.
  • Full Django test suite passes via task tests (7/7).
  • uv run ruff format --check pythonie and uv run ruff check pythonie both pass inside the container.
  • CI is green.

Image size: ~625 MB → ~233 MB (built from python:3.13 single-stage vs. this multi-stage python:3.13-slim build).

Rework the Dockerfile into a real two-stage build:

- builder stage: python:3.13-slim + build toolchain, installs all
  requirements into an isolated venv at /opt/venv
- dev stage: python:3.13-slim with only runtime packages (postgresql-client)
  and the interactive tooling the dev shell needs (fish, neovim, less, ack,
  iputils-ping), copying the venv from the builder

The build toolchain (build-essential, gcc) no longer ships in the final
image, cutting it from ~1.69GB to ~715MB.

Other fixes:
- drop the stray `aws` package from the install line (junk PyPI package;
  boto3 already provides the AWS SDK)
- stop reinstalling ruff via pip -U (it is already pinned in dev.txt)
- switch ADD to COPY for the requirements files
- add apt cache mounts for /var/lib/apt/lists with sharing=locked
- add a .dockerignore to shrink the build context and keep .env/secrets out

Add a .dockerignore covering VCS, Python caches, local databases, env files
and tooling output.
@matrixise
matrixise force-pushed the worktree-dockerfile-multistage-slim branch from 5579a51 to 1afd9c4 Compare September 25, 2026 05:06
Add a new `docker:build:cached` task that reuses the Docker build cache, complementing the existing `docker:build:no-cache` task for scenarios where faster rebuilds are preferred over guaranteeing fresh dependencies.
@matrixise
matrixise merged commit 47f70c1 into master Sep 25, 2026
2 checks passed
@matrixise
matrixise deleted the worktree-dockerfile-multistage-slim branch September 25, 2026 05:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant