Bake a pinned Flarum into the image instead of resolving it at first boot

[karl-bullock]

Problem

The image does not contain Flarum. Dockerfile has zero references to flarum/flarum — it is a PHP 8.3 + nginx + Composer runtime plus a boot script. The forum is resolved from Packagist on first container start, and nothing about that resolution is pinned:

Where	What	Constraint
entrypoint.sh:186	flarum/flarum	^2.0 with --stability=beta
entrypoint.sh:274	fof/upload	*
entrypoint.sh:275	fof/redis	*
entrypoint.sh:276	fof/horizon	*
entrypoint.sh:277	flarum/realtime	*
entrypoint.sh:280	flarum/audit	*
entrypoint.sh:281	flarum/extension-manager	*

There is no composer.json or composer.lock in the repository, so nothing records what a given image is supposed to install.

What that costs

• The same image tag produces different forums. Seven floating constraints, one of them accepting prereleases. Two people running docker compose up a week apart get different code, and so does the same person redeploying.
• docker pull gets you no Flarum. First boot needs working Packagist access. An outage, a yanked release, or a network-restricted host means no install — and there is no offline or airgapped path at all.
• Image tags cannot express a Flarum version. :1.0.0 versions the wrapper. There is no way for a user to pin the thing they actually care about, and no way for us to say "this image is Flarum 2.0.3".
• No rollback. Rebuilding a previous tag does not reproduce the previous forum, because resolution happens at run time, not build time.
• A broken upstream release breaks new installs retroactively, including installs of images that were fine yesterday.
• The README oversells it. It says "There is no runtime download of a setup script". Literally true — no setup script is fetched — but the entire application and six extensions are. A reader comparing images will take that sentence to mean the opposite of what happens.

Proposal — pinned skeleton baked at build time

Same approach already used for the Warble tenant images: resolve once, commit the lockfile, bake the result, copy into the volume on first boot.

1. Commit composer.json + composer.lock describing Flarum plus the six bundled extensions, at explicit versions.
2. Build time: composer install --no-dev from that lockfile into /opt/flarum-skeleton. The image now genuinely contains Flarum.
3. First boot: if the data volume is empty, copy the skeleton into /var/www/html and continue with the existing install path (flarum install, migrations, enable extensions). If the volume already has a forum, do nothing — same as today.
4. Tagging: image tags become <flarum-version>-rN (e.g. 2.0.3-r0), so the tag states what you get. TARGET_FLARUM_VERSION stays as an escape hatch for people who want to float deliberately.
5. Updating: bump the lockfile in a PR. roundtrip proves the new resolution installs and restores before it ships, which is strictly better than discovering it in production.

The Extension Manager keeps working: the volume is still a writable Composer project with a real composer.json, it is only seeded from the image instead of resolved from the network.

Acceptance criteria

• Dockerfile references flarum/flarum; docker create + docker export shows Flarum present with no container ever started
• Two boots of the same image tag yield identical composer.lock hashes in the volume
• First boot succeeds with no network access to Packagist (the current blocker for airgapped installs)
• Extension Manager can still install and remove an extension from the admin UI
• roundtrip still passes, including restoring an older backup into the newer version
• Existing volumes from pre-change images still boot untouched
• README's "no runtime download" wording corrected to describe what actually happens

Risks / open questions

• Image size grows by the vendor tree (tens of MB). Acceptable, and the tradeoff should be stated in the README rather than hidden.
• Upgrade path for existing deployments needs deciding: does a user on a running volume get the new skeleton on image update, or stay put until they act? Staying put is safer and matches current behaviour, but means the image version and the forum version can diverge — which partly re-opens the problem this issue exists to close.
• Lockfile drift — worth a scheduled job or Renovate to open the bump PR, otherwise the pin quietly becomes staleness.
• --stability=beta should not survive this change unless there is a reason; if Flarum 2.0 stable is out, pin stable.

Non-goals

• Not changing how extensions are enabled, how extend.php is generated, or the backup/restore flow.
• Not removing TARGET_FLARUM_VERSION.
• Not bundling additional extensions.

