Deployment updates

docs/instructions-for-env.md

@@ -0,0 +1,34 @@
+Notice what CD actually does: it `scp`s only `docker-compose.prod.yml` to `/opt/vigilcare/` on the VM every deploy — **`.env` is never copied by CD at all.** The `Deploy` step just assumes `/opt/vigilcare/.env` already exists there, `cd`s into that directory, patches only the `IMAGE_TAG=` line in place with `sed`, then runs `docker compose --env-file .env pull/up`. Every other value in `.env` (`PG_CONNECTION`, secrets, hosts, etc.) is expected to already be sitting on the VM, untouched, across every deploy.
+
+That means the `.env` file has a one-time, manual, out-of-band setup step, separate from the automated CD pipeline:
+
+**One-time setup (before your first CD-driven deploy):**
+
+1. Confirm `.gitignore` already excludes it — it does:
+
+```58:60:.gitignore
+.env
+.env.*
+!.env.example
+```
+
+So `.env` will never be committed or touched by `git`/CD checkout — good, since it holds real secrets (DB passwords, JWT signing keys, RabbitMQ creds, etc.).
+
+2. Create the target directory on the VM and copy your real, filled-in `.env` there directly — once, by hand, outside of CD:
+
+```bash
+ssh deploy@YOUR_DEPLOY_HOST "mkdir -p /opt/vigilcare"
+scp .env deploy@YOUR_DEPLOY_HOST:/opt/vigilcare/.env
+```
+
+(Use whatever `DEPLOY_USER`/`DEPLOY_HOST` you set up per `docs/ops/cd-deploy-ssh-setup.md`.)
+
+3. Lock down permissions since it contains secrets:
+
+```bash
+ssh deploy@YOUR_DEPLOY_HOST "chmod 600 /opt/vigilcare/.env"
+```
+
+**From then on, every CD run just works** — it never re-copies `.env`, so any values you change later (rotating a password, updating `KAFKA_BOOTSTRAP`, etc.) require editing `/opt/vigilcare/.env` directly on the VM, not editing the repo's local copy and expecting CD to push it. If you ever *want* CD to manage the full `.env` (e.g. sourced from Gitea secrets/variables rather than a static file sitting on the VM), that would be a bigger change to `cd.yml` — happy to build that out if you'd rather not hand-maintain it on the server, but as-is, your repo's `.env` is really just a local reference/template for what needs to exist on the VM, not something CD pushes.
+
+One gotcha to watch for on that very first deploy: since the `Deploy` step does `grep '^IMAGE_TAG=' .env`, if `/opt/vigilcare/.env` doesn't exist yet when CD first runs, `cd /opt/vigilcare` under `set -euo pipefail` will hard-fail immediately (no directory) — so steps 2–3 above need to happen before you push your first version tag, not after.