Simplify API Dockerfile, align stage names and section style

Cleanup pass on the API image based on the canonical reference Dockerfile
(itk-dev/os2display-api-service@0b2cc18) raised in PR review:

- Renamed `client_app_builder` → `assets_builder` to match canonical.
- Adopted canonical's section-divider comment block.
- Dropped APP_CLIENT_PATH and APP_API_PATH env indirections; literal
  paths read better and match the FPM convention (/var/www/html).
- Dropped the dead APP_RELEASE_TIMESTAMP arg in the assets stage.
- Expanded inline comments to document motivation (two-pass composer
  install, vite manifest ordering, release.json purpose, runtime
  composer for entrypoint dump-env, Prometheus exporter, ENTRYPOINT
  vs CMD) — short lines, one fact each.

Behaviour unchanged. Smoke build via `sh infrastructure/build.sh`
loads working images; resulting API image still ships the
PHP_OPCACHE_*/PHP_PM_* tuning and the public/build vite manifest +
public/release.json that downstream consumers expect.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: turegjorup

infrastructure/display-api-service/Dockerfile

@@ -1,79 +1,85 @@
-######## Clients [Screen|Admin] build ########
-FROM node:24-alpine AS client_app_builder
+################################
+# Assets build
+################################
+FROM node:24-alpine AS assets_builder
 LABEL maintainer="ITK Dev <itkdev@ba.aarhus.dk>"
 
 ARG APP_VERSION="develop"
-ARG APP_RELEASE_TIMESTAMP=0
 
-ENV APP_CLIENT_PATH=/app
-WORKDIR ${APP_CLIENT_PATH}
+WORKDIR /app
 
-# Copy only necessary files for npm install
+# Lockfile + vite config first so the npm install layer caches across
+# unrelated source edits.
 COPY --from=repository-root package.json package-lock.json vite.config.js ./
-
-# Install dependencies
 RUN npm ci --no-audit --no-fund
 
-# Copy source files needed for build
+# Source for `npm run build`. Vite emits to /app/public/build, which the
+# api_app_builder stage copies out.
 COPY --from=repository-root assets/ ./assets/
 COPY --from=repository-root public/client/ ./public/client/
-
-# Build the application with version info
 RUN npm run build
 
 
-######### API backend build ########
+################################
+# API backend build
+################################
+# itkdev/php8.4-fpm publishes two parallel series: `2.x.y` (Ubuntu),
+# tracked by `:latest`, and `alpine-1.4.x` (Alpine), tracked by
+# `:alpine`. `:alpine` is therefore a moving alias to the newest
+# `alpine-1.4.x` — convenient, but not reproducible across time.
+# TODO: pin to a specific `alpine-1.4.x` tag (or a digest) once we
+# settle on a baseline. Same caveat applies to the final stage below.
 FROM itkdev/php8.4-fpm:alpine AS api_app_builder
 LABEL maintainer="ITK Dev <itkdev@ba.aarhus.dk>"
 
 ARG APP_VERSION="develop"
 ARG APP_RELEASE_TIMESTAMP=0
 ARG APP_RELEASE_TIME=""
-ENV APP_CLIENT_PATH=/app \
-    APP_API_PATH=/var/www/html
 
 USER root
 
-# Add composer in from the official composer image (also alpine).
+# Pinned via the official composer image so the build doesn't depend on
+# whatever composer happens to ship in the FPM base.
 COPY --from=composer:2 /usr/bin/composer /usr/local/bin/composer
 
-WORKDIR ${APP_API_PATH}
+WORKDIR /var/www/html
 
 USER deploy
 
-# Copy only composer files first for better layer caching
-COPY --chown=deploy:deploy --from=repository-root composer.json composer.lock symfony.lock ${APP_API_PATH}/
-
-# Pre-install composer packages first (better image layer caching) - application code not present so have to be re-run
+# Two-pass composer install:
+#   1. Lockfile + composer.json only with --no-scripts. The vendor/ layer
+#      then survives unrelated source-code edits.
+#   2. After the full source COPY, re-run with scripts to finalise the
+#      autoloader and trigger Symfony's cache:clear hook.
+COPY --chown=deploy:deploy --from=repository-root composer.json composer.lock symfony.lock ./
 RUN APP_ENV=prod composer install --no-dev -o --classmap-authoritative --no-scripts
 