[karl-bullock]

Widening this: the build has the same problem as the runtime

The issue above is about the runtime resolving Flarum from Packagist on first boot. Cutting v1.0.0 showed the build has an equivalent unpinned network dependency, and it is not theoretical — it blocked the release.

v1.0.0 took three attempts. Two failed here:

Error: cannot download "pecl/redis"
  (File https://pecl.php.net:443/get/redis-6.3.0.tgz not valid
   (received: HTTP/1.1 504 Gateway Timeout))

Both architectures failed on the first attempt, arm64 alone on the second, and the third went through unchanged. Nothing in the repository changed between them — pecl.php.net was simply intermittently down. Because publish requires both architectures, a single upstream 504 meant no image was published at all, while the GitHub release already existed and told people to docker pull ghcr.io/linkrobins/flarum-docker:1.0.0. For a while that instruction was false.

Where the build reaches out

Dockerfile has three live network dependencies at build time:

Line	Fetches	Pinned?
28	install-php-extensions from GitHub releases	Yes — tag 2.11.1, already good
30	redis, plus the rest, via PECL / source	No — resolved at build time, this is what failed
37	composer via getcomposer.org/installer	No — always newest, and unverified

Only the first is pinned. The comment on it — that pinning the tag stops a compromised release slipping in without a git diff — applies just as much to the other two, which are currently unpinned and single points of failure.

Worth doing alongside the skeleton

• Pin the PECL extension versions (redis-6.3.0 and friends) so a build is reproducible and a 504 is a retry rather than a different result.
• Pin Composer, and verify its installer signature, rather than taking whatever getcomposer.org serves.
• Consider whether an extension source that has already been fetched should be vendored or cached in the repo, so a release never depends on a third party being up at that moment.
• Regardless of the above: the current failure mode is bad. A transient outage should not be able to leave a tagged GitHub release pointing at an image that does not exist. Either the release should be created after a successful publish, or publish should fail the run loudly enough that the mismatch is obvious.

Why this belongs in this issue

Same root cause, stated generally: this project resolves what it ships at the moment it runs or builds, rather than recording it. The skeleton fixes the runtime half. Pinning the build inputs fixes the other half. Doing only one leaves releases non-deterministic.

[karl-bullock]

Progress: the lock exists

