cgalo5758
71818de0bd
Implement the ux-first-run change: a state-derived setup checklist on /operator/setup with a landing region that recedes once required steps are done, and empty states that distinguish blocked from empty across operator and member surfaces. Also add production deployment and environment reference docs, plus a config-key completeness test.
3.4 KiB
deployment-docs Specification
Purpose
The README-to-production path: what a deployer needs, in what order, with every configuration key documented, so running an instance requires reading, not archaeology.
Requirements
Requirement: The README states what the system needs and the order to set it up
The repository README SHALL state, before any development-stack material: what the product is; its load-bearing external dependencies, with the FedWiki farm named up front alongside the OIDC identity provider, PostgreSQL, Valkey, Temporal, and (optional, for paid products) Stripe; and the first-run order — deploy, sign in as an operator, then follow the in-app setup checklist. The README SHALL link the production deployment guide. A reader deciding whether they can run this SHALL NOT need to leave the README to learn the dependency list or the setup order.
Scenario: Dependencies and setup order are in the README
- WHEN a prospective deployer reads the README top to bottom
- THEN they encounter the external dependency list (FedWiki farm included) and the first-run setup order before local-development material
- AND a link to the production deployment guide
Requirement: A production deployment guide exists under docs/
The repository SHALL contain a production deployment guide under docs/ covering, for an arbitrary deployment (not wiki.cafe specifically): the required services and how the app connects to each; TLS/reverse-proxy expectations and trusted-origin implications; identity-provider realm setup, including the instruction to align the realm's display branding with the configured deployment name (MC_DEPLOYMENT_NAME) so the sign-in page and the app introduce themselves with one name; Stripe webhook endpoint setup and secret handling; FedWiki farm connection and allowed site domains; and first-boot behavior (migrations run at startup, what seeding exists and that demo seeding is not for production).
Scenario: Guide covers the realm-branding alignment
- WHEN a deployer follows the identity-provider section of the guide
- THEN it instructs them to align realm display branding with the configured deployment name, and explains why (the sign-in page is rendered by the IdP, not the app)
Scenario: Guide is deployment-agnostic
- WHEN the guide names hosts, domains, or organizations in examples
- THEN they are placeholders or neutral examples, not assumptions that the deployment is wiki.cafe
Requirement: A configuration reference documents every key the app reads
The documentation SHALL include a configuration reference in which every configuration key the application reads (the mc-config.yaml keys, each of which is also settable through its derived MC_* environment override) appears with its purpose, its default, whether it is required, and its environment-variable override name. The reference SHALL state the override derivation rule (prefix MC_, uppercase, dashes and dots to underscores) and SHALL also cover environment variables read outside the config system. New keys SHALL be added to the reference in the change that introduces them.
Scenario: A key the app reads is in the reference
- WHEN the application source reads a configuration key or environment variable
- THEN that key appears in the configuration reference with purpose, default, required/optional status, and its environment override name