[docker] docs

Dockerfile

@@ -1,6 +1,15 @@
 ARG PHP_VERSION=8.2
 
-# Install base packages which all stages (build, test, run) need
+# Tree of layers:
+# base
+# ├── dev-tools
+# │   ├── build
+# │   │   └── tests
+# │   └── devcontainer
+# └── run (copies built artifacts out of build)
+
+# Install base packages
+# Things which all stages (build, test, run) need
 FROM debian:bookworm AS base
 COPY --from=mwader/static-ffmpeg:6.1 /ffmpeg /ffprobe /usr/local/bin/
 RUN apt update && \
@@ -14,27 +23,27 @@ RUN apt update && \
     curl imagemagick zip unzip unit unit-php gettext && \
     rm -rf /var/lib/apt/lists/*
 
-# Composer has 100MB of dependencies, and we only need that during build and test
+# Install dev packages
-FROM base AS composer
+# Things which are only needed during development - Composer has 100MB of
+# dependencies, so let's avoid including that in the final image
+FROM base AS dev-tools
 RUN apt update && apt upgrade -y && \
     apt install -y composer php${PHP_VERSION}-xdebug git procps net-tools vim && \
     rm -rf /var/lib/apt/lists/*
 ENV XDEBUG_MODE=coverage
 
-# "Build" shimmie (composer install - done in its own stage so that we don't
+# "Build" shimmie (composer install)
-# need to include all the composer fluff in the final image)
+# Done in its own stage so that we don't meed to include all the
-FROM composer AS build
+# composer fluff in the final image
+FROM dev-tools AS build
 COPY composer.json composer.lock /app/
 WORKDIR /app
 RUN composer install --no-dev
 COPY . /app/
 
-# Tests in their own image. Really we should inherit from app and then
+# Tests in their own image.
-# `composer install` phpunit on top of that; but for some reason
+# Re-run composer install to get dev dependencies
-# `composer install --no-dev && composer install` doesn't install dev
+FROM build AS tests
-FROM composer AS tests
-COPY composer.json composer.lock /app/
-WORKDIR /app
 RUN composer install
 COPY . /app/
 ARG RUN_TESTS=true
@@ -42,11 +51,13 @@ RUN [ $RUN_TESTS = false ] || (\
     echo '=== Installing ===' && mkdir -p data/config && INSTALL_DSN="sqlite:data/shimmie.sqlite" php index.php && \
     echo '=== Smoke Test ===' && php index.php get-page /post/list && \
     echo '=== Unit Tests ===' && ./vendor/bin/phpunit --configuration tests/phpunit.xml && \
-    echo '=== Coverage ===' && XDEBUG_MODE=coverage ./vendor/bin/phpunit --configuration tests/phpunit.xml --coverage-text && \
+    echo '=== Coverage ===' && ./vendor/bin/phpunit --configuration tests/phpunit.xml --coverage-text && \
     echo '=== Cleaning ===' && rm -rf data)
 
 # Devcontainer target
-FROM composer AS devcontainer
+# Contains all of the build and debug tools, but no code, since
+# that's mounted from the host
+FROM dev-tools AS devcontainer
 EXPOSE 8000
 
 # Actually run shimmie