docs: complete v5 to v6 migration guide (#4257)#4265
Merged
Conversation
Expand docs/pages/deployment/migration.rst from a three-migration note into a self-contained v5 to v6 upgrade runbook covering preconditions, deployment changes, the startup migrations, and post-upgrade validation. Calls out the VDR v1 / multi-method subject decision as a top-level upgrade choice rather than burying it under the SQL-import migration: on the default didmethods = ["web","nuts"], VDR v1 writes only touch did:nuts and silently drift against did:web; operators must either set didmethods = ["nuts"] or move to VDR v2. Links out to the existing storage, recommended-deployment, docker, and API-authentication pages instead of duplicating their content. Assisted by AI
Restructure as an operator runbook focused on the did:nuts-only upgrade path. Move did:web adoption, TLS termination, VDR v1 createDID behaviour, and v1/v2 API coexistence into a separate "Other notes" section so the main steps stay close to a 5-minute read. Assisted by AI
reinkrul
requested review from
gerardsn,
stevenvegt and
woutslakhorst
as code owners
Contributor
|
Coverage Impact ⬆️ Merging this pull request will increase total coverage on 🛟 Help
|
- Drop the 'move off SQLite before did:web' sentence; the earlier sentence already covers when SQLite is acceptable. - Fix the 'first start' vs 'every restart' contradiction in Step 5 — migrations run on every start. - TLS termination: 'can no longer terminate' instead of 'no longer terminates' to make the capability removal explicit. Assisted by AI
stevenvegt
reviewed
May 20, 2026
SQLite is single-file/single-node, so a deployment on it cannot later move to a high-availability setup without migrating the database. Mark it supported but discouraged; recommend a server-based engine. Assisted by AI
stevenvegt
approved these changes
Jun 2, 2026
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
2 participants
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.
Closes #4257.
Summary
Rewrites
docs/pages/deployment/migration.rstas an operator runbook for upgrading a v5 deployment to v6 while staying ondid:nuts. Six numbered steps cover the work an operator must do (SQL provisioning, host/container updates, HTTP port split, config diffs, start, log check), followed by Rolling back and Other notes that cover the smaller / optional topics (TLS termination,selfControl=falsesemantics, VDR v1/v2 mixing, did:web adoption).Scope was reduced from the original issue's full breaking-changes table to what an operator actually has to act on — release notes already enumerate the rest. Internal mechanism (BBolt, migration internals) was kept out; everything verified against the v6 code paths.
Test plan
also-enabling-did-web,nuts-node-migration,nuts-node-migrations), and cross-refs (storage-configuration,nuts-node-recommended-deployment,nuts-node-api-authentication) resolve.Assisted by AI