Goal
deploy/community/preflight.sh fails closed with precise messages — permissions
that are not 0600, a key that is not a fresh 32-byte value, a backup directory
inside the checkout, two keys that must differ but do not. Each message says
what is wrong. None of them says what to type next, and deploy/community/README.md
has no troubleshooting section at all.
A first-time operator hits one of these before the stack ever starts. This is the
document that decides whether they continue or close the tab.
Where
deploy/community/preflight.sh — every fail "..." call is one row
services/api/src/sixsentences_server/ops/doctor.py — the failed states are
the after-startup half
deploy/community/README.md — add the section; Checking a running deployment
is the natural neighbour
What to do
Write a table: the message as it actually appears, what it means, and the exact
command that fixes it. Read the messages out of the script rather than
paraphrasing them — a troubleshooting entry that does not match the real output
is worse than none, because it is unsearchable.
Cover at minimum: the environment-file permission check, each key-format check,
the "keys must differ" check, and the backup-directory location checks. Then the
doctor's failed states for database, storage, and mail.
Many of these are fixed by re-running deploy/community/init-env.sh. Say so
where it is true — and say where it is not, because regenerating keys on a
deployment that already holds data is not a fix.
How to verify
Trigger at least three of the failures yourself on a scratch environment file
and confirm the message you wrote down is the message that appears.
Acceptance criteria
Goal
deploy/community/preflight.shfails closed with precise messages — permissionsthat are not
0600, a key that is not a fresh 32-byte value, a backup directoryinside the checkout, two keys that must differ but do not. Each message says
what is wrong. None of them says what to type next, and
deploy/community/README.mdhas no troubleshooting section at all.
A first-time operator hits one of these before the stack ever starts. This is the
document that decides whether they continue or close the tab.
Where
deploy/community/preflight.sh— everyfail "..."call is one rowservices/api/src/sixsentences_server/ops/doctor.py— thefailedstates arethe after-startup half
deploy/community/README.md— add the section;Checking a running deploymentis the natural neighbour
What to do
Write a table: the message as it actually appears, what it means, and the exact
command that fixes it. Read the messages out of the script rather than
paraphrasing them — a troubleshooting entry that does not match the real output
is worse than none, because it is unsearchable.
Cover at minimum: the environment-file permission check, each key-format check,
the "keys must differ" check, and the backup-directory location checks. Then the
doctor's
failedstates for database, storage, and mail.Many of these are fixed by re-running
deploy/community/init-env.sh. Say sowhere it is true — and say where it is not, because regenerating keys on a
deployment that already holds data is not a fix.
How to verify
Trigger at least three of the failures yourself on a scratch environment file
and confirm the message you wrote down is the message that appears.
Acceptance criteria
bash deploy/community/test.shpasses