-# Copy application source (needed for build step)
-COPY --chown=deploy:deploy --from=repository-root ./ ${APP_API_PATH}/
+COPY --chown=deploy:deploy --from=repository-root ./ ./
 
-# Copy javascript build files. This ensures that vite manifest files are availiable when "composer insatll"
-# triggers a "cache:clear" enabling the vite bundle to generate cache configuration files
+# Vite manifest must be in place before the second composer install
+# triggers cache:clear, otherwise the vite bundle can't generate its
+# cache config files.
 # @see https://symfony-vite.pentatrion.com/guide/performance.html#caching-configuration-files-%F0%9F%8F%83
-COPY --chown=deploy:deploy --from=client_app_builder ${APP_CLIENT_PATH}/public/build ./public/build
+COPY --chown=deploy:deploy --from=assets_builder /app/public/build ./public/build
 
-# Re-run composer install after application code copied to image to complete install
 RUN APP_ENV=prod composer install --no-dev --optimize-autoloader --classmap-authoritative
 
-# Write release.json into the public root so the client (assets/shared/release-loader.js)
-# can fetch it at /release.json. Shape matches docs/release-example.json.
+# The client polls /release.json to detect when a screen should refresh;
+# shape per docs/release-example.json.
 RUN printf '{"releaseTimestamp": %s, "releaseTime": "%s", "releaseVersion": "%s"}\n' \
       "${APP_RELEASE_TIMESTAMP}" \
       "${APP_RELEASE_TIME}" \
       "${APP_VERSION}" \
       > public/release.json
 
 
-######## PHP-FPM (API) production image ########
+################################
+# PHP-FPM (API) production image
+################################
 FROM itkdev/php8.4-fpm:alpine
 LABEL maintainer="ITK Dev <itkdev@ba.aarhus.dk>"
 
-ENV APP_CLIENT_PATH=/app \
-    APP_API_PATH=/var/www/html \
-    APP_ENV=prod \
+ENV APP_ENV=prod \
     PHP_OPCACHE_ENABLED=1 \
     PHP_OPCACHE_VALIDATE_TIMESTAMPS=0 \
     PHP_OPCACHE_MAX_ACCELERATED_FILES=20000 \
@@ -87,23 +93,25 @@ ENV APP_CLIENT_PATH=/app \
 
 USER root
 
-# Add composer needed to run optimizations after config is loaded.
+# Needed at container start so the entrypoint can run
+# `composer dump-env prod` against the operator's runtime env.
 COPY --from=composer:2 /usr/bin/composer /usr/local/bin/composer
 
-# Download Prometheus php-fpm export.
+# Prometheus exporter for php-fpm pool stats; scraped by ops monitoring.
 COPY --from=hipages/php-fpm_exporter:2.2.0 /php-fpm_exporter /usr/local/bin/php-fpm_exporter
 
 COPY --chmod=0755 docker-entrypoint.sh /usr/local/bin/
 
 USER deploy
 
-WORKDIR ${APP_API_PATH}
+WORKDIR /var/www/html
 
-# Install the api application.
-COPY --chown=deploy:deploy --from=api_app_builder ${APP_API_PATH} .
-RUN mkdir -p ./config/secrets
+COPY --chown=deploy:deploy --from=api_app_builder /var/www/html .
 
-WORKDIR ${APP_API_PATH}
+# Mount point for the Symfony secrets vault.
+RUN mkdir -p ./config/secrets
 
+# Entrypoint compiles env vars to .env.local.php and warms the Symfony
+# cache before exec'ing CMD; CMD stays overridable for ad-hoc commands.
 ENTRYPOINT ["docker-entrypoint.sh"]
 CMD ["php-fpm"]