# 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:

```bash
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:

```bash
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:

```bash
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.