Skip to content

feat(ops): answer whether a running deployment can do its work - #79

Merged
L4XB merged 1 commit into
developfrom
feat/deployment-doctor
Sep 14, 2026
Merged

L4XB merged 1 commit into
developfrom
feat/deployment-doctor

Conversation

@L4XB

@L4XB L4XB commented Sep 14, 2026

Copy link
Copy Markdown
Member

Closes #45.

The gap

preflight.sh proves a configuration is internally consistent before the
stack starts. Nothing answered the question afterwards: whether the database is
there and carries its tables, whether documents can be written, whether the
configured mail host accepts a session, and which optional features are off and
why. An operator learned each of those from a failed user action — most often a
verification mail that never arrived.

What it looks like

$ docker compose --env-file .env.selfhost exec api six-community doctor
  ok  database                  reachable with all 89 tables
  ok  storage                   writable
 off  mail                      no SMTP host configured; public registration and verification stay unavailable
 off  metadata                  no contact address; scholarly metadata calls stay unidentified
 off  web search                needs a provider key and the data-processing confirmation
 off  speech                    needs a provider key and the data-processing confirmation
 off  public spoken interviews  needs speech processing and the explicit release gate
 off  public registration       closed; create accounts with 'six-community auth create-owner'

Every configured feature answered.

Two rules it follows

Off is a decision, not a fault. An empty provider key means the operator did
not enable that feature; reporting it as a failure would train people to ignore
the output. Only a configured thing that does not work is a failure, and the
command exits non-zero exactly then.

No secret is printed. The mail check names the host and port an operator
wrote in their own configuration, never the credentials, and it sends no login
and no message — it opens a session and leaves. A test pins this with canary
values for SIX_SMTP_USERNAME, SIX_SMTP_PASSWORD and SIX_GEMINI_API_KEY and
asserts none of them reaches the output, while the feature they belong to is
still reported.

The database check compares the tables the running build expects against the
tables the database has, so a stack started without its migrations says so in
one line instead of failing at the first upload.

quickstart.sh runs it after the readiness gate, and make doctor is there for
later. A failing check never tears down a running stack.

Validation

Four new tests, 208 source files clean under mypy, ruff clean, the
deployment script tests pass, and the export audit passes with the manifest
refreshed through #76's new mode.

preflight.sh proves a configuration is internally consistent before the stack
starts. Nothing answered the question afterwards. Whether the database carries
its tables, whether documents can be written, whether the configured mail host
accepts a session — an operator found each of those out through a failed user
action, usually a registration that never arrived.

six-community doctor reports one line per answerable question. Two rules shape
it. A feature that is switched off is reported as off rather than as broken,
because an empty provider key is a deployment decision and not a fault. And no
configured secret, key fragment or credential is printed, so the output can be
pasted into an issue — a test pins that with canary values for the SMTP
credentials and the provider key.

quickstart.sh runs it once after the stack starts, so the first thing an
operator sees after "ready" is what their deployment can actually do. A failing
check does not tear down a running stack; it names what to fix.

Signed-off-by: L4XB <L4XB@users.noreply.github.com>
@L4XB

L4XB commented Sep 14, 2026

Copy link
Copy Markdown
Member Author

I have read and agree to the SixSentences CLA v1.0.

@L4XB
L4XB enabled auto-merge (squash) September 14, 2026 07:54
@L4XB
L4XB merged commit 9e2c3ac into develop Sep 14, 2026
21 of 22 checks passed
@L4XB
L4XB deleted the feat/deployment-doctor branch September 14, 2026 08:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant