docs: complete v5 to v6 migration guide (#4257)#4265
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
|
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
|
|
||
| chown -R 18081:18081 /opt/nuts/data | ||
|
|
||
| Docker image tags no longer carry a ``v`` prefix — pull ``nutsfoundation/nuts-node:6.0.0``, not ``v6.0.0``. |
There was a problem hiding this comment.
better to encourage here to use only the major version so they always fetch the latest:
nutsfoundation/nuts-node:6
| In the new situation a user manages ``subjects``, and the node manages all DIDs under the ``subject``. | ||
| To reduce complexity and allow future adoption of other did methods, all documents will be under self-control from v6. | ||
| v6 requires SQL storage. Supported engines: PostgreSQL, MySQL, Microsoft SQL Server, Azure SQL, SQLite. | ||
| SQLite is acceptable for small deployments, and for ``did:nuts``-only deployments that won't adopt ``did:web`` in the near future — in that case the SQL state is rebuilt at startup from BBolt and the key backend. |
There was a problem hiding this comment.
I would say possible but discouraged.
| TLS termination | ||
| --------------- | ||
|
|
||
| v6 can no longer terminate server-side TLS for HTTP itself. If you already run v5 behind a reverse proxy or ingress (the typical setup), no change is needed. If you relied on the node's built-in TLS, move termination to a reverse proxy or ingress before upgrading. |
There was a problem hiding this comment.
I expected this to be higher up, under HTTP interfaces for example.
| Mixing VDR v1 and v2 APIs | ||
| ------------------------- | ||
|
|
||
| The v1 and v2 APIs read from different stores. Do not mix usage, or you risk data drift and stale reads. VDR v1 / DIDMan v1 are deprecated and slated for removal in a future major release. |
There was a problem hiding this comment.
This is ambiguous. When I read carefully I read that it is ok to use v1 and the warning is not to use both of them. But the deprecation warning suggest to not use v1 at all.
There was a problem hiding this comment.
If this is a footgun, shouldn't we made either one available by a config param?
|
|
||
| Additional preconditions: | ||
|
|
||
| - **Resolve all DID document conflicts on v5 first.** A conflicted ``did:nuts`` document imports into SQL as the replayed published history, not the merged state the v1 resolver returns. The new ``did:web`` is derived from the SQL view, so for any conflicted DID it will diverge from what v1 callers see. On v5, check ``GET /status/diagnostics``; if any are owned, list them via ``GET /internal/vdr/v1/did/conflicted`` and resolve each one. |
There was a problem hiding this comment.
when you enable did:web, is the sqlite backend forbidden in strict mode? (should we build this?)
| Additional preconditions: | ||
|
|
||
| - **Resolve all DID document conflicts on v5 first.** A conflicted ``did:nuts`` document imports into SQL as the replayed published history, not the merged state the v1 resolver returns. The new ``did:web`` is derived from the SQL view, so for any conflicted DID it will diverge from what v1 callers see. On v5, check ``GET /status/diagnostics``; if any are owned, list them via ``GET /internal/vdr/v1/did/conflicted`` and resolve each one. | ||
| - **Move all DID and service management to VDR v2 before the first multi-method write.** VDR v1 / DIDMan v1 writes only touch the ``did:nuts`` document, not the ``did:web`` in the same subject. Mixed use silently desynchronises the two, and the startup migrations do not repair this on later restarts. |
There was a problem hiding this comment.
should we disable the didman api's or error/warn when did:web is enabled?
2 participants
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