Latest update may have broken the PHP build cache??

[wpeasy]

With the latest update; deploying on PHP 8.4, every deploy rebuilds PHP:

' The PHP image needs a rebuild (SpawnWP update or forced): this deploy takes about 5 minutes; the next ones about 35 seconds.' on every deploy.

Deployment has gone flakey. I deployed a site on 8.4, it rebuilt PHP and deployed properly. The site worked.
Deployed another 8.4 site. It said that PHP was already cached. However, got an error saying the container was not healthy.
Deployed again and got ' The PHP image needs a rebuild (SpawnWP update or forced): this deploy takes about 5 minutes; the next ones about 35 seconds.' on every deploy. again.

[wpeasy]

Actually. on the last deploy, deploy the ' The PHP image needs a rebuild (SpawnWP update or forced): this deploy takes about 5 minutes; the next ones about 35 seconds.' was there, but found the cached PHP, and deployed quickly.

Used my saved blueprint and got:

Error: This does not seem to be a WordPress installation.
The used path is: /var/www/html/
Pass --path=path/to/wordpress or run wp core download.
make: *** [Makefile:42: bootstrap] Error 1
!! Creation failed; rolling back partial resources...
❌ Exited with code 2

[wpeasy]

I just saw an update and installed if. When trying to refresh PHP I just get "Exited with code 2".

[wpeasy]

Fixed with Claude :)

Item 1 — Bug: "Refresh" PHP image fails with "Exited with code 2" when the primary project has no .env
Summary
On the System info tab, clicking Refresh on a PHP version (e.g. 8.4) fails immediately with "Exited with code 2" and no other output. The cause is an unguarded grep in scripts/refresh-image.sh running under set -euo pipefail: when the primary project (wp-dev) has no .env file, grep returns exit code 2 (file-not-found), which pipefail/set -e treat as fatal — aborting the script before its own intended ${WP_VERSION:-latest} fallback can run.

Regression
Appeared after an auto-update from 0.5.14 → 0.5.19; the regenerated refresh-image.sh carries this behaviour.

Symptom
System → Refresh (PHP 8.4) → the SSE output box shows only Exited with code 2.
The backend runs bash /srv/wp-dev/scripts/refresh-image.sh 8.4 in PRIMARY_PROJECT (app.py: REFRESH_IMAGE_TOOL = PRIMARY_PROJECT / "scripts" / "refresh-image.sh" → sse_response([...], PRIMARY_PROJECT)).
Root cause
scripts/refresh-image.sh (line 21):

set -euo pipefail
...
WP_VERSION=$(grep -E '^WP_VERSION=' .env 2>/dev/null | cut -d= -f2)
export WP_VERSION="${WP_VERSION:-latest}"
The comment above this block states the intent: "read from the primary .env with the compose defaults as fallback."
When .env is absent, grep exits 2 (not 1). Under pipefail the pipeline inherits exit 2, and under set -e the failed command-substitution assignment aborts the script — so ${WP_VERSION:-latest} never runs.
2>/dev/null suppresses grep's error message, not its exit status.
Even an empty-but-present .env wouldn't help: grep would then exit 1 and the script would still abort.
Reproduction / evidence
$ cd /srv/wp-dev && bash -x scripts/refresh-image.sh 8.4

• set -euo pipefail
  ...
• VER=8.4
  ++ grep -E '^WP_VERSION=' .env
  ++ cut -d= -f2
• WP_VERSION=

exits here, code 2 (grep .env → exit 2; .env does not exist)

$ ls -la /srv/wp-dev/.env
ls: cannot access '/srv/wp-dev/.env': No such file or directory
$ grep -E '^WP_VERSION=' /srv/wp-dev/.env; echo $?
2
The script dies before printing its first echo "==> Refreshing …" line — hence the UI shows only the exit code.

Impact / scope
Affects any install where the primary wp-dev project isn't a fully-provisioned site (no .env) — the common case where wp-dev is a scaffold used only for image building. For those installs, Refresh is broken for every PHP version. The refresh always targets PRIMARY_PROJECT (wp-dev), so having other provisioned projects with a valid .env does not help.

Suggested fix (one line)
WP_VERSION=$(grep -E '^WP_VERSION=' .env 2>/dev/null | cut -d= -f2 || true)
export WP_VERSION="${WP_VERSION:-latest}"
|| true makes the pipeline non-fatal; WP_VERSION ends up empty and the existing ${WP_VERSION:-latest} supplies the compose default, exactly as the surrounding comment describes. (Alternatives: gate the read behind [[ -r .env ]].) Fix belongs in the template payload/runtime/scripts/refresh-image.sh, which is copied per-project on regeneration.

Verification
After applying || true, Refresh on PHP 8.4 ran to completion:

==> Refreshing wp-dev-php:8.4: pulling the latest base and rebuilding...
==> Done: wp-dev-php:8.4 refreshed with the latest WordPress.
Resulting image healthy (php --ri ftp → FTP + FTPS enabled).