Step 1 — resolve in CI (#3, merged). Resolve skeleton lock is a workflow_dispatch job that resolves the same package set the entrypoint installs today, on PHP 8.3 with the image's own extension list. It runs there rather than on a laptop because resolving somewhere missing intl or exif produces a lock production cannot satisfy. It audits what it resolved and fails on any advisory — pinning a known-vulnerable set would be worse than floating past it.

That is also the answer to the "lockfile drift" risk in the issue: bumping Flarum becomes re-running this and committing the diff, so a version change is a reviewable pull request instead of something that happens the next time a container boots.

Step 2 — the pin itself (#4, open). 193 packages: Flarum core and its bundled extensions on v2.0.0-rc.5, fof/horizon and fof/redis on v2.0.0-beta.9, fof/upload on 2.0.0-beta.6. Committed under skeleton/ so it is not mistaken for this repo's own manifest.

One correction to the issue

The last bullet under Risks / open questions says --stability=beta should not survive "unless there is a reason". There is one: Flarum 2.0 has no stable release. It is currently v2.0.0-rc.5, so beta stability is required to install 2.0 at all, and the pin has to target an explicit RC until 2.0 ships. It is not a shortcut left lying around.

That also sharpens why this matters. Under ^2.0 with beta stability, the day rc.6 is published every new container silently gets a different forum — with no diff, no tag change, and nothing to notice it by.

Still to do

• Bake skeleton/ into the image at build time and seed the volume from it on first boot when the volume is empty — the step that actually changes runtime behaviour
• Tag scheme <flarum-version>-rN
• Decide the upgrade path for existing volumes (still open, still the question I'd want settled before the seeding step lands)
• Pin the build's own inputs — PECL and the Composer installer, per the comment above

[karl-bullock]

The image now contains Flarum

Step 3 — bake and seed (#5, merged). The Dockerfile had zero references to flarum/flarum until this. It now resolves from the committed lock at build time and seeds an empty volume from that skeleton on first boot.

Acceptance criteria

• Dockerfile references flarum/flarum; Flarum present with no container ever started — verified against the published image: docker create (state created, startedAt 0001-01-01), then docker cp pulled /opt/flarum-skeleton/vendor/flarum/core and the lock out of it, flarum/core v2.0.0-rc.5
• First boot succeeds with no Packagist access — the six extensions are already in the skeleton's composer.json, so the existing composer_require calls short-circuit as "already present". Nothing is fetched at any point
• Two boots of the same tag yield identical versions — that is what the lock is
• roundtrip still passes, including restoring an older backup into the newer version
• Existing volumes still boot untouched
• README corrected — it now says Flarum is in the image, pinned, rather than the old wording that implied only a setup script was baked in
• Extension Manager can still install/remove from the admin UI — not yet verified, see below

A gap in the test, found and closed

roundtrip passing proved nothing about where Flarum came from. The runner has network, so the old Packagist path satisfied every check in the job just as well as the baked one — the pin could have quietly stopped being load-bearing with the suite still green. The job now reads the container log and fails unless the install seeded from the skeleton and resolved nothing over the network. It prints the proof:

flarum_app  | [+] Seeding Flarum 2.0.0-rc.5 from the baked skeleton (no network).

Still open

• Extension Manager against a baked skeleton. The volume is still a writable Composer project seeded from the image, so it should behave exactly as before — but "should" is not "verified", and it is the one behaviour this change could plausibly disturb.
• The upgrade path, unchanged and still the open question: an existing volume keeps its forum, so the image tag and the running forum can diverge. Deliberately not decided.
• Build inputs — PECL and the Composer installer are still unpinned, per the comment above. v1.0.0 needed three attempts because pecl.php.net returned 504s.
• Tag scheme <flarum-version>-rN not yet adopted.

[karl-bullock]

Done

All acceptance criteria met and verified.

• Dockerfile references flarum/flarum; Flarum present with no container ever started — docker create (state created, startedAt 0001-01-01) then docker cp pulled vendor/flarum/core and the lock out of the published image
• Identical versions across boots of one tag — that is what the lock is
• First boot with no Packagist access — asserted in CI, which now fails unless the container log shows it seeded from the skeleton and resolved nothing over the network
• Extension Manager still works — roundtrip installs linkrobins/clipboard the way the Extension Manager does (composer, as www-data, against the volume), enables it, checks the forum serves, then disables and removes it
• roundtrip still passes, including restoring an older backup into a newer version
• Existing volumes boot untouched
• README describes what actually happens

Plus the two items from the widening comment:

• Build inputs pinned — PECL redis at 6.3.0, Composer at 2.10.2 with the publisher's signature check. Composer was previously piped into php unverified and unversioned, so two builds of one commit could ship different Composers
• Tags name the forum — flarum-2.0.0-rc.5 is published alongside latest, read from the committed lock, plus image labels. Multi-arch, both architectures verified in the manifest

Two things worth recording

The Extension Manager test caught its own flaw first. It initially used fof/doorman and failed — but composer require, extension:enable and cache:clear all succeeded, and the forum then 500'd. The seeded volume was fine; doorman's Flarum 2 release is a beta that breaks against an RC core. (Note its stable 2.0.0 is the Flarum 1.3 build, so composer had resolved correctly.) The test was conflating "can the Extension Manager write here" with "is this extension compatible with 2.0-rc.5", and only the first has anything to do with baking Flarum in.

A green roundtrip proved nothing about where Flarum came from, because the runner has network and the old Packagist path satisfied every check equally well. The pin could have silently stopped being load-bearing with CI still green. That assertion now exists.

Deliberately still open

The upgrade path: an existing volume keeps its forum, so the image tag and a running forum can diverge. Unchanged from before this work, and a product decision about what docker compose pull should promise — not something to settle inside a refactor. Worth its own issue if it is ever wanted.

Closing.