Validate and simplify OpenDJ guides (#1313)
## Summary
- Validate and simplify the AsciiDoc Getting Started, Installation,
Administration, and Server Developer guides against the OpenDJ tools and
code.
- Add hands-on examples for LDAP SDK clients, REST over HTTPS, access
delegation, replication, and LDAP performance measurements.
- Correct upgrade, backend migration, plugin packaging, certificate
verification, and monitoring instructions.
## Review follow-up
- After an interrupted Docker upgrade, identify all affected DN equality
indexes using the backend configuration and effective instance schema,
including inherited matching rules. Require a valid index status and
successful offline verification for every affected index before clearing
`.upgrade-pending`. Align the Docker README and upgrade startup message
with the recovery guide, including when to restore the backup.
- Explain when Docker retries bootstrap and how to recover running and
stopped containers. Mount a named data volume in the Docker README
examples. Document how to copy an instance from a stopped container's
writable layer into a volume. If OpenDJ starts in the recovery shell,
require a successful local stop before clearing `.bootstrap-pending`.
- In the ZIP upgrade example, use `stop-ds --noPropertiesFile` and
require a successful local stop, backup, and extraction before replacing
files.
- Require a restart when changing the listen address of an active JMX
handler and use `jmx-read` in the monitoring example.
- Specify the DSML and REST to LDAP WAR context paths. For Tomcat with
`unpackWARs=false`, deploy the exploded REST gateway directory and keep
the archive outside `appBase`. Identify the SASL sample's test-only TLS
settings and document `_id` for users (`uid`) and groups (`cn`).
## Verification
- The documentation module passed `mvn verify` with the `man-pages`
profile, including 36 tests, the AsciiDoc attribute check, and 644 file
cross-references across 77 pages.
- On OpenDJ 5.2.0, exercised stopped-container recovery with its
existing volume and with data copied from the writable layer. Verified
that `stop-ds --noPropertiesFile` shut down the server in the recovery
shell before the repaired volume was attached to a replacement
container. Checked index validity and offline verification before and
after rebuilding the `owner` and inherited `myManager` DN equality
indexes.
- Exercised the ZIP failure paths and confirmed that the successful
backup archived the installation and instance data with restricted
permissions.
- On Tomcat 10.1.59 with `unpackWARs=false`, confirmed that Tomcat
selects the WAR when both artifacts are present and that deploying the
exploded directory alone exposes `config.json` as a file on disk.
- In the initial pass, checked 1,007 local links across 47 rendered
pages. Exercised the HTTPS REST and password delegation recipes with
OpenDJ 5.2.0 and 5.2.1-SNAPSHOT ZIP distributions.
- Verified both directions of the replication exercise and packaged
resources in both plugin examples.