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, removing only the staging certificate directory when necessary.

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.