vigilcare-clinical/docs/instructions-for-env.md

Notice what CD actually does: it scps 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, cds 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:

.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:

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:

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.