Dependency-Track: move the module to v5

[stephdl]

The module still runs Dependency-Track v4. Upstream v4 is end of life. No more fixes, no more analyzer updates.

I want the module on v5, released as version 2.0.0.

The obstacle is the database. v5 changed the schema, and upstream ships no online migration. So the upgrade cannot be an ordinary update-module.

Proposed solution

Ship v5 as module version 2.0.0.

Set org.nethserver.min-from=2.0.0, so Software Center never offers the update to a 1.x instance.

Add a migration script an admin runs by hand on an existing instance. It drives the upstream migrator with the application down, then hands over to update-module.

v5 cannot decrypt what v4 encrypted, so the settings are not carried over. The data is: projects, components, vulnerabilities, findings, audit history, policies, users, teams, permissions and API keys.

Document the procedure and what has to be reconfigured after it.

Alternative solutions

Migrate inside update-module. Rejected. The migration needs the services down, can run long, and can leave a half-replaced database. That does not belong in an unattended update.

Keep v4. Rejected. No upstream support.

Additional context

Implementation, and the details of the script: NethServer/ns8-dependencytrack#133

See also

• Upstream migration guide: https://dependencytrack.github.io/docs/next/guides/administration/migrating-from-v4/

[stephdl]

QA — ghcr.io/nethserver/dependencytrack:2.0.0-dev.1

Two paths to test.

1. Fresh install

add-module ghcr.io/nethserver/dependencytrack:2.0.0-dev.1 1
api-cli run configure-module --agent module/dependencytrack1 --data - <<EOF
{"host": "dependencytrack.example.com", "lets_encrypt": false}
EOF

Check:

• the UI answers on the host, login works
• podman ps shows apiserver and frontend on 5.0.5
• upload an SBOM larger than 1 MB, it must not be refused by nginx
• api-cli run get-configuration --agent module/dependencytrack1
• backup, then restore into a new instance

2. Upgrade from v4

Start from a 1.x instance holding real data: a few projects, an SBOM, an audited finding, a policy, an API key, a notification rule.

add-module ghcr.io/nethserver/dependencytrack:1.0.11 1

On the node running the app:

curl -fsSL -o /tmp/upgrade2V5.sh \
  https://raw.githubusercontent.com/NethServer/ns8-dependencytrack/main/migration/upgrade2V5.sh
runagent -m dependencytrack1 bash /tmp/upgrade2V5.sh

On the leader:

api-cli run update-module --data '{"module_url":"ghcr.io/nethserver/dependencytrack:2.0.0-dev.1","instances":["dependencytrack1"],"force":true}'

Back on the node:

runagent -m dependencytrack1 bash /tmp/upgrade2V5.sh start

Check:

• the script asks to type I have a backup before it touches anything
• projects, components, findings, audit history, policies, users, teams, permissions and API keys are all there
• the dashboards show figures, not zeros
• what the script prints at the end matches what is really missing: analyzers, Trivy, repository passwords, tokens, notification rules
• after a node reboot the instance comes back on v5

Two failure paths, one run each:

• interrupt the script while it replaces the database, then relaunch it. It must resume from state/dependencytrack-v5.pg_dump, without migrating again
• run runagent -m dependencytrack1 bash /tmp/upgrade2V5.sh start on an instance still on v4. It must refuse