docs(ops): stop the compose header contradicting itself, and name the four variables step 2 dropped (#204) #210

2026-08-28T14:01:08-05:00

bermudalamb commented

2026-08-28 14:01:08 -05:00

Three corrections a review of #196 found, all in text #196 itself rewrote.

The compose header asserted something it falsified three lines later. "All must be set in Portainer for this stack. All are secrets except DEMO_MODE" — but three PayPal entries are unused while DEMO_MODE is true, three more are marked Optional, and SMTP_FROM is not a secret. The runbook sends the operator to that exact block as authoritative, so an operator cutting over during the demo interim reads "all must be set", has no live PayPal credentials — which is the whole reason the interim exists — and either stops or invents a BACKUP_PASSPHRASE, which is how you get archives nobody can decrypt. The blanket claim is gone; each entry already says whether it is required and when.

Step 2 enumerated nine of the thirteen interpolated names. USPS_CLIENT_ID, USPS_CLIENT_SECRET, UPLOADS_BASE_URL and BACKUP_PASSPHRASE were missing. The USPS pair is the one that matters, and it now gets a sentence of its own: losing it is the only silent failure in this step. Address validation is skipped when those are empty rather than failing, so checkout keeps working and quietly stops validating addresses, with no crash loop and nothing in step 7 that would notice. The list also now says to take everything the stack holds rather than working from the list, because an enumeration reads as a checklist however it is introduced.

The DB_PASSWORD failure was described wrongly, and its error names a variable the operator never typed. It does not fail to authenticate against its data directory — the app never reaches a connection attempt, checkAlwaysRequired refuses at boot, and the message says PGPASSWORD because the compose file injects it as PGPASSWORD=${DB_PASSWORD}. An operator grepping for DB_PASSWORD finds nothing. That is now stated.

The crash-loop examples were reordered to match the case the section claims to be about. It headlines "the likeliest outcome of a missed step 2", but the only block shown was the PayPal triple, which cannot occur during the demo interim, and #196 replaced it with a DEMO_MODE-only block that is not what a missed step 2 produces either. A wholesale miss is two problems led by PGPASSWORD; that is now first, with the DEMO_MODE-only and mistyped-value forms after it.

Every quoted line was verified by running the real validator against production's entry set rather than by reading the source — 2 problem(s) and 1 problem(s) counts included — and all four now match character for character. The mistyped-value message is quoted in full rather than truncated, which was the point of the complaint that produced it.

DEMO_MODE is no longer called "the only one that is not a secret", which was false of SMTP_FROM and UPLOADS_BASE_URL. It is the only one that is a setting rather than a credential, which is true and a better hook.

Verified: 278 backend unit tests pass, including the compose guard that parses this file.

Closes #204
Refs #196

Co-Authored-By: Claude Opus 5 (1M context) noreply@anthropic.com

Three corrections a review of #196 found, all in text #196 itself rewrote. **The compose header asserted something it falsified three lines later.** "All must be set in Portainer for this stack. All are secrets except DEMO_MODE" — but three PayPal entries are unused while `DEMO_MODE` is `true`, three more are marked Optional, and `SMTP_FROM` is not a secret. The runbook sends the operator to that exact block as authoritative, so an operator cutting over during the demo interim reads "all must be set", has no live PayPal credentials — which is the whole reason the interim exists — and either stops or invents a `BACKUP_PASSPHRASE`, which is how you get archives nobody can decrypt. The blanket claim is gone; each entry already says whether it is required and when. **Step 2 enumerated nine of the thirteen interpolated names.** `USPS_CLIENT_ID`, `USPS_CLIENT_SECRET`, `UPLOADS_BASE_URL` and `BACKUP_PASSPHRASE` were missing. The USPS pair is the one that matters, and it now gets a sentence of its own: losing it is the only silent failure in this step. Address validation is skipped when those are empty rather than failing, so checkout keeps working and quietly stops validating addresses, with no crash loop and nothing in step 7 that would notice. The list also now says to take everything the stack holds rather than working from the list, because an enumeration reads as a checklist however it is introduced. **The `DB_PASSWORD` failure was described wrongly, and its error names a variable the operator never typed.** It does not fail to authenticate against its data directory — the app never reaches a connection attempt, `checkAlwaysRequired` refuses at boot, and the message says `PGPASSWORD` because the compose file injects it as `PGPASSWORD=${DB_PASSWORD}`. An operator grepping for `DB_PASSWORD` finds nothing. That is now stated. The crash-loop examples were reordered to match the case the section claims to be about. It headlines "the likeliest outcome of a missed step 2", but the only block shown was the PayPal triple, which cannot occur during the demo interim, and #196 replaced it with a `DEMO_MODE`-only block that is not what a missed step 2 produces either. A wholesale miss is two problems led by `PGPASSWORD`; that is now first, with the `DEMO_MODE`-only and mistyped-value forms after it. Every quoted line was verified by running the real validator against production's entry set rather than by reading the source — `2 problem(s)` and `1 problem(s)` counts included — and all four now match character for character. The mistyped-value message is quoted in full rather than truncated, which was the point of the complaint that produced it. `DEMO_MODE` is no longer called "the only one that is not a secret", which was false of `SMTP_FROM` and `UPLOADS_BASE_URL`. It is the only one that is a setting rather than a credential, which is true and a better hook. Verified: 278 backend unit tests pass, including the compose guard that parses this file. Closes #204 Refs #196 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

bermudalamb added 1 commit 2026-08-28 14:01:08 -05:00

docs(ops): stop the compose header contradicting itself, and name the four variables step 2 dropped (#204 )

SonarQube Analysis / sonarqube (pull_request) Failing after 17m33s

Details

Linting / lint (pull_request) Successful in 1m57s

Details

e72c41d4c9

Three corrections a review of #196 found, all in text #196 itself rewrote.

**The compose header asserted something it falsified three lines later.** "All must be set in Portainer for this stack. All are secrets except DEMO_MODE" — but three PayPal entries are unused while `DEMO_MODE` is `true`, three more are marked Optional, and `SMTP_FROM` is not a secret. The runbook sends the operator to that exact block as authoritative, so an operator cutting over during the demo interim reads "all must be set", has no live PayPal credentials — which is the whole reason the interim exists — and either stops or invents a `BACKUP_PASSPHRASE`, which is how you get archives nobody can decrypt. The blanket claim is gone; each entry already says whether it is required and when.

**Step 2 enumerated nine of the thirteen interpolated names.** `USPS_CLIENT_ID`, `USPS_CLIENT_SECRET`, `UPLOADS_BASE_URL` and `BACKUP_PASSPHRASE` were missing. The USPS pair is the one that matters, and it now gets a sentence of its own: losing it is the only silent failure in this step. Address validation is skipped when those are empty rather than failing, so checkout keeps working and quietly stops validating addresses, with no crash loop and nothing in step 7 that would notice. The list also now says to take everything the stack holds rather than working from the list, because an enumeration reads as a checklist however it is introduced.

**The `DB_PASSWORD` failure was described wrongly, and its error names a variable the operator never typed.** It does not fail to authenticate against its data directory — the app never reaches a connection attempt, `checkAlwaysRequired` refuses at boot, and the message says `PGPASSWORD` because the compose file injects it as `PGPASSWORD=${DB_PASSWORD}`. An operator grepping for `DB_PASSWORD` finds nothing. That is now stated.

The crash-loop examples were reordered to match the case the section claims to be about. It headlines "the likeliest outcome of a missed step 2", but the only block shown was the PayPal triple, which cannot occur during the demo interim, and #196 replaced it with a `DEMO_MODE`-only block that is not what a missed step 2 produces either. A wholesale miss is two problems led by `PGPASSWORD`; that is now first, with the `DEMO_MODE`-only and mistyped-value forms after it.

Every quoted line was verified by running the real validator against production's entry set rather than by reading the source — `2 problem(s)` and `1 problem(s)` counts included — and all four now match character for character. The mistyped-value message is quoted in full rather than truncated, which was the point of the complaint that produced it.

`DEMO_MODE` is no longer called "the only one that is not a secret", which was false of `SMTP_FROM` and `UPLOADS_BASE_URL`. It is the only one that is a setting rather than a credential, which is true and a better hook.

Verified: 278 backend unit tests pass, including the compose guard that parses this file.

Closes #204
Refs #196

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

bermudalamb added 1 commit 2026-08-28 14:01:22 -05:00

Merge branch 'main' into feature/204-ops-doc-accuracy

SonarQube Analysis / sonarqube (pull_request) Failing after 16m59s

Details

Linting / lint (pull_request) Successful in 2m12s

Details

410aaa6d87

bermudalamb merged commit a1948a50c9 into main

2026-08-28 14:01:30 -05:00

bermudalamb deleted branch feature/204-ops-doc-accuracy

2026-08-28 14:01:30 -05:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: bermudalamb/redefined-designs#210