docs(onprem): recover a Compose first install that gives up during initialization

[Maffooch]

Description

Documents how to recover a self-hosted Docker Compose install when dojo-compose-cli 2.1.x reports that first-install failed while the database initializer is still running.

On a slower host the first start takes a long time, because the init container creates the whole database schema before the application comes up. On the smallest Compose host in the sizing table this can take about 30 minutes, and the 2.1.x CLI stops waiting before then. The run prints an error, prints no admin credentials, does not create the systemd service, and does not mark the install as initialized. The initializer usually finishes on its own in the background, so the install does not need to be redone.

• Installing on Docker Compose. A new troubleshooting section, "First install reports a failure while the initializer is still running", walks through the recovery: check the init container's state and exit code with docker inspect, wait for it to exit with code 0, then run sudo -E dojo-compose-cli app start. On an install not yet marked initialized, app start finishes the first start: it creates the systemd service, sets and prints a new admin password, and marks the install initialized. The section explains that the CLI does not store that password, so a missed password is reset with app change-password. A non-zero exit code points to the existing Reading the initializer's result table. The install section also notes the expected first-start time and links to the recovery.
• Hardware sizing. A new "How long the first start takes" section says to allow about 30 minutes for the first start on the smallest Compose tier and links to the recovery steps.

English only; translations follow the quarterly refresh described in docs/TRANSLATIONS.md.

Test results

Docs only. npm run build -- --environment development in docs/ builds with no warnings or errors. The rendered pages carry the new #first-install-reports-a-failure-while-the-initializer-is-still-running and #how-long-the-first-start-takes anchors, and the links to #reading-the-initializers-result and #sizing-table resolve.

🤖 Generated with Claude Code

[Maffooch]

Review: APPROVE (after two rounds)

Reviewed by a separate session that did not write this PR. Every command and claim was checked against dojo-compose-cli releases 2.1.0 to 2.1.5.

• Accurate for every 2.1.x release:
  • why first-install gives up on a slow host (its compose up time limit is shorter than a slow first initialization);
  • what it leaves undone (the systemd service, the admin password, the initialized flag);
  • that app start completes those steps on an install that is not marked initialized.
• Container and service names: init, dojo and defectdojo-compose are correct for both the containerized and the separate database layouts.
• Commands: config print, app change-password and diagnostics collect exist in every 2.1.x release and behave as described. sudo -E is correct.

Fixed after the first round:

• what to do with exit codes outside the initializer table, such as 137;
• an explicit warning not to run app stop while init is still running;
• retry steps after a failed init;
• the same 30-minute framing on both pages;
• a link to the existing password-reset section, plus the admin username;
• the DOJO_CLI_KEY export moved before its first use;
• a note for when the init container does not exist yet;
• a systemctl is-enabled check, since 2.1.0 to 2.1.2 do not enable the service.

Fixed after the second round:

• the "already running" case now sits under the step where it happens;
• sudo dmesg, since Ubuntu restricts the kernel log to root.

The docs build is clean, with no warnings.

Not tested here: the recovery has not yet been run on a real slow host. A run on the documented minimum host is planned and will report back.

🤖 Generated with Claude Code