Item 2 — Enhancement: front-end vhost serves HTTP/1.1 only; enable HTTP/2
Summary
All sites are served over HTTP/1.1, even though the host nginx is built with HTTP/2 support and TLS is configured. The generated reverse-proxy vhost uses listen 443 ssl; without http2, so nginx never advertises h2. Adding http2 to the listen directives in the vhost template enables HTTP/2 for every site with no other changes.

Evidence
$ curl -sI --http2 https:/// -o /dev/null -w '%{http_version}\n'
1.1
$ nginx -V 2>&1 | grep -o with-http_v2_module
--with-http_v2_module # module IS compiled in
$ grep -n 'listen .*443' /etc/nginx/sites-available/spawnwp
listen 443 ssl;
listen [::]:443 ssl;
listen 443 ssl; # (second server block: cockpit)
listen [::]:443 ssl;
Everything needed for h2 is already present — module built in, valid TLS/ALPN — it's simply not switched on.

Source
Template: payload/lib/installer/nginx.conf.tpl — the two TLS server {} blocks (@@Domain@@ and @@COCKPIT_DOMAIN@@) each declare:

listen 443 ssl;
listen [::]:443 ssl;
Suggested change
Add http2 to those listen directives:

listen 443 ssl http2;
listen [::]:443 ssl http2;
Version note: nginx 1.24 (shipped here) uses this on-listen form. On 1.25.1+, the on-listen http2 flag is deprecated in favour of a separate directive — http2 on; inside the server {} block. If you support both, either keep the listen … http2 form (still works on 1.24 and 1.25) or branch on version. The backend proxy hop to the containers can remain HTTP/1.1 — h2 only needs to terminate at the TLS edge.

Verification
After adding http2 to the live vhost and reloading (nginx -t clean, graceful reload):

$ curl -sI --http2 https:/// -o /dev/null -w '%{http_version}\n'
2
$ openssl s_client -connect :443 -alpn h2 </dev/null 2>/dev/null | grep ALPN
ALPN protocol: h2
No downtime; browsers negotiate h2 via ALPN.

Rationale
HTTP/2 (multiplexing, header compression, prioritisation) is a straightforward win for page-load performance and has been stable in nginx for years. For a modern managed WordPress platform it's a reasonable default; there's no downside for HTTP/1.1 clients (they continue to negotiate 1.1 via ALPN).

[wpeasy]

Follow-up report: PHP image cache is rarely reused — pinned-version blueprints and stray files both force needless rebuilds
Follow-up to the earlier report (Refresh "Exited with code 2" + HTTP/2). Same environment: SpawnWP 0.5.19, Ubuntu, Docker Compose build backend.

Context
After fixing the Refresh crash, we observed that deploying a blueprint still triggers a full ~5-minute PHP image rebuild even immediately after a successful Refresh of that PHP version — with the UI message "The PHP image needs a rebuild (SpawnWP update or forced)…". Investigation shows the image-cache gate (in new-project.sh, mirrored in refresh-image.sh) has two independent weaknesses that make the cache miss in normal use.

The gate key (identical in both scripts):

CONTEXT_HASH=$( { cd docker/php && find . -type f ! -name 'zz-site.ini' -print0
| LC_ALL=C sort -z | xargs -0 sha256sum; echo "wp=${WP_VERSION}"; }
| sha256sum | cut -c1-12 )

reuse image only if its org.spawnwp.context-hash label == CONTEXT_HASH

Issue A — "Refresh" cannot pre-warm a pinned-WP-version blueprint
Behaviour: refresh-image.sh derives WP_VERSION from the primary project's .env, falling back to latest. The primary project (wp-dev) commonly has no .env (scaffold only), so Refresh always builds wp=latest. There is no way to tell Refresh to build a specific WP version.

Consequence: any blueprint that pins a WP version (ours captures WP_VERSION=7.0.1) computes a hash with wp=7.0.1, which can never equal the refreshed image's wp=latest hash. So Refresh does nothing useful for pinned-version blueprints — the deploy rebuilds regardless.

Evidence:

Refreshed image label (Refresh PHP 8.4) : ecaddcdcf739 # = hash(wp-dev docker/php + wp=latest)
Blueprint deploy needs : 84a209d0c935 # = hash(clean template docker/php + wp=7.0.1)
→ never matches → full rebuild every first deploy of that blueprint
Suggested fixes (any of):

Let the operator pick the WP version when refreshing (the System tab already knows the installed PHP versions; add a WP-version selector), and/or pre-warm the versions actually referenced by saved blueprints.
When the primary project has no .env, this compounds with the earlier report — Refresh both crashed (now the || true fix) and silently builds the wrong WP version. A primary project used purely for image-building arguably shouldn't drive WP_VERSION at all; the refresh target should be explicit.
Issue B — the context hash includes every file in docker/php, so stray files force rebuilds
Behaviour: find . -type f ! -name 'zz-site.ini' hashes all files in docker/php. Any extra file — an editor backup (Dockerfile.bak, .orig, .swp), .DS_Store, a copied-in artifact — changes the hash and forces a rebuild, and makes that project's image incompatible with every other project's cache.

