Skip to content

docs(self-host): map the preflight failure messages to their fixes #94

Description

@L4XB

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

  • Every message in the table is copied from the script, not paraphrased
  • Each row names the command that fixes it
  • The rows where regenerating keys would destroy data say so
  • bash deploy/community/test.sh passes

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:self-hostingCommunity deployment, upgrades, backup, and recoverydocumentationImprovements or additions to documentationeffort:smallA few files, no system-wide knowledge neededgood first issueGood for newcomers

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions