From 3c907d17e996d91899cdb1a1773dd59efc6f9a78 Mon Sep 17 00:00:00 2001
From: Nora <nora_rocks@agentmail.to>
Date: Wed, 24 Jun 2026 16:08:12 -0600
Subject: [PATCH] =?UTF-8?q?docs(sp26):=20RUNBOOK=20=E2=80=94=20CYCLONE=5FS?=
 =?UTF-8?q?FTP=5FPASSWORD=5FFILE=20row=20+=20Docker=20variant?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/RUNBOOK.md | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/docs/RUNBOOK.md b/docs/RUNBOOK.md
index 9c9b28f..c549ae8 100644
--- a/docs/RUNBOOK.md
+++ b/docs/RUNBOOK.md
@@ -22,6 +22,7 @@ paramiko SFTP in SP13. To turn it on for `mft.gainwelltechnologies.com`:
 | Variable | Required | Default | Purpose |
 |---|---|---|---|
 | `CYCLONE_SFTP_PASSWORD` | Yes (real MFT only) | unset | The MFT password. Stripped of whitespace; empty values are treated as unset. |
+| `CYCLONE_SFTP_PASSWORD_FILE` | No | unset | Path to a file containing the MFT password. Highest-priority lookup in `secrets.get_secret()`. Standard Docker-secrets pattern. See "Docker secrets variant" below. |
 | `CYCLONE_SCHEDULER_AUTOSTART` | No | unset (falsy) | When `1`/`true`/`yes`, the scheduler starts polling on API launch. |
 | `CYCLONE_SCHEDULER_POLL_SECONDS` | No | `60` | Seconds between poll cycles. The Gainwell MFT server doesn't push — we pull. |
 
@@ -111,3 +112,29 @@ security find-generic-password -s cyclone -a sftp.gainwell.password -w   # verif
 The env var is the highest-priority lookup; the Keychain is the
 fallback. Setting both means the env var wins. To force the Keychain,
 unset the env var for that shell.
+
+### Docker secrets variant (SP26)
+
+For the SP23 Docker stack, mount the MFT password as a file rather
+than embedding it in `docker-compose.yml`. The compose file already
+declares the `cyclone_sftp_password` secret and wires
+`CYCLONE_SFTP_PASSWORD_FILE: "/run/secrets/cyclone_sftp_password"`
+on the backend service. Create the file once on the host:
+
+```bash
+sudo install -m 0600 -o root -g root /dev/null /etc/cyclone/secrets/sftp_password
+echo -n 'the-actual-password' | sudo tee /etc/cyclone/secrets/sftp_password > /dev/null
+sudo chmod 0600 /etc/cyclone/secrets/sftp_password
+```
+
+Then `docker compose up -d`. The backend's `secrets.get_secret()` will
+read the file on the next scheduler tick — no env-var export, no
+`docker-compose.yml` edit with the password in it. The file takes
+precedence over the plain `CYCLONE_SFTP_PASSWORD` env var; setting
+both means the file wins.
+
+If the mounted file is missing or unreadable (typo in path, container
+started without the secret mount), the scheduler surfaces a
+`RuntimeError` at the next tick that names the env var and the
+missing path — this is intentional, so a silent fall-through doesn't
+mask a real misconfiguration.