Add Web/PWA image health endpoint and app tags #248

New issue

Closed

opened 2026-06-03 10:08:05 +00:00 by steve · 0 comments

steve commented

2026-06-03 10:08:05 +00:00

Owner

Follow up the initial Web/PWA Docker image work with an explicit health endpoint
and app-version image metadata.

Problem

The new lapisnotes/web image serves the PWA but does not expose a dedicated
health route for ingress/container health probes. The publish workflow also only
pushes latest and the short Git SHA, leaving deployments without image tags
that identify the Web/PWA package version.

Goal

Expose a cheap HTTP health endpoint and publish app-version image tags and OCI
metadata alongside the existing short SHA and latest tags.

Scope

Add a Caddy-served health route for the Web/PWA image.
Extend the publish workflow to derive the Web/PWA package version and publish
versioned tags.
Add relevant OCI labels for the app image.
Keep web and release specs current.

Non-goals

Do not add a Dockerfile HEALTHCHECK that would require copying a shell,
curl, or other probe binary into the distroless runtime.
Do not change app runtime behavior outside the health route.

Acceptance Criteria

The Web/PWA container returns HTTP 200 from /healthz with a small static
response and no SPA fallback dependency.
The publish workflow still pushes lapisnotes/web:<12-char-sha> and
lapisnotes/web:latest.
The publish workflow also pushes lapisnotes/web:<web-package-version> and
lapisnotes/web:v<web-package-version>.
The image carries OCI labels for title, description, source, revision,
version, and license.
Specs document the health endpoint and version tags.

Implementation Notes

Derive the version from packages/web/package.json in the workflow so the tag
follows the app package version.
Use a Caddy respond handler for /healthz; keep Docker image hardening by
avoiding extra runtime probe binaries.

Suggested Files or Specs To Inspect

docker/web/Caddyfile
.forgejo/workflows/publish-web.yml
packages/web/package.json
spec/src/20-packages/web/index.md
packages/web/spec.md
spec/src/80-maintenance/release-management.md

Validation Commands

pnpm -s check:format:root
pnpm check:all
make spec-lint
mdbook build spec
Docker runtime check when a Docker daemon is available:
curl -i http://localhost:8080/healthz

Follow-up to #247 — Publish Web/PWA Docker image

Follow-up Tasks

Implementation Summary

Added /healthz to the Web/PWA Caddy runtime, added package-version Docker Hub tags plus OCI app metadata labels, and updated web/release specs. Validated pnpm check:all, make spec-lint, and mdbook build spec; local Docker build/run health checks were blocked because no Docker daemon is available.

Follow up the initial Web/PWA Docker image work with an explicit health endpoint and app-version image metadata. ## Problem The new `lapisnotes/web` image serves the PWA but does not expose a dedicated health route for ingress/container health probes. The publish workflow also only pushes `latest` and the short Git SHA, leaving deployments without image tags that identify the Web/PWA package version. ## Goal Expose a cheap HTTP health endpoint and publish app-version image tags and OCI metadata alongside the existing short SHA and `latest` tags. ## Scope - Add a Caddy-served health route for the Web/PWA image. - Extend the publish workflow to derive the Web/PWA package version and publish versioned tags. - Add relevant OCI labels for the app image. - Keep web and release specs current. ## Non-goals - Do not add a Dockerfile `HEALTHCHECK` that would require copying a shell, curl, or other probe binary into the distroless runtime. - Do not change app runtime behavior outside the health route. ## Acceptance Criteria - The Web/PWA container returns HTTP `200` from `/healthz` with a small static response and no SPA fallback dependency. - The publish workflow still pushes `lapisnotes/web:<12-char-sha>` and `lapisnotes/web:latest`. - The publish workflow also pushes `lapisnotes/web:<web-package-version>` and `lapisnotes/web:v<web-package-version>`. - The image carries OCI labels for title, description, source, revision, version, and license. - Specs document the health endpoint and version tags. ## Implementation Notes - Derive the version from `packages/web/package.json` in the workflow so the tag follows the app package version. - Use a Caddy `respond` handler for `/healthz`; keep Docker image hardening by avoiding extra runtime probe binaries. ## Suggested Files or Specs To Inspect - `docker/web/Caddyfile` - `.forgejo/workflows/publish-web.yml` - `packages/web/package.json` - `spec/src/20-packages/web/index.md` - `packages/web/spec.md` - `spec/src/80-maintenance/release-management.md` ## Validation Commands - `pnpm -s check:format:root` - `pnpm check:all` - `make spec-lint` - `mdbook build spec` - Docker runtime check when a Docker daemon is available: `curl -i http://localhost:8080/healthz` ## Related Issues - Follow-up to #247 — [Publish Web/PWA Docker image](../closed/247-publish-web-pwa-docker-image.md) ## Follow-up Tasks ## Implementation Summary Added /healthz to the Web/PWA Caddy runtime, added package-version Docker Hub tags plus OCI app metadata labels, and updated web/release specs. Validated pnpm check:all, make spec-lint, and mdbook build spec; local Docker build/run health checks were blocked because no Docker daemon is available.

steve

2026-06-03 10:08:05 +00:00