chore: add wp-cli maintenance override

docs/operations.md

@@ -23,6 +23,20 @@ Review security releases routinely, update pins in a task branch, rebuild, run t
 test suite, and deploy. Production disables WordPress web-based file modifications, so
 image rebuilds are the update path.
 
+The default `wp-cli` service is attached only to the internal data network. When a
+maintenance command must download from the internet, use
+`docker-compose.maintenance.yml` explicitly:
+
+```bash
+docker compose -f docker-compose.yml -f docker-compose.maintenance.yml --profile tools run --rm wp-cli -c 'wp core update --version=7.0.2 --force'
+docker compose -f docker-compose.yml -f docker-compose.maintenance.yml --profile tools run --rm wp-cli -c 'wp core update-db'
+docker compose --profile tools run --rm wp-cli -c 'wp core version'
+docker compose restart wordpress proxy
+```
+
+Do not use the maintenance override for routine bootstrap or inspection commands that
+do not need outbound network access.
+
 External `wp-cron.php` requests are blocked to reduce public attack surface. If future
 content scheduling, maintenance jobs, or plugin features require WordPress cron, run it
 from a controlled host/container cron against the private WordPress service instead of

docs/runbook.md

@@ -35,6 +35,21 @@ HTTPS redirects during production startup.
 2. Run `docker compose --profile tools run --rm wp-cli -c 'wp theme status azionelab'`.
 3. Verify file ownership before changing permissions; never make the tree world-writable.
 
+## WP-CLI cannot resolve wordpress.org
+
+The default WP-CLI container intentionally runs only on the internal data network. Use
+the maintenance override for commands that must download WordPress core files:
+
+```bash
+docker compose -f docker-compose.yml -f docker-compose.maintenance.yml --profile tools run --rm wp-cli -c 'wp core update --version=7.0.2 --force'
+docker compose -f docker-compose.yml -f docker-compose.maintenance.yml --profile tools run --rm wp-cli -c 'wp core update-db'
+docker compose --profile tools run --rm wp-cli -c 'wp core version'
+docker compose restart wordpress proxy
+```
+
+If DNS still fails with the maintenance override, inspect the host/container DNS
+configuration and firewall rules before retrying the update.
+
 ## Uploaded image does not appear on the public page
 
 1. Confirm the image was selected in **Appearance > Customize**, not only uploaded in

docs/security.md

@@ -28,6 +28,10 @@
   WordPress/Apache retains the capabilities needed by the official image internally,
   but no WordPress port is published. A containerized security test fails if the
   WordPress service is configured with host-published ports.
+- WP-CLI normally joins only the internal data network. The maintenance override
+  attaches WP-CLI to the web network for operator-triggered commands that require
+  outbound internet access, such as WordPress core downloads; do not use it for routine
+  bootstrap or inspection commands.
 - Persistent state uses host-based bind mounts. Keep those paths outside the public web
   root, restrict host access, never make them world-writable, and run
   `./scripts/prepare-host-volumes.sh` when paths or image user IDs change.

docs/testing.md

@@ -12,6 +12,7 @@ docker compose -f docker-compose.yml -f docker-compose.test.yml --profile tools
 docker compose -f docker-compose.yml -f docker-compose.test.yml --profile test run --build --rm functional-tests
 docker compose -f docker-compose.yml -f docker-compose.test.yml --profile test run --rm security-tests
 docker compose config --quiet
+docker compose -f docker-compose.yml -f docker-compose.maintenance.yml config --quiet
 LETSENCRYPT_ENABLED=1 docker compose config --quiet
 ```