Repository navigation
docs(self-host): add the secret convergence guide and the key rotation admin pages - #332
Open
ChambersChan wants to merge 2 commits into
Open
ChambersChan wants to merge 2 commits into
ChambersChan wants to merge 2 commits into
Conversation
…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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
A self-hosted instance needs two secrets of its own,
SECRET_KEYandSANDBOX_JWT_SECRET; every other server secret followsSECRET_KEY. This PR documents that, and how an existing instance gets there without losing the data it already holds.deploy/secret-convergence(Self-hosted → Maintenance): check what an instance still sets, remove dedicated secret variables, switch from a public default to an ownSECRET_KEY, re-encrypt stored data, and remove each old value when it is safe. Includes how long each_OLDvalue has to stay, Docker Compose.envexamples, rollback and an FAQ.basic/admin-panel/key-convergence: the Encryption key convergence page in System Admin (Server secrets, Stored ciphertexts and Personal access tokens tabs).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_KEYis described as the root secret; the storage and personal-access-token key/iv pairs are no longer marked required, because they are derived fromSECRET_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
SECRET_KEYunset; they need the adoption steps first..envfiles. It has not been rehearsed end to end on a live instance yet.Checks
Run locally, all passing:
python3 -m unittest discover -s scripts -p 'test_*.py'node --test scripts/test_*.cjspython3 scripts/check_docs_seo.pynpx --yes mintlify@4.2.1059 validatenpx --yes mintlify@4.2.1059 broken-links --check-anchors --check-redirects