feat(provision): idempotent setup for local dev and remote server

docs/deployment.md

@@ -19,38 +19,56 @@ Deployment is orchestrated through the `justfile` (`deploy` group).
 
 ## One-time server setup
 
+From a machine with `ssh` access to the `xamxam` host, run the full remote
+provisioning once:
+
 ```bash
-ssh xamxam
-sudo mkdir -p /var/www/xamxam
-sudo chown www-data:xamxam /var/www/xamxam
-sudo chmod 775 /var/www/xamxam
-exit
+just provision-server
 ```
 
-Then from local, deploy once and apply the nginx config + verify permissions:
+This chains (each step is also runnable individually):
+
+1. `scripts/provision-server-env.sh` — ensure the server has an `APP_KEY` in
+   `/var/www/xamxam/.env` (idempotent; see below).
+2. `just deploy` — code + Composer deps + migrations + permissions.
+3. `just deploy-nginx` — install + apply the nginx config and fix permissions.
+4. `just deploy-backup`, `just deploy-cleanup-cron`, `just deploy-logrotate` —
+   install backup + cleanup cron jobs and log rotation.
+
+It finishes by telling you what's left to do in `/admin/account` (set the admin
+password — a fresh DB starts unauthenticated — and configure SMTP/PeerTube
+credentials and Nextcloud sync).
+
+If you'd rather do it step by step (e.g. you already provisioned nginx):
 
 ```bash
 just deploy
 just deploy-nginx
 ```
 
-For a full initial rollout including backup + cleanup cron jobs:
+For a full initial rollout *without* the env/nginx steps (backup + cleanup cron
+only), when those are already handled:
 
 ```bash
-just deploy-all-first        # deploy + deploy-backup + deploy-cleanup-cron
+just deploy-all-first        # deploy + deploy-backup + deploy-cleanup-cron + deploy-logrotate
 ```
 
-### First-time `APP_KEY` on a brand-new server
+### Server `APP_KEY` — idempotent, never overwrites
 
-`deploy-env` uploads the **local** `app/.env` only when the remote has none. Do
-**not** rely on a committed `.env` — generate a fresh key per environment and put
-it on the server before first `deploy`: create `app/.env` locally (see
-[development.md](development.md#appkey-and-the-appenv-file)) so `deploy-env`
-uploads it, or create `/var/www/xamxam/.env` on the server directly:
+`just provision-server` (via `scripts/provision-server-env.sh`) ensures the
+server has an `APP_KEY` in `/var/www/xamxam/.env`. It is **idempotent** and will
+**never overwrite an existing key**:
 
-```bash
-ssh xamxam 'sudo -u www-data bash -c "echo APP_KEY=\$(php -r \"echo base64_encode(random_bytes(32));\") > /var/www/xamxam/.env; chmod 640 /var/www/xamxam/.env; chown www-data:xamxam /var/www/xamxam/.env"'
-```
+- If `/var/www/xamxam/.env` already has an `APP_KEY=…` → it is left untouched
+  and the script prints that the key already exists (so encrypted credentials
+  stay decryptable). It exits `0`.
+- If the file exists but has no `APP_KEY` → a fresh key is appended, existing
+  lines untouched.
+- If the file is absent → it is created with a fresh key.
+
+Ownership (`www-data:xamxam`) and permissions (`640`) are normalised after any
+write. `deploy-env` also refuses to overwrite a remote `.env` that already has
+`APP_KEY`.
 
 If you ever rotate `APP_KEY`, re-encrypt the SMTP password with
 `just reencrypt-password <new_base64_key>` and push the new key via