Update deployment documentation and validate environment variables in CI/CD workflow

Author: wpak-ai

.github/workflows/cd.yml

@@ -41,6 +41,14 @@ jobs:
        || github.ref == 'refs/heads/develop' && 'staging'
        || '' }}
     steps:
+      - name: Validate GitHub Environment variables
+        run: |
+          set -euo pipefail
+          err() { echo "::error title=Missing environment variable::$1" >&2; exit 1; }
+          [ -n "${{ vars.DEPLOY_PATH }}" ] || err "Set Variable DEPLOY_PATH on this job's GitHub Environment (e.g. /opt/paperscout). Settings → Environments → ${{ github.environment }} → Environment variables."
+          [ -n "${{ vars.DEPLOY_BRANCH }}" ] || err "Set Variable DEPLOY_BRANCH (e.g. main or develop)."
+          [ -n "${{ vars.HEALTH_PORT }}" ] || err "Set Variable HEALTH_PORT to the host port published for GET /health (see docker-compose / README; e.g. 9101). Without it the workflow builds http://localhost:/health and curl fails."
+
       - name: Deploy via SSH
         uses: appleboy/ssh-action@v1
         with:

CHANGELOG.md

@@ -16,6 +16,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Documentation: deployment URLs (Slack Request URL behind nginx `/paperscout/`), clone URL in server setup, staging-style placeholders.
 - `db-backup.yml`: matrix parallel backups for `staging` / `production` using environment-level SSH secrets; uploads under `gs://insights-db-backups/paperscout/<environment>/` with unique temp files and object keys (UTC timestamp + `run_id` + `run_attempt` + environment); `EXIT` trap removes temp dump on failure. `SERVER_SETUP` restore examples updated (`--no-owner`, listing/copy by object name).
+- `cd.yml`: validate `DEPLOY_PATH`, `DEPLOY_BRANCH`, and `HEALTH_PORT` GitHub Environment variables before SSH so missing `HEALTH_PORT` fails with a clear error instead of curling `http://localhost:/health`.
 
 ## [0.1.0] - 2026-05-05
 

README.md

@@ -154,17 +154,17 @@ Push to develop → CI tests → SSH into staging → git pull --ff-only → doc
 
 #### Configure GitHub Environments
 
-Create two environments under **Settings → Environments**: `production` and `staging`. Both use the **same secret names** (different values per environment) and a small set of per-environment **Variables**:
+Create two environments under **Settings → Environments**: `production` and `staging`. Both use the **same secret names** (different values per environment) and **these Environment variables are required for CD** — if `HEALTH_PORT` is omitted, the workflow builds `http://localhost:/health` and the deploy fails at the health check:
 
 | Type     | Name             | Production              | Staging                           |
 | -------- | ---------------- | ----------------------- | --------------------------------- |
 | Secret   | `SERVER_HOST`    | prod host / IP          | staging host / IP                 |
 | Secret   | `SERVER_USER`    | deploy user             | deploy user                       |
 | Secret   | `SERVER_SSH_KEY` | private key             | private key                       |
 | Secret   | `SERVER_PORT`    | optional (default `22`) | optional (default `22`)           |
-| Variable | `DEPLOY_PATH`    | `/opt/paperscout`       | `/opt/paperscout-staging`         |
+| Variable | `DEPLOY_PATH`    | `/opt/paperscout`       | `/opt/paperscout`                 |
 | Variable | `DEPLOY_BRANCH`  | `main`                  | `develop`                         |
-| Variable | `HEALTH_PORT`    | `9101`                  | `9102` (or whatever staging maps) |
+| Variable | `HEALTH_PORT`    | `9101`                  | `9101` (or whatever staging maps) |
 
 The workflow picks the environment from the branch (`refs/heads/main` → `production`, `refs/heads/develop` → `staging`), so values like `DEPLOY_PATH` and `HEALTH_PORT` are not hard-coded in the YAML.
 
@@ -184,11 +184,11 @@ curl -sf http://localhost:9101/health
 On the **staging** server (separate host or separate path on the same host; must match the `staging` environment's `DEPLOY_PATH` and expose `/health` on `HEALTH_PORT`):
 
 ```bash
-git clone -b develop https://github.com/cppalliance/paperscout.git /opt/paperscout-staging
-cd /opt/paperscout-staging
+git clone -b develop https://github.com/cppalliance/paperscout.git /opt/paperscout
+cd /opt/paperscout
 cp .env.example .env   # use staging credentials / DB / Slack app as appropriate
 docker compose up -d --build
-curl -sf http://localhost:9102/health
+curl -sf http://localhost:9101/health
 ```
 
 See [`deploy/SERVER_SETUP.md`](deploy/SERVER_SETUP.md) for the full Ubuntu 22.04 provisioning guide, and [`.github/workflows/cd.yml`](.github/workflows/cd.yml) for the CD pipeline.
@@ -444,6 +444,7 @@ The `.github/workflows/cd.yml` workflow runs on push to `main` or `develop` (and
 1. **Test** — single Python 3.12 pytest run as a gate (re-uses the same coverage threshold as CI).
 2. **Deploy** — single environment-driven job:
    - Selects the **GitHub Environment** from the branch (`main` → `production`, `develop` → `staging`).
+   - **Validates** Environment variables `DEPLOY_PATH`, `DEPLOY_BRANCH`, and **`HEALTH_PORT`** are non-empty (missing `HEALTH_PORT` produces an invalid health URL and fails the job immediately with an actionable error).
    - SSHes using the environment-scoped secrets (`SERVER_HOST`, `SERVER_USER`, `SERVER_SSH_KEY`, optional `SERVER_PORT`).
    - Reads per-environment **variables** (`DEPLOY_PATH`, `DEPLOY_BRANCH`, `HEALTH_PORT`) so the same workflow targets prod or staging without code changes.
    - Runs `git fetch` + `git checkout` + `git pull --ff-only` against `DEPLOY_BRANCH` to keep deploys deterministic, then `docker compose up -d --build paperscout`.

deploy/SERVER_SETUP.md

@@ -231,7 +231,7 @@ docker compose logs -f paperscout
 If you use a **separate** staging deployment (second clone path and GitHub Environment `staging`), typical placeholders are:
 
 - TLS / DNS: `sudo certbot --nginx -d staging.example.org` (replace with your real staging hostname when provisioning).
-- Health check on the staging machine after mapping ports (see README CD table): `curl -sf http://localhost:9102/health` — use whatever port your staging compose publishes for health instead of `9102` if different.
+- Health check on the staging machine after mapping ports (see README CD table): `curl -sf http://localhost:9101/health`.
 - Slack **Request URL** when nginx proxies under `/paperscout/`: `https://staging.example.org/paperscout/slack/events`.
 
 ---