diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3952840..727b9ce 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -109,7 +109,7 @@ SLMM feed; every route resolves the client through one swappable
 - Each project's client portal is now gated by a **secure per-project link + shared password** (argon2-hashed). Operators manage it from the project page's **Portal access** panel (enable, generate password, copy link).
 - Per-project session isolation (a session for one project can't read another's data); brute-force lockout (5 tries / 15 min) on the password gate.
 - Retired the interim magic-link / `PORTAL_OPEN_LINKS` open links and the `portal_admin.py mint-link` command.
-- **Upgrade:** run `python3 backend/migrate_add_project_portal_auth.py` per DB. Set `COOKIE_SECURE=true` once served over HTTPS.
+- **Upgrade:** new `argon2-cffi` dependency → **rebuild the image**, then run `python3 backend/migrate_add_project_portal_auth.py` per DB (adds the `projects.portal_*` columns). `SECRET_KEY` and `COOKIE_SECURE` are now passed through in `docker-compose.yml` (settable via a `.env` file) — set a real `SECRET_KEY` (and `COOKIE_SECURE=true` once on HTTPS) before the portal faces the internet.
 
 ---
 
diff --git a/docker-compose.yml b/docker-compose.yml
index 74c045c..93ef140 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -11,6 +11,13 @@ services:
       - ENVIRONMENT=production
       - SLMM_BASE_URL=http://host.docker.internal:8100
       - SFM_BASE_URL=http://sfm:8200
+      # Client-portal session-cookie signing. Set SECRET_KEY to a real secret (e.g.
+      # in a .env file beside this compose) BEFORE the portal faces the internet —
+      # the dev default is public/forgeable and logs a warning at boot. Set
+      # COOKIE_SECURE=true once served over HTTPS (leave false on plain HTTP, or the
+      # browser won't send the cookie and the portal breaks).
+      - SECRET_KEY=${SECRET_KEY:-dev-insecure-change-me}
+      - COOKIE_SECURE=${COOKIE_SECURE:-false}
       # Display timezone for server logs + any text-rendered timestamps.
       # DB columns are stored UTC regardless; this only affects what
       # operators see.  Override here for non-US-East deployments.