Build/Test Tools: Enable text compression in the local Docker environment

[westonruter]

Enables gzip compression in the nginx config template used by the local Docker environment, so that HTML, JavaScript, CSS, JSON, XML, and SVG responses are served compressed.

Without this, front-end performance analysis against the local environment is not representative of a real user's experience: on JavaScript-heavy screens like the Site Editor, several megabytes of uncompressed editor JavaScript are transferred on every load, and any performance improvement under test is drowned out by that transfer. Serving compressed responses matches the behavior of virtually all production WordPress hosts.

Compression is Accept-Encoding-gated, so any request that does not advertise gzip support (e.g. curl without --compressed) continues to receive uncompressed responses as before. gzip_vary on ensures caches key on the encoding, and the gzip_types list deliberately omits already-compressed assets (images, woff2 fonts) so nothing is wastefully re-compressed.

Configuration

Compression is enabled by default and controlled by a new LOCAL_NGINX_COMPRESSION option in .env (valid values on/off, defaulting to on). The value is substituted into the nginx template the same way as LOCAL_DIR. Setting it to off reproduces the previous uncompressed behavior, which is useful for measuring the uncompressed baseline when comparing performance:

LOCAL_NGINX_COMPRESSION=off

Notes

• nginx:alpine (the image used by the local environment) ships the gzip module but not brotli, so this uses gzip.
• Because this changes docker-compose.yml (the web server's environment and command) in addition to the nginx template, existing checkouts need to recreate the web server container to pick up the change, e.g. docker compose up -d wordpress-develop or npm run env:start.

Verification

Verified locally under Fast 4G throttling: the Site Editor's major bundles compress to roughly 30% of their transfer size (e.g. editor.min.js 1.55 MB → 498 KB), which brought this screen's LCP down from ~25.4 s to ~15.4 s and made data-loading differences measurable rather than being swamped by asset transfer. Toggling LOCAL_NGINX_COMPRESSION between on and off was confirmed to add/remove the Content-Encoding: gzip response header as expected.

Trac ticket: https://core.trac.wordpress.org/ticket/65634

Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Opus 4.8
Used for: Authoring the nginx gzip configuration and the LOCAL_NGINX_COMPRESSION toggle, drafting this PR description, and running the performance measurements that motivated the change. All changes were directed, reviewed, and verified by me.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props westonruter, jblz.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[Copilot]

Pull request overview

This PR enables gzip text compression in the local Docker nginx configuration so the local environment better reflects typical production hosting behavior and yields more representative front-end performance measurements.

Changes:

• Adds gzip configuration (vary/proxied/level/min length + content types) to the nginx config template used by the local environment.
• Introduces LOCAL_NGINX_COMPRESSION (default on) as a .env/Compose-controlled toggle for enabling/disabling compression.
• Updates the container startup command to substitute the new variable into the nginx config via envsubst.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
tools/local-env/default.template	Enables gzip compression in the nginx server config template with a variable-driven on/off toggle.
docker-compose.yml	Adds LOCAL_NGINX_COMPRESSION to the web container environment and includes it in envsubst substitution.
.env.example	Documents the new LOCAL_NGINX_COMPRESSION option and its valid values.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[jblz]

I think we should consider having LOCAL_NGINX_COMPRESSION default to off.

While negligible, compression and decompression in a local env will add overhead that is likely only useful when developing features that depend on that behavior.

[github-actions]

A commit was made that fixes the Trac ticket referenced in the description of this pull request.

SVN changeset: 63308
GitHub commit: 1fcc5c0

This PR will be closed, but please confirm the accuracy of this and reopen if there is more work to be done.

[jblz]

This is testing well :)

$ curl -sI -H 'Accept-Encoding: gzip' http://localhost:8889/wp-includes/css/dashicons.css | grep -iE 'content-type|content-encoding|vary'
  Content-Type: text/css
  Vary: Accept-Encoding
  Content-Encoding: gzip


$ curl -sI -H 'Accept-Encoding: gzip' http://localhost:8889/wp-includes/images/w-logo-blue.png | grep -iE 'content-type|content-encoding'
  Content-Type: image/png

$ curl -sI -H 'Accept-Encoding: gzip' 'http://localhost:8889/?feed=rss2'
  | grep -iE 'content-type|content-encoding'
  Content-Type: application/rss+xml; charset=UTF-8
  Content-Encoding: gzip

Not a blocker, but noting that specifying a value other than on or off for LOCAL_NGINX_COMPRESSION "silently" breaks nginx in the container. Logs say something like:

wordpress-develop-1 | nginx: [emerg] invalid value "o" in "gzip" directive, it must be "on" or "off" in /etc/nginx/conf.d/default.conf:18