Docs: complete v5 → v6 migration guide

[reinkrul]

Context

The release notes for v6.0.0 document the breaking changes and new
concepts (see docs/pages/release_notes.rst, "Peanut (v6.0.0)"), but the
official migration guide at
docs/pages/deployment/migration.rst only covers the three on-startup
DID document migrations. Operators upgrading from v5.x have to piece
the rest of the upgrade together from release notes, individual config
pages, and the changelog.

Problem

The current migration.rst covers:

• did:nuts self-control conversion
• did:nuts → subject SQL migration (and the conflicted-document precondition)
• did:web addition to subjects

It does not cover the operational changes that actually break a v5
deployment on first start. Concretely missing:

Area	What changed in v6	Migration doc says
HTTP ports	Split into 8080 (public) and 8081 (internal, bound to 127.0.0.1)	nothing
Internal endpoints	/internal, /status, /metrics, /health moved to :8081	nothing
TLS	Server-side TLS for HTTP dropped — reverse proxy now required	nothing
API authentication	Legacy tokens removed; only /internal endpoints are protected	nothing
auth.publicURL	Removed, folded into url	nothing
IRMA/Yivi CORS	Moved to auth.irma.cors.origin	nothing
Container user	Changed from root to 18081; data dir needs chown -R 18081:18081	nothing
Docker tags	v prefix dropped (v5.0.0 → 6.0.0)	nothing
Storage	SQL database (PostgreSQL/MySQL/SQLite/MSSQL) now required	nothing
didmethods config	New parameter, default ["web","nuts"]; controls which migrations run	mentioned implicitly per migration step, not as a deployment knob
VDR v1 createDID	No longer accepts controller / selfControl	nothing
Removed features	UZI auth, deprecated network TLS properties, purposeOfUseClaim	nothing
Deprecated APIs	Auth v1, DIDMan v1, Network v1, VDR v1, external key store API	nothing
Network TLS properties	Configuring deprecated properties now fails to start	nothing
TLS optionality	Node can now run without TLS when didmethods excludes nuts	nothing
Crypto key storage	Keys linked to KID via key_reference SQL table	nothing

The current guide also doesn't tell operators the order to do things in,
or how to validate a migrated node before cutting traffic over.

Proposal

Expand docs/pages/deployment/migration.rst so it is a self-contained
upgrade runbook. Suggested structure:

1. Preconditions

• Resolve all conflicted DID documents (/status/diagnostics,
  /internal/vdr/v1/did/conflicted). Already mentioned — keep, but
  promote to its own "before you upgrade" section.
• Provision the SQL database (link to :ref:storage-configuration``).
  Note why SQL is now required: subjects, did:web management, the
  credential wallet, the discovery service, OpenID4VP/OpenID4VCI
  sessions, and the crypto key_reference table all live in SQL — it
  is no longer optional. SQLite is acceptable for small/single-node
  deployments; PostgreSQL/MySQL/MSSQL for production.
• Decide which DID methods to enable via didmethods (default
  ["web","nuts"]):
  • If you only use did:nuts (typical v5 use cases), enable only
    nuts.
  • If you plan to adopt did:web soon, keep both enabled so the
    startup migration adds a did:web document alongside each existing
    did:nuts subject.

2. Deployment changes

• HTTP interface split: explain :8080 (public) vs :8081
  (internal, default-bound to 127.0.0.1); how to expose :8081
  to other hosts when needed; that /internal, /status, /metrics,
  /health all live on :8081.
• Reverse proxy now required for TLS termination; link to
  recommended-deployment.
• Container user 18081: chown -R 18081:18081 /path/to/data on
  the host before first v6 start. Note the v-prefix drop on Docker
  tags so image pulls don't silently 404.
• Config keys to remove/rename:
  • auth.publicURL → drop; url covers it.
  • Deprecated network TLS properties → remove or node won't start.
  • IRMA/Yivi CORS → move to auth.irma.cors.origin.
• API authentication: legacy tokens are gone; only /internal is
  protected. Point to the JWT-based scheme and to the API
  authentication doc.

3. Startup migrations

Keep the existing three sections (did:nuts self-control, SQL import,
did:web add), but add:

• The note that migrations re-run on every restart, and the warning
  about VDR v1 API changes not propagating across a subject.
• What to check post-migration: /status/diagnostics, that subjects
  exist for previously owned DIDs, that did:web documents resolve.

Scope

• docs/pages/deployment/migration.rst — main rewrite
• Cross-links from docs/pages/deployment/docker.rst,
  recommended-deployment.rst, storage.rst, oauth.rst /
  api-authentication.rst where each topic is already documented in
  depth — the migration page should link out, not duplicate
• Release notes: no change (they already list the breaking changes)

Related

• Triggering issue: this issue (Docs: complete v5 → v6 migration guide #4257)
• Source of truth for the breaking-changes list: release_notes.rst,
  "Peanut (v6.0.0)" section