haylan/Smart-Tablet-Screen
1
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases Wiki Activity

docs(research): calendar webhook support + FrankenPHP Docker setup

Browse Source 
Resolves wayfinder tickets #2 and #3 on the calendar-backend
groundwork map (#1):

- smart-tablet-screen-calendar-webhooks.md: Nextcloud CalDAV push
  support (none usable — Mail-in-a-Box's bundled Nextcloud predates
  the Webhooks app) vs Microsoft Graph webhook subscriptions
  (supported, with renewal-job requirements).
- smart-tablet-screen-frankenphp-docker.md: FrankenPHP-based dev/prod
  Docker image and compose setup for the Symfony backend.

Also gitignore .scratch/, the repo-local scratchpad directory for
throwaway working files.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QshNimeB3TVU2vMjN7tEuz
This commit is contained in:
haylan
2026-09-01 21:37:53 +02:00
co-authored by Claude-Bot
parent 299343b83b
commit 07670c5f44
3 changed files with 166 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/research/smart-tablet-screen-calendar-webhooks.md
+36
View File
@@ -0,0 +1,36 @@
# Smart Tablet Screen — Calendar Webhook vs Polling Research
Research date: 2026-09-01. All claims below are sourced against primary/official documentation, source code, or first-party API references — not third-party summaries. Each claim links its own source. Companion to `docs/research/smart-tablet-screen-stack.md` (§1–2 cover the base CalDAV/Graph decision this doc extends for change-detection strategy) — written for issue #2, feeds issue #5 ("Cache refresh trigger mechanism").
---
## 1. Nextcloud CalDAV (Mail-in-a-Box bundled): webhook vs sync-token
- **Mail-in-a-Box pins an old Nextcloud version.** Its own setup script hardcodes `nextcloud_ver=27.1.11` (with a matching SHA1 for the downloaded tarball) — this is the version actually installed on any Mail-in-a-Box box today, not whatever is "latest" upstream. — [mail-in-a-box/mailinabox `setup/nextcloud.sh`, GitHub](https://github.com/mail-in-a-box/mailinabox/blob/main/setup/nextcloud.sh)
- **Nextcloud's own "Webhooks" capability (`webhook_listeners` app) only exists from Nextcloud 30.0.0 onward.** It ships as an app inside the `nextcloud/server` monorepo itself (`apps/webhook_listeners/`, added by [PR #45475](https://github.com/nextcloud/server/pull/45475)) — it is not a separately-maintained GitHub repo (`nextcloud/webhook_listeners` does not exist as an independent project; the app lives at [`nextcloud/server/apps/webhook_listeners`](https://github.com/nextcloud/server/tree/master/apps/webhook_listeners)). — [nextcloud/server PR #45475, GitHub](https://github.com/nextcloud/server/pull/45475), [nextcloud/server `apps/webhook_listeners`, GitHub](https://github.com/nextcloud/server/tree/master/apps/webhook_listeners)
- **Consequence: Mail-in-a-Box's Nextcloud 27.1.11 predates `webhook_listeners` by three major versions (27 → 30).** The app cannot be present or enabled on a Mail-in-a-Box-bundled Nextcloud instance today — it isn't a matter of the household needing to install anything extra; the underlying Nextcloud version doesn't ship the feature at all. This directly answers the ticket's "is it realistic to assume it's present" question: no.
- **Even where present (Nextcloud ≥30), `webhook_listeners` does support calendar/event change events.** Nextcloud's own admin manual lists supported event categories including calendar object creation, update, deletion, and movement between calendars (`CalendarObjectCreatedEvent`, `CalendarObjectUpdatedEvent`, `CalendarObjectDeletedEvent`, `CalendarObjectMovedEvent`), alongside file, tag, Forms, and Tables events. It comes bundled with core Nextcloud but is **not enabled by default** — an admin must run `occ app:enable webhook_listeners`, and registering a webhook additionally requires an admin (or delegated-admin) account via the OCS API. Delivery itself runs through a background job, triggered roughly every 5 minutes by default rather than instantly. — [Webhook Listeners, Nextcloud Administration Manual, docs.nextcloud.com](https://docs.nextcloud.com/server/stable/admin_manual/webhook_listeners/index.html)
- **Absent (or unusable) webhooks, Nextcloud's CalDAV implementation supports WebDAV Collection Sync per RFC 6578** — the standard, protocol-level alternative to full re-fetch. The client requests a sync-token via a `sync-collection` REPORT; the server replies only with items created/modified/deleted since that token, plus a new token to store for the next round. This is a generic CalDAV/WebDAV mechanism (not Nextcloud-specific), defined by the IETF standard itself. — [RFC 6578 — Collection Synchronization for WebDAV, datatracker.ietf.org](https://datatracker.ietf.org/doc/html/rfc6578)
- **This sync-token mechanism still requires a client-initiated poll** — RFC 6578 makes each poll cheap (only the delta is returned) but does not give the server a way to push to the client; the client must periodically re-issue the `sync-collection` REPORT to learn whether anything changed. There is no server-initiated notification path in the CalDAV/WebDAV spec itself, and (per the point above) Mail-in-a-Box's pinned Nextcloud version has no bundled app that adds one.
## 2. Microsoft Graph webhook change notifications for calendar events
- **Graph's `/subscriptions` API explicitly supports the `event` resource.** The Outlook `event` resource is listed among subscribable resources with resource path `/me/events` / `/users/{id}/events`, supporting both delegated (personal Microsoft account, via `Calendars.Read`) and application permissions — confirming free Outlook.com/personal-account calendars are covered, consistent with §2 of the base stack research. — [Create subscription, Microsoft Graph v1.0, learn.microsoft.com](https://learn.microsoft.com/en-us/graph/api/subscription-post-subscriptions?view=graph-rest-1.0), [Set up notifications for changes in resource data — Supported resources, learn.microsoft.com](https://learn.microsoft.com/en-us/graph/change-notifications-overview#supported-resources)
- **Creating a subscription**: `POST https://graph.microsoft.com/v1.0/subscriptions` with a JSON body containing `changeType` (`created`, `updated`, `deleted`, comma-separated as needed), `notificationUrl` (the app's public HTTPS webhook endpoint), `resource` (e.g. `/me/events`), `expirationDateTime`, and a required `clientState` secret the app later uses to confirm notifications genuinely came from Graph. A successful call returns `201 Created` with the subscription object including its `id`. — [Create subscription, Microsoft Graph v1.0, learn.microsoft.com](https://learn.microsoft.com/en-us/graph/api/subscription-post-subscriptions?view=graph-rest-1.0)
- **Validation-token handshake (mandatory, happens synchronously during subscription creation)**: Graph sends `POST https://{notificationUrl}?validationToken={opaqueToken}` with `Content-Type: text/plain`. The app's endpoint must URL-decode the token and respond within **10 seconds** with HTTP `200 OK`, `Content-Type: text/plain`, and a body containing exactly the plain-text (decoded) validation token — an HTML/JS-encoded response fails validation. If this handshake fails, Graph does not create the subscription (`400 Bad Request`) at all. — [Receive change notifications through webhooks — notificationUrl validation, learn.microsoft.com](https://learn.microsoft.com/en-us/graph/change-notifications-delivery-webhooks#notificationurl-validation)
- **Notification payload shape delivered on change**: a `POST` to `notificationUrl` carrying a `changeNotificationCollection` — a JSON object with a `value` array, where each entry has `id`, `subscriptionId`, `subscriptionExpirationDateTime`, `clientState` (must be checked against the value set at creation to reject spoofed notifications), `changeType`, `resource` (path to the changed item), `tenantId`, and a `resourceData` block (`@odata.type`, `@odata.id`, `@odata.etag`, `id`) identifying the changed resource — by default this is a **basic notification** (no event body/fields, just enough to know something changed and re-fetch it). A single `POST` may bundle multiple notifications across subscriptions. The app must return `2xx` within 3 seconds (`200` if processed inline, `202` if merely queued) or Graph begins retrying for up to 4 hours with exponential backoff before giving up. — [Receive change notifications through webhooks, learn.microsoft.com](https://learn.microsoft.com/en-us/graph/change-notifications-delivery-webhooks)
- **Maximum subscription duration for `event` (and `message`, `contact`) is under 7 days: 10,080 minutes.** (Rich/resource-data subscriptions on these resources are capped much lower, at under 1 day — 1,440 minutes — but this project would use basic notifications and re-fetch via the API, so the 10,080-minute ceiling applies.) Graph subscriptions are explicitly **not indefinite** — the docs state apps "need to renew their subscriptions before the expiration time; Otherwise, they need to create a new subscription." — [Set up notifications for changes in resource data — Subscription lifetime, learn.microsoft.com](https://learn.microsoft.com/en-us/graph/change-notifications-overview#subscription-lifetime)
- **Renewal**: `PATCH https://graph.microsoft.com/v1.0/subscriptions/{id}` with a JSON body containing only the new `expirationDateTime` (must still respect the same per-resource max-duration ceiling from the point above — a single renewal cannot push the expiry further than ~7 days out from the renewal call). A successful renewal returns `200 OK` with the updated subscription object. Each change notification also carries the current `subscriptionExpirationDateTime`, which the docs recommend using as a cue for when to renew. Optionally, a `lifecycleNotificationUrl` can be registered alongside `notificationUrl` to receive an explicit "subscription about to expire" / "reauthorization required" push rather than relying solely on tracking dates client-side. — [Receive change notifications through webhooks — Subscription lifecycle / Renew a subscription, learn.microsoft.com](https://learn.microsoft.com/en-us/graph/change-notifications-delivery-webhooks#subscription-lifecycle)
---
## Recommended approach
For issue #5 ("Cache refresh trigger mechanism"), use two different strategies per backend, since only one of the two sources has a usable push mechanism:
- **Nextcloud/Mail-in-a-Box (CalDAV)**: **poll with WebDAV Collection Sync (RFC 6578 sync-token)**, not webhooks. Mail-in-a-Box's pinned Nextcloud (27.1.11) predates the `webhook_listeners` app (Nextcloud ≥30) entirely, so no webhook path exists on this backend without the household upgrading Nextcloud out-of-band from Mail-in-a-Box's own installer — not something to build a dependency on. Implement the Symfony CalDAV client to store each calendar's sync-token, issue a periodic `sync-collection` REPORT (e.g. on the cache-refresh job's normal cadence), and only re-parse/update the SQLite cache for the returned deltas rather than re-fetching the whole calendar every cycle.
- **Microsoft Graph**: **use webhook change notifications** (`/subscriptions` on `/me/events`), since Graph explicitly supports it end-to-end for both personal and work/school accounts. Implementation shape:
1. Symfony backend exposes a public HTTPS `notificationUrl` endpoint that (a) handles the synchronous `validationToken` handshake (echo it back as `text/plain`, `200 OK`, within 10s) and (b) accepts subsequent `POST` change-notification payloads, checks `clientState`, and — since notifications are basic (no event data) — triggers a re-fetch of the changed event/calendar into the SQLite cache.
2. Create the subscription with `changeType: "created,updated,deleted"`, `resource: "/me/events"`, and an `expirationDateTime` no more than ~7 days out (10,080-minute cap).
3. **Renewal is mandatory, not optional** — schedule a recurring job (well inside the 7-day window, e.g. daily) that `PATCH`es the subscription with a fresh `expirationDateTime`; a lapsed subscription silently stops delivering notifications. Track `subscriptionExpirationDateTime` from incoming notifications, or subscribe to `lifecycleNotificationUrl` events, as a second signal so a missed renewal is self-detected rather than silently going stale.
4. Keep a **low-frequency polling fallback** even with the webhook wired up — Graph notifications can be delayed, dropped after throttling, or silently lapse if renewal fails; a periodic full-resync (e.g. once daily) against `/me/events` guards against any single missed/expired subscription leaving the dashboard's cache stale indefinitely.
docs/research/smart-tablet-screen-frankenphp-docker.md
+127
View File
@@ -0,0 +1,127 @@
# Smart Tablet Screen — FrankenPHP Docker Research
Research date: 2026-09-01. Scope: FrankenPHP Docker image setup for this project's Symfony backend, for the dev/prod split and PHP extensions this map needs (SQLite cache via `pdo_sqlite`, Symfony secrets vault via `sodium`). All claims sourced against primary sources only — frankenphp.dev's own docs, the `php/frankenphp` and `dunglas/symfony-docker` GitHub repos (the latter is FrankenPHP's own docs page's recommended reference implementation, see §2), Docker Hub, and one claim verified directly by running the real image (`docker run … php -m`, noted as such). This report does not redo `smart-tablet-screen-stack.md` or `smart-tablet-screen-config-secrets.md`, and does not modify them.
---
## 1. Recommended base image/tag
Per FrankenPHP's own Docker docs:
- The image is `dunglas/frankenphp` on Docker Hub. Tags follow the pattern **`<frankenphp-version>-php<php-version>-<os>`**, e.g. `dunglas/frankenphp:1.2.3-php8.4-bookworm`. Supported PHP versions listed: 8.2, 8.3, 8.4, 8.5. OS variants: `trixie` and `bookworm` (Debian) or `alpine`. — [Docker, frankenphp.dev/docs/docker/](https://frankenphp.dev/docs/docker/)
- **Debian variants are recommended over Alpine** by the same page.
- FrankenPHP's own reference Symfony Dockerfile (§2) pins `dunglas/frankenphp:1-php8.5` — the major-version-only FrankenPHP tag (`1`) paired with a specific PHP minor (`php8.5`), no explicit OS suffix (defaults to the image's default Debian base). Confirmed directly against the real image on Docker Hub (`docker pull dunglas/frankenphp:1-php8.5` succeeded, digest `sha256:f92d81eb…`).
**For this project**: `dunglas/frankenphp:1-php8.5` (or pin a specific PHP version this project targets, e.g. `1-php8.4`), Debian-based — matches both FrankenPHP's own recommendation and its own reference Symfony setup.
## 2. FrankenPHP's Symfony guide: Dockerfile structure and worker mode
Per FrankenPHP's own Symfony guide:
- **"For Symfony projects, we recommend using Symfony Docker, the official Symfony Docker setup maintained by FrankenPHP's author."** — [Symfony, frankenphp.dev/docs/symfony/](https://frankenphp.dev/docs/symfony/). This points at [dunglas/symfony-docker](https://github.com/dunglas/symfony-docker) on GitHub as the primary source for the actual Dockerfile/compose shape, rather than the guide page itself spelling one out inline.
- That repo's `Dockerfile` (fetched directly, `main` branch) is a **three-stage** build:
- `frankenphp_base` — shared stage: installs `install-php-extensions @composer apcu intl opcache zip`, sets `PHP_INI_SCAN_DIR`, copies in the app's `php.ini` overrides, entrypoint script, and Caddyfile. Ends with a `HEALTHCHECK` hitting FrankenPHP's own `/metrics` admin endpoint and `CMD [ "frankenphp", "run", "--config", "/etc/frankenphp/Caddyfile" ]`.
- `frankenphp_dev` (extends `frankenphp_base`) — sets `APP_ENV=dev`, `FRANKENPHP_WORKER_CONFIG=watch`, switches to `php.ini-development`, installs `xdebug`, adds a non-root user, and runs `frankenphp run --config … --watch` (file-watching hot reload).
- `frankenphp_prod_builder` (extends `frankenphp_base`) → `frankenphp_prod` — builder stage runs `composer install --no-dev`, `composer dump-autoload --classmap-authoritative --no-dev`, asset-map compile, etc., then a **separate final stage `FROM debian:13-slim`** copies over only the compiled FrankenPHP/PHP binaries, extensions, shared libraries (via `libtree`), certs, and the built `/app` — producing a minimal prod image that doesn't carry build tooling. Runs as `www-data`.
— [`Dockerfile`, dunglas/symfony-docker, raw.githubusercontent.com](https://raw.githubusercontent.com/dunglas/symfony-docker/main/Dockerfile)
- **Worker mode**: FrankenPHP's worker docs describe it as keeping the application booted in memory between requests — *"Boot your application once and keep it in memory. FrankenPHP will handle incoming requests in a few milliseconds."* It's enabled via the `FRANKENPHP_CONFIG` env var (`worker /path/to/script.php`) or a Caddyfile `worker` directive; by default 2 workers per CPU are started. — [Worker Mode, frankenphp.dev/docs/worker/](https://frankenphp.dev/docs/worker/)
- The Symfony guide states worker mode is **natively supported since Symfony 7.4**; for older Symfony versions it requires installing the `runtime/frankenphp-symfony` Composer package (`APP_RUNTIME=Runtime\FrankenPhpSymfony\Runtime`). — [Symfony, frankenphp.dev/docs/symfony/](https://frankenphp.dev/docs/symfony/)
- **Is it recommended for prod?** The worker-mode docs don't blanket-recommend or discourage it — they frame it as an opt-in perf feature with a real cost: *"many libraries and legacy code still leak memory"* between requests since the app no longer boots fresh per request, and document mitigations (restarting the worker after N requests, graceful reloads via the Caddy admin API). Symfony-docker's own dev/prod split reflects this: **dev** sets `FRANKENPHP_WORKER_CONFIG=watch` (worker mode + file-watch, for hot-reload DX) while **prod's `CMD` runs plain `frankenphp run` with no worker config set** — i.e. the reference implementation does **not** turn worker mode on by default in prod; it's left as an explicit opt-in once the app has been audited for state leaks, not a default-on prod setting.
## 3. PHP extensions: `pdo_sqlite` and `sodium`
- FrankenPHP's own Dockerfile (builder stage, `php/frankenphp` repo, `main` branch) pre-installs the `install-php-extensions` script (from [mlocati/docker-php-extension-installer](https://github.com/mlocati/docker-php-extension-installer)) into every FrankenPHP image at `/usr/local/bin/install-php-extensions` — confirmed by the `curl … -o /usr/local/bin/install-php-extensions` step in the image's own build. — [`Dockerfile`, php/frankenphp, raw.githubusercontent.com](https://raw.githubusercontent.com/php/frankenphp/main/Dockerfile)
- FrankenPHP's docs document this as the standard way to add extensions: `RUN install-php-extensions pdo_mysql gd intl zip opcache` — no `docker-php-ext-install`/manual compile step needed; it's the same convention `dunglas/symfony-docker`'s own Dockerfile uses (`install-php-extensions @composer apcu intl opcache zip`, §2). — [Docker, frankenphp.dev/docs/docker/](https://frankenphp.dev/docs/docker/)
- **`pdo_sqlite` and `sodium` are already enabled by default in this project's target image** — verified directly, not inferred: `docker run --rm dunglas/frankenphp:1-php8.5 php -m` lists `pdo_sqlite`, `sqlite3`, and `sodium` in `[PHP Modules]` with no extra install step. This matches the general official-PHP-image baseline documented in the extension installer's own README, which explicitly excludes "pre-installed PHP extensions" from its supported-extensions table and shows the same `pdo_sqlite`/`sodium` pairing pre-enabled in `php:8.5-cli`'s `php -m` output. — [`docker-php-extension-installer` README, mlocati/docker-php-extension-installer, GitHub](https://github.com/mlocati/docker-php-extension-installer), and direct `docker run dunglas/frankenphp:1-php8.5 php -m` output (this research).
- This also lines up with FrankenPHP's own build: `php/frankenphp`'s builder stage installs `libsqlite3-dev` and `libsodium-dev` as build dependencies for linking the FrankenPHP binary itself (its Caddy layer uses SQLite storage; libsodium is a common Go/Caddy TLS dependency), which is a separate concern from — but consistent with — PHP's own `pdo_sqlite`/`sodium` modules being pre-built in. — [`Dockerfile`, php/frankenphp, raw.githubusercontent.com](https://raw.githubusercontent.com/php/frankenphp/main/Dockerfile)
**For this project**: no `RUN install-php-extensions pdo_sqlite sodium` line is strictly required — both are already on by default in `dunglas/frankenphp:1-php8.5`. Recommend still listing them explicitly (harmless — `install-php-extensions` no-ops on an already-enabled extension) as executable documentation of the requirement, alongside whatever extensions this project's own composer.json / `symfony/requirements-checker` actually demands (e.g. `intl`, `opcache`, `zip`, `apcu` per the symfony-docker baseline in §2) — don't rely on an undocumented default that could change across base-image updates.
## 4. Dev/prod `docker-compose.yml` + override structure (single service, no reverse proxy)
Per `dunglas/symfony-docker`'s own compose files (fetched directly, `main` branch) — used here only for the **base-vs-override responsibility split** and the **named `var/` volume** pattern; this repo's map has already ruled out the multi-service/reverse-proxy shape that repo also ships (Mercure, Postgres, Caddy ports), so only the single-service mechanics are carried over:
- **Base `compose.yaml`** carries the service's env vars (with `${VAR:-default}` shell-style defaults) and named volumes. In symfony-docker this is `caddy_data`/`caddy_config` (TLS state) — for this project, the base file's equivalent responsibility is the **named `var/` volume** so the SQLite cache file (and Symfony's `var/cache`, `var/log`) survive container rebuilds: a top-level `volumes: app_var:` declaration, mounted at `/app/var` (or wherever this app's `var/` lives) on the service. — [`compose.yaml`, dunglas/symfony-docker, raw.githubusercontent.com](https://raw.githubusercontent.com/dunglas/symfony-docker/main/compose.yaml)
- **`compose.override.yaml`** (Docker Compose auto-loads this file alongside `compose.yaml` for local `docker compose up`, per [Compose's own merge-and-override docs](https://docs.docker.com/compose/how-tos/multiple-compose-files/merge/)) carries everything dev-specific:
- `build: { context: ., target: frankenphp_dev }` — pins the build to the dev stage of the multi-stage Dockerfile (§2), so `docker compose up` locally builds/runs `frankenphp_dev`, never the prod image.
- `volumes: - ./:/app` — bind-mounts the whole source tree over the built image for hot-reload; the file adds `- /app/var` as an **anonymous volume entry layered on top of that bind mount** specifically so `var/` (cache/log/the SQLite file) is *not* shadowed by the host bind-mount — this repo would instead point that at the **named** `app_var` volume from the base file, per the map's requirement that the SQLite cache persist across rebuilds (an anonymous volume gets discarded on `docker compose down -v` / recreate; a named volume declared in the base file does not).
- `environment:` overrides — `FRANKENPHP_WORKER_CONFIG: watch`, `APP_ENV: "${APP_ENV:-dev}"`, `XDEBUG_MODE`, etc. — i.e. dev-only env vars/toggles layered over whatever the base file / built image already sets.
— [`compose.override.yaml`, dunglas/symfony-docker, raw.githubusercontent.com](https://raw.githubusercontent.com/dunglas/symfony-docker/main/compose.override.yaml)
- **Prod** runs `compose.yaml` alone (`docker compose -f compose.yaml up`, or any deploy tooling that skips the override), which builds without a `target:` override — Docker's multi-stage build convention is that omitting `target:` builds the **last** stage in the Dockerfile, which in the §2 Dockerfile is `frankenphp_prod`. — [Compose file `build.target`, docs.docker.com/reference/compose-file/build/#target](https://docs.docker.com/reference/compose-file/build/#target)
**For this project**: same two-file split, minus everything reverse-proxy/multi-service (no Caddy TLS volumes, no Mercure/Postgres blocks) — single `php`/`app` service, named `var/` volume in the base file for SQLite persistence, dev-only bind-mount + build target + env overrides in the override file.
---
## Recommended approach
1. **Base image**: `dunglas/frankenphp:1-php8.5` (or pin the PHP minor this project settles on) — Debian-based per FrankenPHP's own recommendation (§1).
2. **Dockerfile**: three-stage, following `dunglas/symfony-docker`'s reference shape (§2) — a shared base stage (extensions, Caddyfile, entrypoint), a `dev` stage (Xdebug, watch mode, non-root user), and a `prod_builder` → `prod` pair (Composer `--no-dev` install, asset-map compile, copied into a minimal final stage).
3. **Extensions**: `pdo_sqlite` and `sodium` are already enabled in this base image (§3, verified by running it) — no extra `install-php-extensions` step is *required*, but list them explicitly anyway alongside the project's other needed extensions (`intl`, `opcache`, `zip`, `apcu` per the symfony-docker baseline) as documentation that doesn't rely on an implicit default.
4. **Worker mode**: leave off by default in prod (matches the reference implementation, §2) — it's a real perf win but requires auditing the app for per-request state leaks first; enable only after that audit, not as part of this ticket's baseline setup.
5. **Compose**: base `docker-compose.yml` (single service, no reverse proxy per the map's decision) + `docker-compose.override.yaml` for dev, following the responsibility split in §4.
Illustrative shape only — not literal repo code:
```dockerfile
# Dockerfile (illustrative)
FROM dunglas/frankenphp:1-php8.5 AS frankenphp_base
WORKDIR /app
RUN install-php-extensions \
pdo_sqlite \
sodium \
intl \
opcache \
zip \
apcu
ENV PHP_INI_SCAN_DIR=":$PHP_INI_DIR/app.conf.d"
CMD ["frankenphp", "run", "--config", "/etc/frankenphp/Caddyfile"]
FROM frankenphp_base AS frankenphp_dev
ENV APP_ENV=dev
RUN mv "$PHP_INI_DIR/php.ini-development" "$PHP_INI_DIR/php.ini"
CMD ["frankenphp", "run", "--config", "/etc/frankenphp/Caddyfile", "--watch"]
FROM frankenphp_base AS frankenphp_prod_builder
ENV APP_ENV=prod
RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini"
COPY . .
RUN composer install --no-dev --optimize-autoloader
FROM dunglas/frankenphp:1-php8.5 AS frankenphp_prod
ENV APP_ENV=prod
COPY --from=frankenphp_prod_builder /app /app
WORKDIR /app
USER www-data
```
```yaml
# docker-compose.yml (illustrative) — base: prod-shaped, no target: override picks the last stage (frankenphp_prod)
services:
app:
build:
context: .
environment:
APP_ENV: prod
volumes:
- app_var:/app/var # named volume: SQLite cache + var/cache + var/log survive rebuilds
volumes:
app_var:
```
```yaml
# docker-compose.override.yaml (illustrative) — auto-loaded by `docker compose up`, dev only
services:
app:
build:
target: frankenphp_dev
volumes:
- ./:/app # bind-mount source for hot reload
- app_var:/app/var # keep the same named volume so var/ isn't shadowed by the bind mount above
environment:
APP_ENV: dev
FRANKENPHP_WORKER_CONFIG: watch
```
Why: `dunglas/frankenphp:1-php8.5` plus `install-php-extensions` is FrankenPHP's own documented convention (§1, §3); the three-stage dev/prod split and the base/override compose responsibility split both mirror FrankenPHP's own recommended reference implementation for Symfony (`dunglas/symfony-docker`, §2, §4) minus the reverse-proxy/multi-service pieces this project's map already decided against; the named `app_var` volume (rather than symfony-docker's anonymous `/app/var` volume) is the one deliberate deviation, needed specifically so the SQLite cache this map is designing persists across rebuilds rather than being discarded with the container.