Add v4 migration rehearsal tutorial (#79)

To make it easier to v4 users to test with a local stack and provide feedback for the migration procedure.

Signed-off-by: nscuro <nscuro@protonmail.com>

Author: nscuro

.markdownlint-cli2.yaml

@@ -24,6 +24,8 @@ config:
     siblings_only: true
   code-block-style: false
   no-space-in-code: false
+  ul-indent:
+    indent: 4
 
 globs:
 - "docs/**/*.md"

.vale/styles/config/vocabularies/DependencyTrack/accept.txt

@@ -143,6 +143,7 @@ Webex
 apiserver
 autovacuum
 crypto
+cutover
 eDirectory
 keysets?
 keytool

context/briefing.md

@@ -46,6 +46,6 @@ Version 5 (codename "Hyades") is a ground-up rearchitecture of the backend:
 
 ### Tech stack
 
-- Java 21, Jetty, Jakarta REST (Jersey), DataNucleus (JDO), Liquibase, Protocol Buffers.
+- Java 21, Jetty, Jakarta REST (Jersey), DataNucleus (JDO), Flyway, Protocol Buffers.
 - PostgreSQL as the sole external dependency.
 - Google CEL for policy evaluation and notification filtering.

context/source-inventory.md

@@ -8,12 +8,3 @@ Map of app repo paths and accuracy status of existing-docs/ files.
   Contains REST API definitions in OpenAPI format, configuration (application.properties), and database migrations.
 - **frontend**: Refers to the repository of the frontend, a SPA built with Vue.js.
   Contains route definitions and UI component structure.
-
-## Existing Docs Accuracy
-
-- **v4**: Refers to documentation of the previous major version of Dependency-Track.
-  Most of it is outdated and incomplete. General documentation such as description of the project,
-  use-cases, and integrations still apply. Built with Jekyll.
-- **v5**: Refers to the initial state of the documentation for this major version of Dependency-Track.
-  It is most thorough around the topics of operations and administration, but is missing most of the
-  truly user-facing documentation (tutorials, workflows, concepts).

docs/guides/administration/configuring-database.md

@@ -174,10 +174,10 @@ Before proceeding, take note of the following constraints:
 * Only `session` and `transaction` pooling modes are supported. `transaction` is recommended.
 * Initialisation tasks, which include database migrations, **must** connect to the
   database directly, bypassing the connection pooler, when using pooling mode `transaction`.
-  * To prevent concurrent initialisation, session-level PostgreSQL advisory locks are used,
-    which are not supported with the `transaction` pooling mode.
-  * To facilitate this, initialisation tasks can be executed in dedicated containers,
-    and / or using separate data sources.
+    * To prevent concurrent initialisation, session-level PostgreSQL advisory locks are used,
+      which are not supported with the `transaction` pooling mode.
+    * To facilitate this, initialisation tasks can be executed in dedicated containers,
+      and / or using separate data sources.
 
 ### Example
 

docs/guides/administration/migrating-from-v4.md

@@ -14,6 +14,9 @@ See the [per-release upgrade pages](../upgrading/index.md) instead.
 To try v5 against your real workload before committing to the migration, see
 [Running v4 and v5 in parallel](running-v4-and-v5-in-parallel.md).
 
+To walk this migration end to end against a sandbox v5 stack before the production cutover, see
+[Rehearsing the v4 to v5 migration](../../tutorials/rehearsing-the-v4-migration.md).
+
 ## How the migration works
 
 The `v4-migrator` command-line tool runs three offline phases (**extract**, **transform**, **load**)
@@ -111,7 +114,7 @@ The migrator ships as a container image published at `ghcr.io/dependencytrack/v4
 The examples below use the following shell alias for brevity:
 
 ```bash
-alias v4-migrator='docker run --rm -it --network=host ghcr.io/dependencytrack/hyades-apiserver-v4-migrator:<version>'
+alias v4-migrator='docker run --rm -it --network=host ghcr.io/dependencytrack/v4-migrator:<version>'
 ```
 
 !!! note

docs/guides/upgrading/v0.7.0-alpha.3.md

@@ -86,11 +86,11 @@
 * **The notification-publisher service has been removed**. Publishing of notifications
   is now performed by the API server. Refer to the [design documentation](../../concepts/architecture/design/notifications.md) for details.
 * The way notification publishers and alerts are configured behind the scenes has changed.
-  * Existing configuration is migrated during the upgrade on a best-effort basis.
-  * To prevent partially migrated alert configurations from taking effect,
-    **all alerts are turned off during the upgrade**.
-  * You must manually review and re-enable them after the upgrade.
-  * Refer to the [notification publishers documentation](../../reference/notifications/publishers.md) for guidance.
+    * Existing configuration is migrated during the upgrade on a best-effort basis.
+    * To prevent partially migrated alert configurations from taking effect,
+      **all alerts are turned off during the upgrade**.
+    * You must manually review and re-enable them after the upgrade.
+    * Refer to the [notification publishers documentation](../../reference/notifications/publishers.md) for guidance.
 * **Notifications are no longer published to Kafka by default**. Going forward, you must configure
   alerts explicitly, and use the new [Kafka publisher](../../reference/notifications/publishers.md#kafka)
   if you want to receive notifications via Kafka.
@@ -111,11 +111,11 @@
     | `alpine.database.pool.idle.timeout` | `dt.datasource.pool.idle-timeout-ms` |
     | `alpine.database.pool.max.lifetime` | `dt.datasource.pool.max-lifetime-ms` |
 
-  * For this version, the `dt.datasource.*` configurations default to their `alpine.database.*`
-    counterparts. Existing deployments should continue to function without changes.
-    Support for `alpine.database.*` configs is removed before the GA release.
-  * The new datasource configuration mechanism is documented in the
-    [datasource configuration reference](../../reference/configuration/datasources.md).
+    * For this version, the `dt.datasource.*` configurations default to their `alpine.database.*`
+      counterparts. Existing deployments should continue to function without changes.
+      Support for `alpine.database.*` configs is removed before the GA release.
+    * The new datasource configuration mechanism is documented in the
+      [datasource configuration reference](../../reference/configuration/datasources.md).
 
 * **All configuration properties have been standardized to use the `dt.` prefix**.
   Properties that previously used the `alpine.` prefix, or no prefix at all, are now under `dt.`.
@@ -127,9 +127,9 @@
     | `alpine.oidc.enabled`                | `dt.oidc.enabled`                       |
     | `task.portfolio.metrics.update.cron` | `dt.task.portfolio.metrics.update.cron` |
 
-  * The naming rule is straightforward:
-    * `alpine.<suffix>` → `dt.<suffix>` (for all former `alpine.*` properties)
-    * `<name>` → `dt.<name>` (for all previously unprefixed properties)
+    * The naming rule is straightforward:
+        * `alpine.<suffix>` → `dt.<suffix>` (for all former `alpine.*` properties)
+        * `<name>` → `dt.<name>` (for all previously unprefixed properties)
 
     When using environment variables, the same mapping applies: `ALPINE_LDAP_ENABLED` becomes
     `DT_LDAP_ENABLED`, `TASK_PORTFOLIO_METRICS_UPDATE_CRON` becomes `DT_TASK_PORTFOLIO_METRICS_UPDATE_CRON`,
@@ -157,9 +157,9 @@
   via `dt.logging.level."<logger-name>"` per-logger properties.
   Refer to the [logging documentation](../administration/configuring-observability.md#adjusting-log-levels) for details.
 * The following init task configurations have been removed and replaced with `init.tasks.datasource.name`:
-  * `init.tasks.database.url`
-  * `init.tasks.database.username`
-  * `init.tasks.database.password`
+    * `init.tasks.database.url`
+    * `init.tasks.database.username`
+    * `init.tasks.database.password`
 * Refer to [schema migration credentials](../administration/configuring-database.md#schema-migration-credentials)
   for an example of how to run init tasks with separate database credentials.
 

docs/tutorials/.pages

@@ -4,4 +4,5 @@ nav:
   - quickstart.md
   - creating-a-component-policy.md
   - setting-up-notifications.md
+  - rehearsing-the-v4-migration.md
   - ...