Skip to content

docs(self-host): add the secret convergence guide and the key rotation admin pages - #332

Open
ChambersChan wants to merge 2 commits into
mainfrom
docs/server-secrets-convergence
Open

ChambersChan wants to merge 2 commits into
mainfrom
docs/server-secrets-convergence

Conversation

@ChambersChan

Copy link
Copy Markdown
Contributor

Summary

A self-hosted instance needs two secrets of its own, SECRET_KEY and SANDBOX_JWT_SECRET; every other server secret follows SECRET_KEY. This PR documents that, and how an existing instance gets there without losing the data it already holds.

  • New guide, deploy/secret-convergence (Self-hosted → Maintenance): check what an instance still sets, remove dedicated secret variables, switch from a public default to an own SECRET_KEY, re-encrypt stored data, and remove each old value when it is safe. Includes how long each _OLD value has to stay, Docker Compose .env examples, rollback and an FAQ.
  • New admin page, basic/admin-panel/key-convergence: the Encryption key convergence page in System Admin (Server secrets, Stored ciphertexts and Personal access tokens tabs).
  • New admin page, basic/admin-panel/jwt-credentials: the JWT credentials page in System Admin, for refreshing the credentials App Builder apps hold after the JWT signing secret changes.
  • deploy/env: SECRET_KEY is described as the root secret; the storage and personal-access-token key/iv pairs are no longer marked required, because they are derived from SECRET_KEY; "Secrets and rotation" is rewritten around the two secrets and points to the guide.
  • deploy/upgrade: "Required secrets" matches the product: a missing secret does not block startup, the instance falls back to public defaults and reports it.
  • basic/admin-panel/settings, overview: the Server secrets checklist item links to the guide; the overview lists the two new pages.
  • docs.json: navigation entries for the three pages.

English and Chinese for now. The other nine locales follow in this PR once the wording is settled.

Before merging

  • The pages describe the next self-hosted release, where the two admin pages are available by default. Merge once that release is out, and add its version under "Before you start" in the guide.
  • The guide sends deployment-kit users to the "App secrets" sections of the kit's Docker and Helm READMEs. Those sections still tell older installs to leave SECRET_KEY unset; they need the adoption steps first.
  • The procedure was checked against the product's code and tests, and the shell examples were run against sample .env files. It has not been rehearsed end to end on a live instance yet.
  • Add the other nine locales.

Checks

Run locally, all passing:

  • python3 -m unittest discover -s scripts -p 'test_*.py'
  • node --test scripts/test_*.cjs
  • python3 scripts/check_docs_seo.py
  • npx --yes mintlify@4.2.1059 validate
  • npx --yes mintlify@4.2.1059 broken-links --check-anchors --check-redirects
  • Local preview: the rendered English and Chinese pages were checked (tables, the table nested in a numbered list, explicit heading anchors, and that the code blocks inside the accordions render exactly as the scripts that were tested).

…n admin pages

A self-hosted instance needs two secrets of its own, SECRET_KEY and
SANDBOX_JWT_SECRET; every other server secret follows SECRET_KEY. English
and Chinese:

- deploy/secret-convergence: how an existing instance moves to those two
  secrets without losing stored data. What to check, removing dedicated
  variables, switching from a public default to an own SECRET_KEY, how long
  each _OLD value stays, Docker Compose examples, rollback and FAQ.
- basic/admin-panel/key-convergence and jwt-credentials: the two System
  Admin pages the guide relies on.
- deploy/env and deploy/upgrade: SECRET_KEY is the root secret, the storage
  and access-token key/iv pairs are derived from it rather than required,
  and a missing secret does not block startup.
- basic/admin-panel/settings and overview: link the Server secrets
  checklist item to the guide and list the new pages.
- docs.json: navigation entries for the three pages.
…ommand

The product's startup log and the published pages already tell admins to generate secrets with openssl rand -base64 32; the hex variant added nothing (both are 32 random bytes) and made the docs disagree with the product. The Docker Compose example now replaces SECRET_KEY with a sed delimiter that base64 output cannot contain.

This branch has not been deployed

No deployments
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