mirror of https://github.com/OpenIdentityPlatform/OpenDJ.git

Valery Kharseko
4 hours ago 3dceb7e4db65fc340f5e8032f43322c7d968fe00
refs
author Valery Kharseko <vharseko@3a-systems.ru>
Thursday, November 5, 2026 12:32 +0100
committer GitHub <noreply@github.com>
Thursday, November 5, 2026 12:32 +0100
commit3dceb7e4db65fc340f5e8032f43322c7d968fe00
tree 1fed477468c5442d40684eee798fd5ad79e51143 tree | zip | gz
parent 12a5e3a1dfca3b334edd9378875464c80870fc4f view | diff
[#1130] Add Getting Started, Release Notes and wiki How-To guides (#1268)

OpenDJ is missing introductory and release guides on the documentation
site, and its practical tutorials live separately in the wiki. This adds
three maintained AsciiDoc guides to the existing Maven, Antora and PDF
pipeline:

- Getting Started explains LDAP concepts and walks through a local
OpenDJ 5.2.0 installation, LDAPS and entry add/search/modify/delete
operations, including a restart and cleanup.
- Release Notes records the published 5.2.0 release, requirements,
distributions and upgrade considerations, linking to the authoritative
release history and security advisories.
- How-To migrates the wiki recipes and links existing installation and
administration procedures instead of duplicating them.

The Installation Guide also gains a Docker Compose example with a named
data volume and shutdown guidance; the How-To task directory links to
that procedure. The embedded module tests now run without module-opening
JVM flags, exercising the startup described in its How-To guide.

Fixes #1130. Existing DocBook sources remain unchanged. The source
README explains how to maintain all three guides and stage the wiki
migration.

## Wiki migration file

The requested wiki diff is included as a separate file in this PR:
[wiki-how-to-migration.patch](https://github.com/vharseko/OpenDJ/blob/c6cf562bb55203e888b614c95712b0c29f955909/opendj-doc-generated-ref/wiki-how-to-migration.patch)
([download the
patch](https://raw.githubusercontent.com/vharseko/OpenDJ/c6cf562bb55203e888b614c95712b0c29f955909/opendj-doc-generated-ref/wiki-how-to-migration.patch)).
It applies to the wiki repository, not this repository. Its application
was checked against wiki revision
`26436e39bc3f7b078e24e43c71f53a3a0b999e1b` using a separate index.

**Do not publish the wiki patch until the new documentation URLs and PDF
are live and verified.** It replaces eight tutorial bodies with
relocation notices, updates the two How-To index pages, and retains the
former collection's headings for incoming fragment links. The live wiki
has not been modified.

The companion site PR,
OpenIdentityPlatform/doc.openidentityplatform.org#41, registers all
three guides and their PDFs. Deploy the generated modules and PDFs
before merging that registration.

Automated cross-guide xref validation is tracked separately in #1271;
this PR does not add a CI link checker.

## Validation

Earlier validation of the guides and runtime examples:

- Executed the Getting Started commands on a freshly downloaded official
OpenDJ 5.2.0 ZIP under JDK 27: setup, LDAPS, add/search/modify,
persistence after restart, delete and cleanup passed.
- Generated Getting Started and Release Notes with doc-maven-plugin
3.2.2; checked each new page with the existing AsciiDoc attribute
validator and built both PDFs.
- Verified release date, Java minimum, assets and selected changes
against the official 5.2.0 release record and tagged sources.
- Ran the project's `doc-maven-plugin` 3.2.2 preprocessing, Antora
conversion and PDF generation.
- Built a site preview and checked 1,696 local navigation/content/wiki
link targets and fragments across the three guides; all resolved. The
existing attribute checker passed all 17 new AsciiDoc pages.
- Executed REST/HTTPS reads, delegated LDAP and REST password resets,
and a denied unrelated attribute modification (LDAP result 50).
- Executed clean BCFKS setup, LDAPS search and administrative access
with both required certificate aliases.
- Compiled the embedded bean at Java 11 source/API level; verified LDAP
import and temporary-directory cleanup using a Spring application
context.
- Executed the PostgreSQL 17 JDBC recipe and generated/loaded 102 LDIF
entries; verified the expected search results.
- Checked shell syntax, Kubernetes YAML and Docker Compose
configuration. Source whitespace checks pass; the attached patch retains
original wiki whitespace.

The How-To runtime checks used the available local 5.2.1-SNAPSHOT server
package on JDK 27; the new Getting Started checks used the official
5.2.0 release. Kubernetes and Cassandra were not exercised against
clusters; Compose was parsed, not launched, and a complete Spring Boot
application was not built. The initial full Maven reactor attempt could
not resolve missing local SNAPSHOT source/tool artifacts, so the earlier
documentation goals were run directly; the dependency reactor for
`opendj-embedded` was subsequently built and installed successfully for
the current validation below. The complete-site preview also reported 29
pre-existing attribute warnings in untouched OpenAM/OpenIG/OpenIDM
pages, with none from OpenDJ. Live search indexing remains a
post-deployment check.

The first review update also checked the revised password block
(contents, mode `0600`, unchanged parent-shell umask, and variable
cleanup), all 11 release assets, the upgrade checklist anchors, and the
rendered license URL.

Validation of the current revision:

- Reran doc-maven-plugin 3.2.2 preprocessing and Antora conversion, the
existing attribute checker on all 17 new pages, and the affected How-To
PDF build; all passed. The preceding documentation update rebuilt all
three PDFs. JRuby/JDK access warnings remain in the PDF build, with no
build failure.
- Executed the Cassandra configuration command against the official
5.2.0 setup-generated `java.properties` (all 38 Java-arguments keys) and
both its template and this branch's template (five keys each). Existing
JVM options and comments were preserved, and `.bak` retained the
original contents. The real `_script-util.sh` loaders received both
driver properties for every configured command and offline fallback
cases.
- The Cassandra recipe now persists driver settings for both the server
and offline tools, clears `OPENDJ_JAVA_ARGS`, and restarts before
backend creation. Removed the incorrect claim that legacy
`OPENDS_JAVA_ARGS` overrides file-based arguments in the Unix scripts.
- Built and installed the 12-module dependency reactor for
`opendj-embedded`, then ran the complete embedded module test suite on
Java 11.0.33 and Java 27: 17 tests passed on each, with no failures,
errors or skips. Surefire uses `-Xmx512m
-Dorg.bouncycastle.native.cpu_variant=java`, without `--add-opens` or
`--add-exports`; the Java 11 debug fork command confirms those
arguments. Existing compiler and manifest warnings remain in the reactor
build.
- The wiki patch is unchanged from the preceding review update, when it
was checked against wiki revision
`26436e39bc3f7b078e24e43c71f53a3a0b999e1b` using a separate index. Its
certificate stub also links the Docker image README.
- `git diff --check` passed. Cassandra was not exercised against a
cluster. Full server walkthroughs, the complete-site link scan and
Spring Boot application validation were not repeated for this update.
The live wiki remains unchanged.
3 files modified
19 files added
2600 ■■■■■ changed files
opendj-doc-generated-ref/README.md 73 ●●●●● diff | view | raw | blame | history
opendj-doc-generated-ref/pom.xml 3 ●●●●● diff | view | raw | blame | history
opendj-doc-generated-ref/src/main/asciidoc/getting-started/first-steps.adoc 171 ●●●●● diff | view | raw | blame | history
opendj-doc-generated-ref/src/main/asciidoc/getting-started/index.adoc 27 ●●●●● diff | view | raw | blame | history
opendj-doc-generated-ref/src/main/asciidoc/getting-started/overview.adoc 45 ●●●●● diff | view | raw | blame | history
opendj-doc-generated-ref/src/main/asciidoc/how-to/bcfks.adoc 90 ●●●●● diff | view | raw | blame | history
opendj-doc-generated-ref/src/main/asciidoc/how-to/cassandra-backend.adoc 47 ●●●●● diff | view | raw | blame | history
opendj-doc-generated-ref/src/main/asciidoc/how-to/debug-instance.adoc 34 ●●●●● diff | view | raw | blame | history
opendj-doc-generated-ref/src/main/asciidoc/how-to/delegate-password-reset.adoc 107 ●●●●● diff | view | raw | blame | history
opendj-doc-generated-ref/src/main/asciidoc/how-to/embedded-ldap.adoc 116 ●●●●● diff | view | raw | blame | history
opendj-doc-generated-ref/src/main/asciidoc/how-to/generate-test-data.adoc 55 ●●●●● diff | view | raw | blame | history
opendj-doc-generated-ref/src/main/asciidoc/how-to/index.adoc 38 ●●●●● diff | view | raw | blame | history
opendj-doc-generated-ref/src/main/asciidoc/how-to/jdbc-backend.adoc 63 ●●●●● diff | view | raw | blame | history
opendj-doc-generated-ref/src/main/asciidoc/how-to/kubernetes.adoc 129 ●●●●● diff | view | raw | blame | history
opendj-doc-generated-ref/src/main/asciidoc/how-to/rest-access.adoc 82 ●●●●● diff | view | raw | blame | history
opendj-doc-generated-ref/src/main/asciidoc/how-to/tasks.adoc 53 ●●●●● diff | view | raw | blame | history
opendj-doc-generated-ref/src/main/asciidoc/install-guide/chap-install.adoc 26 ●●●●● diff | view | raw | blame | history
opendj-doc-generated-ref/src/main/asciidoc/release-notes/index.adoc 27 ●●●●● diff | view | raw | blame | history
opendj-doc-generated-ref/src/main/asciidoc/release-notes/release-5.2.0.adoc 58 ●●●●● diff | view | raw | blame | history
opendj-doc-generated-ref/src/main/asciidoc/release-notes/requirements-and-upgrade.adoc 54 ●●●●● diff | view | raw | blame | history
opendj-doc-generated-ref/wiki-how-to-migration.patch 1300 ●●●●● diff | view | raw | blame | history
opendj-embedded/pom.xml 2 ●●●●● diff | view | raw | blame | history