azionelab-v2/docs/runbook.md

Runbook

Installation screen remains visible

1. Check docker compose ps for healthy database and WordPress services.
2. Run docker compose --profile tools run --rm wp-cli /scripts/bootstrap.sh.
3. Inspect docker compose logs wordpress db without printing secret values.

NGINX returns 502

1. Run docker compose ps and docker compose exec proxy nginx -t.
2. Check the WordPress health status and docker compose logs proxy wordpress.
3. Confirm the request host is exactly azionelab.org; unknown hosts return 404.

Images or theme are missing

1. Confirm WORDPRESS_DATA_PATH is mounted in both WordPress and WP-CLI.
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.

A service cannot write to its volume

1. Stop the affected service.
2. Confirm the relevant .env path points to the intended host directory.
3. Run ./scripts/prepare-host-volumes.sh.
4. Start the service and inspect logs without printing secret values.

Certificate issuance fails

Verify public DNS, inbound port 80, the operator email, and staging mode. Request a missing /.well-known/acme-challenge/ path: an NGINX 404 confirms the route is yours. Avoid repeated production-CA retries while debugging.

When Let's Encrypt is enabled, the proxy intentionally returns 503 for normal application paths until a certificate exists. ACME challenge paths and proxy health paths must still work in that pending state, otherwise Certbot will never start.

Staging certificate remains after switching to production

Certbot does not replace a still-valid staging certificate just because LETSENCRYPT_STAGING changed. Recreate the Certbot container so it reads the updated environment:

docker compose up -d --force-recreate certbot
docker compose up -d proxy

The entrypoint removes an existing staging certificate for LETSENCRYPT_DOMAIN before requesting the production certificate. If issuance fails, inspect docker compose logs certbot proxy, verify DNS and port 80, and avoid repeated production-CA retries.

Bootstrap writes to the wrong data volume

Do not combine the test override with production bootstrap commands. This command writes to isolated test volumes only:

docker compose -f docker-compose.yml -f docker-compose.test.yml --profile tools run --rm wp-cli /scripts/bootstrap.sh

Use this command for the real host-based WordPress data directory:

docker compose --profile tools run --rm wp-cli /scripts/bootstrap.sh

Rollback

Revert the deployment commit and rebuild while preserving all host data directories. Restore database/files only for a data rollback and only from a verified coordinated backup.