Deployment updates

docker-compose.prod.yml

@@ -61,6 +61,7 @@ services:
     networks:
       - vigilcare_prod
       - monitoring
+      - shared-service
     logging:
       driver: json-file
       options: { max-size: "50m", max-file: "5" }
@@ -97,6 +98,7 @@ services:
     networks:
       - vigilcare_prod
       - monitoring
+      - shared-service
     logging:
       driver: json-file
       options: { max-size: "50m", max-file: "5" }
@@ -123,4 +125,10 @@ networks:
   vigilcare_prod:
     driver: bridge
   monitoring:
+    external: true
+  # Shared network owned by the Postgres/Redis compose project (it defines and
+  # creates "shared-service" via its own `docker compose up`). This project only
+  # consumes it, so the Postgres/Redis stack must already be running the first
+  # time this stack is deployed, or `docker compose up` here will fail to find it.
+  shared-service:
     external: true

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.

docs/ops/cd-deploy-ssh-setup.md

@@ -23,11 +23,21 @@ The private key does **not** need to live on the VM. The VM only needs the publi
 
 ### 1. On your computer — create the key pair
 
+**Windows (PowerShell):**
+
+```powershell
+ssh-keygen -t ed25519 -f vigilcare-deploy -N '""' -C "gitea-cd"
+```
+
+Windows 10/11 ships the OpenSSH client by default (`Settings → Optional features → OpenSSH Client` if it's missing). PowerShell needs the empty passphrase quoted as `'""'` — a bare `-N ""` sometimes gets swallowed by PowerShell's argument parsing and prompts for a passphrase anyway.
+
+**Linux (Ubuntu):**
+
 ```bash
 ssh-keygen -t ed25519 -f vigilcare-deploy -N "" -C "gitea-cd"
 ```
 
-That creates two files in the current folder:
+Both produce two files in the current folder:
 
 - `vigilcare-deploy` — **private** (secret)
 - `vigilcare-deploy.pub` — **public** (safe to copy)
@@ -49,6 +59,14 @@ chmod 600 ~/.ssh/authorized_keys
 
 Or from your computer (if you already have another way to SSH in):
 
+**Windows (PowerShell):** `ssh-copy-id` doesn't exist on Windows, so pipe the public key into the same `mkdir`/`echo`/`chmod` sequence over SSH instead:
+
+```powershell
+Get-Content vigilcare-deploy.pub | ssh deploy@YOUR_DEPLOY_HOST "mkdir -p ~/.ssh && chmod 700 ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"
+```
+
+**Linux (Ubuntu):**
+
 ```bash
 ssh-copy-id -i vigilcare-deploy.pub deploy@YOUR_DEPLOY_HOST
 ```
@@ -69,15 +87,35 @@ Also set:
 
 ### 4. Sanity check from your computer
 
+**Windows (PowerShell):**
+
+```powershell
+ssh -i vigilcare-deploy deploy@YOUR_DEPLOY_HOST
+```
+
+**Linux (Ubuntu):**
+
 ```bash
 ssh -i vigilcare-deploy deploy@YOUR_DEPLOY_HOST
 ```
 
-If that works without a password, CD’s SSH steps will work the same way (the runner uses the same private key from the secret).
+Same command either way — if that works without a password, CD's SSH steps will work the same way (the runner uses the same private key from the secret).
 
 ### 5. Optional cleanup on your computer
 
-After the private key is in Gitea and you’ve verified SSH, you can delete the local private file if you don’t want another copy. Keep the public key only if you need it again. Prefer regenerating over emailing or sharing the private key.
+After the private key is in Gitea and you've verified SSH, you can delete the local private file if you don't want another copy. Keep the public key only if you need it again. Prefer regenerating over emailing or sharing the private key.
+
+**Windows (PowerShell):**
+
+```powershell
+Remove-Item vigilcare-deploy
+```
+
+**Linux (Ubuntu):**
+
+```bash
+rm vigilcare-deploy
+```
 
 ---