How we hit it: a single leftover Dockerfile.bak-… in docker/php shifted the hash:

wp-dev docker/php WITH stray .bak + wp=latest : ecaddcdcf739
wp-dev docker/php WITHOUT the .bak + wp=latest : 6982c99a2e25 # == clean template
Worse, because new projects copy the whole docker/php directory from the template, a stray file introduced in the template propagates into every project created afterwards — silently de-syncing all their hashes from each other and from the template. (We had inadvertently created such a file; it had spread into 5 projects. Now cleaned up.)

Suggested fixes (any of):

Hash only a known list of build inputs (e.g. Dockerfile, the .ini files that are actually COPY'd, phpstan-wp.neon) rather than find . -type f.
Or exclude non-build patterns: ! -name '.bak' ! -name '.orig' ! -name '.swp' ! -name '.DS_Store' (and ideally anything not referenced by the Dockerfile).
Or compute the hash from git ls-files/a manifest so untracked junk can't affect it.
When copying docker/php into a new project, copy only the tracked build files, not the whole directory.
Net effect for operators
Between A and B, the "Refresh" feature and the per-deploy cache gate rarely coincide in practice: a pinned-version blueprint never matches a latest refresh, and any stray file in docker/php invalidates the cache and cross-project reuse. The observable symptom is "every first deploy rebuilds for ~5 minutes even though I just refreshed that PHP version." Addressing A (version-aware refresh/pre-warm) and B (hash only real build inputs) would make the cache behave as users expect.

Positive note
The 0.5.19 template already ships the PHP ftp/FTPS build for 8.4 — thanks; that resolves the earlier "ftp and ftps are not available" issue out of the box.

[tts-empire]

All four of these are fixed in 0.5.20, which is out now. Thank you — this was a genuinely good set of reports, and two of them turned out to be symptoms of causes that ran deeper than they looked.

The rebuild loop

Your read was that Refresh couldn't pre-warm a pinned-WP blueprint. That's true, but it's downstream of the real bug: the image tag was keyed on the PHP version alone, while the image contents also depend on the WordPress version (the Dockerfile bakes the core in). So a site on latest and your blueprint pinning 7.0.1 were fighting over one mutable tag — wp-dev-php:8.4. Each deploy re-tagged it, the other's cache key stopped matching, and they rebuilt each other forever. That's your "every deploy rebuilds PHP", and no amount of refreshing could have fixed it.

The tag now carries the WordPress version: wp-dev-php:8.4 for latest, wp-dev-php:8.4-wp7.0.1 when a blueprint pins one. They coexist instead of overwriting each other.

This also closes a hazard nobody had noticed: because both sites shared one tag, a site brought Down and back Up could come back running another site's WordPress core.

There was a third, independent source of the same symptom that no report could have surfaced: switching a site's PHP version built the image without stamping its cache key, so the image got labelled dev and every later deploy on that version saw a mismatch and rebuilt. The key was copy-pasted into two scripts and simply missing from that third one. It now lives in exactly one place, and CI fails if a second copy ever appears.

"This does not seem to be a WordPress installation"

Not flakiness — a race, and a nasty one. bootstrap waited for the database and then ran wp core install, but nothing waited for WordPress itself. On a first start the container spends a while extracting the whole install into an empty volume, and the health check is php-fpm -t — a config syntax test that passes instantly and tells you nothing about the volume. Win the race and the deploy failed outright and rolled the site back. Most likely right after a rebuild, when the cold cache makes the extraction slowest — exactly where you hit it.

Bootstrap now waits for the core files. nginx gets the same 60-second start-up grace as PHP, which is the other half of your "container was not healthy".

Refresh → "Exited with code 2"

Your diagnosis was spot on, down to the || true. grep on a missing .env exits 2, pipefail propagates it, set -e kills the script before its own ${WP_VERSION:-latest} fallback can run. Fixed — and the same trap was lurking in the image garbage collector, which would have died the same way.

Stray files in the build context

Also fixed, and worth underlining for anyone reading later: the cache key was computed over every file in docker/php, so a single .bak or .DS_Store changed it, invalidated that project's cache, and — since new projects copy the directory wholesale — propagated into every site created afterwards. It's now computed over the files the Dockerfile actually uses, and CI fails if a new build input is added without being registered.

HTTP/2

Enabled, for sites and the cockpit. You were right that everything was already in place — module compiled in, TLS with ALPN — it was simply never switched on. Existing installs get it automatically on update; HTTP/1.1 clients are unaffected.

What you need to do

Just update. Your existing sites keep working as they are.

The first deploy on each PHP version after updating pays a one-off rebuild — the cache key changed shape — which also clears out any image left holding the wrong WordPress core. After that, deploys reuse the image the way they were always supposed to.

Full notes: https://spawnwp.com/docs/release-notes/0.5.20/