# 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