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.

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.