From 5bdf628a2ee84d3e182c0e05b020b65c4cb29499 Mon Sep 17 00:00:00 2001
From: bisco <bisco@younerd.org>
Date: Thu, 25 Jun 2026 12:26:55 +0200
Subject: [PATCH] docs: add first startup procedure

---
 README.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)

diff --git a/README.md b/README.md
index 00b50f3..3fdd71c 100644
--- a/README.md
+++ b/README.md
@@ -45,6 +45,85 @@ Open:
 Use the development credentials copied into `.env` only locally. Change them before
 sharing the environment.
 
+## First startup procedure
+
+Use this checklist for the first run of a new environment.
+
+1. Create the environment file:
+
+   ```bash
+   cp .env.example .env
+   ```
+
+2. Edit `.env` before starting containers:
+
+   - set strong `MARIADB_PASSWORD`, `MARIADB_ROOT_PASSWORD`, and `WP_ADMIN_PASSWORD`;
+   - set `WP_URL` to the public URL, for example `https://lab.younerd.org`;
+   - set `LETSENCRYPT_DOMAIN` to the same hostname when direct Let's Encrypt is used;
+   - keep `LETSENCRYPT_STAGING=1` for the first certificate test;
+   - configure `DB_DATA_PATH`, `WORDPRESS_DATA_PATH`, `LETSENCRYPT_DATA_PATH`, and
+     `CERTBOT_CHALLENGES_PATH` for the host directories that must persist.
+
+3. Prepare host-based volumes and permissions:
+
+   ```bash
+   ./scripts/prepare-host-volumes.sh
+   ```
+
+   On Linux hosts, rerun with `sudo` if the script warns that it cannot change
+   ownership:
+
+   ```bash
+   sudo ./scripts/prepare-host-volumes.sh
+   ```
+
+4. Start the runtime services:
+
+   ```bash
+   docker compose up --build -d
+   docker compose ps
+   ```
+
+   With `LETSENCRYPT_ENABLED=1` and no certificate yet, NGINX intentionally returns
+   `503` for normal application traffic while still serving ACME challenge and health
+   routes. Certbot should start after the proxy becomes healthy.
+
+5. Install/configure WordPress on the real persistent volume:
+
+   ```bash
+   docker compose --profile tools run --rm wp-cli /scripts/bootstrap.sh
+   ```
+
+   Do not add `-f docker-compose.test.yml` here. The test override uses disposable test
+   volumes and is only for automated checks.
+
+6. Follow certificate issuance:
+
+   ```bash
+   docker compose logs -f proxy certbot
+   ```
+
+   After the staging certificate flow is working, switch to the production CA:
+
+   ```dotenv
+   LETSENCRYPT_STAGING=0
+   ```
+
+   Then restart the affected services:
+
+   ```bash
+   docker compose up -d proxy certbot
+   ```
+
+7. Final sanity checks:
+
+   ```bash
+   docker compose ps
+   docker compose logs --tail=100 proxy wordpress db certbot
+   ```
+
+   Open the configured `WP_URL` and `/wp-admin/`.
+
 Persistent data uses host-based bind mounts by default:
 
 - `./runtime/db` for MariaDB;