azionelab-v2/docs/deployment.md

Deployment

Local

Copy .env.example to .env, add 127.0.0.1 azionelab.org to the hosts file, then:

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

NGINX binds to loopback ports 8080/8443. WordPress and MariaDB remain private. The bootstrap is safe to rerun and does not duplicate demo records.

The default persistent paths are host-based bind mounts under ./runtime. Before the first start, run:

./scripts/prepare-host-volumes.sh

The script reads .env, creates the configured paths, and applies the expected container ownership. For Linux hosts this avoids the common problem where Docker creates missing bind-mount directories as root:root and WordPress or MariaDB later cannot write to them. If a platform uses different image UIDs/GIDs, override MARIADB_VOLUME_UID/GID, WORDPRESS_VOLUME_UID/GID, or CERTBOT_VOLUME_UID/GID.

Production

Required controls:

• WP_ENVIRONMENT_TYPE=production;
• unique non-placeholder MariaDB passwords of at least 16 characters;
• WORDPRESS_DEBUG=0 and a strong administrator password;
• an HTTPS WP_URL;
• managed secrets outside the Compose file;
• either direct Let's Encrypt termination or a trusted external load balancer;
• off-host database/file backups and monitoring.

When a load balancer terminates TLS, Certbot stays disabled. TRUST_PROXY_HEADERS=1 is safe only when firewall/network policy makes the load balancer the sole NGINX caller and it overwrites X-Forwarded-* headers.

For direct TLS, public DNS and inbound ports 80/443 must reach NGINX. Start with LETSENCRYPT_STAGING=1 and set WP_URL to the final HTTPS URL. Application HTTP returns 503 until a certificate exists, then redirects to HTTPS. Switch to the production CA only after validating DNS and firewall behavior. When LETSENCRYPT_STAGING changes from 1 to 0, recreate the Certbot container; it removes an existing staging certificate for the configured domain before requesting the production certificate.

State and rollback

Database and WordPress file directories must be backed up together. Code rollback is a container rebuild from a prior commit and does not require deleting host data directories. Never delete the paths configured by DB_DATA_PATH, WORDPRESS_DATA_PATH, or LETSENCRYPT_DATA_PATH where content/certificates must survive. Test database restoration in a disposable environment before any production restore.