From 4d90e4a7596a12eaa39a85a5183cdd5f73546c29 Mon Sep 17 00:00:00 2001 From: reinkrul Date: Tue, 2 Jun 2026 10:39:35 +0200 Subject: [PATCH] docs: complete v5 to v6 migration guide (#4257) (#4265) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs: complete v5 to v6 migration guide (#4257) 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 * docs: rework migration guide based on review 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 * docs: address review feedback on migration guide - 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 * docs: discourage SQLite in migration guide 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 (cherry picked from commit ea99418d66b633daf933e7fdbe6a9bac4dba393e) --- docs/pages/deployment/migration.rst | 136 +++++++++++++++++++++++----- 1 file changed, 111 insertions(+), 25 deletions(-) diff --git a/docs/pages/deployment/migration.rst b/docs/pages/deployment/migration.rst index 437071e888..a9ca00acaf 100644 --- a/docs/pages/deployment/migration.rst +++ b/docs/pages/deployment/migration.rst @@ -1,38 +1,124 @@ .. _nuts-node-migration: +.. _nuts-node-migrations: Migrating from v5 to v6 -************************ +*********************** -Nuts node v6 runs several migrations on startup for DID documents that are managed by the node, namely: +Operator runbook for upgrading a v5 deployment to v6 while keeping the existing ``did:nuts`` setup. Work through the steps in order. If you also want to adopt ``did:web`` as part of the upgrade, finish the main steps first, then see :ref:`also-enabling-did-web`. -1. Remove controllers and add self-control to ``did:nuts`` documents, -2. Import ``did:nuts`` documents into the new SQL database under a ``subject`` with the same name, and -3. Add a ``did:web`` document to the same ``subject``. +.. contents:: + :local: + :depth: 1 -**Migration: convert did:nuts to self-control** -Requires ``didmethods`` to contain ``nuts``. +1. Provision an SQL database +============================ -Previously, DID documents could either by under self-control or under control of another DID as was recommended for vendor and care organisation, respectively. -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. -**Migration: convert did:nuts to subject** -Requires ``didmethods`` to contain ``nuts``. +A server-based engine (PostgreSQL, MySQL, MS SQL / Azure SQL) is recommended. SQLite is supported but discouraged: it is a single-file, single-node store, so a deployment on SQLite cannot later be moved to a high-availability setup (when supported) without migrating the database. It is acceptable for small, single-node ``did:nuts``-only deployments that won't adopt ``did:web`` in the near future — there the SQL state is rebuilt at startup from BBolt and the key backend, so the cost of switching engines later is low. -All owned ``did:nuts`` DID documents will be migrated to the new SQL storage. -This migration includes all historic document updates as published upto a potential deactivation of the document. -For DIDs with a document conflict this is different than the resolved version of the document, which contains a merge of all conflicting document updates. -To prevent the state of the resolver and the SQL storage to be in conflict, all DID document conflicts must be resolved before upgrading to v6. -See ``/status/diagnostics`` if you own any DIDs with a document conflict. If so, use ``/internal/vdr/v1/did/conflicted`` to find the DIDs with a conflict. +Configure the connection string in ``storage.sql.connection``. See :ref:`storage-configuration` for the full reference. -.. note:: +.. code-block:: yaml - The document migration will run on every restart of the node, meaning that any updates made using the VDR V1 API will be migrated on the next restart. - However, any changes made via the V1 API wil NOT propagate to other DID documents under the same ``subject``, so you MUST set ``didmethods = ["nuts"]`` to use the V1 API. + # SQLite — supported but discouraged; acceptable for a small, single-node did:nuts-only upgrade + storage: + sql: + connection: sqlite:file:/opt/nuts/data/sqlite.db?_pragma=foreign_keys(1)&journal_mode(WAL) -**Migration: add did:web to subjects** -Requires ``didmethods`` to contain ``web`` and ``nuts`` (default). +2. Update the host and container references +=========================================== -This migration adds a new ``did:web`` DID Document to owned subjects that do not already have one. -A new verification method is created for the document and added to all verification relationships except KeyAgreement. -This means did:web cannot be used for encryption (yet). +The v6 container runs as UID ``18081`` (was ``root``). Before the first v6 start, on the host: + +.. code-block:: shell + + 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``. + +3. HTTP interfaces +================== + +v5 supported flexible HTTP binding via ``http..*`` (with ``http.default.*`` as the default interface; operators could define additional named interfaces like ``http.admin.*`` bound to separate addresses). v6 replaces this with two fixed interfaces — update your reverse proxy / ingress to route accordingly: + +- ``:8080`` (``http.public.address``) — public endpoints (``/iam``, ``/oauth2``, ``/n2n``, ``/.well-known``, …). +- ``127.0.0.1:8081`` (``http.internal.address``) — ``/internal``, ``/status``, ``/metrics``, ``/health``. Loopback only by default; if you need to access it from another host, set ``http.internal.address`` to ``0.0.0.0:8081`` and make sure it is not accessible to unauthorized callers (firewall, network segmentation, auth). + +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. + +See :ref:`nuts-node-recommended-deployment` for a reference topology. + +4. Adjust the config file +========================= + +Set ``didmethods = ["nuts"]`` (unless you are also adopting ``did:web`` — see :ref:`also-enabling-did-web`). The v6 default is ``["web", "nuts"]``; setting it explicitly to ``["nuts"]`` keeps the deployment behaviour aligned with v5. + +Remove or rename the following: + +.. list-table:: + :header-rows: 1 + :widths: 45 55 + + * - v5 key + - Action + * - ``auth.publicURL`` + - Replace with the new top-level ``url`` (introduced in v6). + * - All ``http..*`` interface bindings (``http.default.address``, ``http.default.tls``, ``http.default.cors.origin``, and any custom-named interfaces) + - Remove. v6 uses fixed ``http.public.address`` and ``http.internal.address``. + * - IRMA/Yivi CORS origin + - Move to ``auth.irma.cors.origin``. + * - ``network.certfile``, ``network.certkeyfile``, ``network.truststorefile`` + - Rename to ``tls.certfile``, ``tls.certkeyfile``, ``tls.truststorefile``. v6 refuses to start otherwise. + * - ``http.internal.auth.type = token`` + - No longer accepted. Either configure ``token_v2`` (see :ref:`nuts-node-api-authentication`) or rely on another authentication mechanism on the internal interface — reverse-proxy auth, mTLS, or network-level controls. + +5. Start v6 +=========== + +Back up the v5 data directory first — see `Rolling back`_. + +Bring up the v6 node. It runs the ``did:nuts`` migrations on every start (self-control rewrite and history import into SQL). The migrations are idempotent, so an interrupted upgrade is safe to retry. + +6. Check the startup logs +========================= + +Schema migrations abort startup on failure — if the node booted, those are fine. The DID-document migrations don't: per-DID failures (corrupted history, key resolution errors) are logged at ``error`` and the node keeps running with that DID missing from SQL. Grep the startup logs for ``level=error`` lines from the migration step. + +Rolling back +============ + +v6 rewrites the v5 on-disk state on first start. There is no in-place downgrade. To roll back, restore the v5 data directory from the backup you took before Step 5, then start v5. The SQL database is new in v6 and not used by v5. If you plan to retry the upgrade, wipe the SQL database first to avoid stale state. + +Other notes +=========== + +Creating DIDs with ``selfControl=false`` +---------------------------------------- + +``POST /internal/vdr/v1/did`` ignores the request body in v6. The v5 vendor-controls-care-organisation pattern is gone — new DIDs are always self-controlled, and existing ones are flattened to self-control by the startup migration. + +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. + +.. _also-enabling-did-web: + +Also enabling ``did:web`` +------------------------- + +If you also want to support ``did:web`` use cases, leave ``didmethods`` at its default (both methods enabled) — drop the ``didmethods = ["nuts"]`` line from Step 4. The startup migration adds a ``did:web`` document to every existing subject; this is one-way and cannot be reversed without manually rebuilding subjects. + +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. +- ``did:web`` resolution requires the public interface to be reachable at the configured ``url`` over HTTPS (handled by the reverse proxy from Step 3). + +After the first v6 start with ``did:web`` enabled, verify each subject contains both DIDs: + +- ``GET /internal/vdr/v2/subject/{id}`` lists both the ``did:nuts`` and the ``did:web``.