Add CI install-test for the Windows MSI + document MSI install/upgrade/uninstall

.github/workflows/build.yml

@@ -441,3 +441,53 @@ jobs:
           timeout 3m bash -c 'until docker inspect --format="{{json .State.Health.Status}}" test_custom | grep -q \"healthy\"; do sleep 10; done'
           docker exec test_custom 'sh' '-c' '/opt/opendj/bin/ldapsearch --hostname localhost --port 1636 --bindDN "cn=Directory Manager" --bindPassword custom_password --useSsl --trustAll --baseDN "dc=example,dc=com" --searchScope base "(objectClass=*)" 1.1'
           docker kill test_custom
+
+  test-msi:
+    needs: build-maven
+    runs-on: 'windows-latest'
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v8
+        with:
+          name: windows-latest-11
+      - name: Set up Java
+        uses: actions/setup-java@v5
+        with:
+          java-version: '25'
+          distribution: 'zulu'
+      - name: Install MSI (silent)
+        shell: pwsh
+        run: |
+          $msi = (Get-ChildItem -Recurse -Filter *.msi -Path opendj-packages/opendj-msi | Select-Object -First 1).FullName
+          if (-not $msi) { throw "MSI not found in the windows-latest-11 artifact" }
+          Write-Host "MSI: $msi"
+          $p = Start-Process msiexec -Wait -PassThru -ArgumentList "/i `"$msi`" /quiet /qn /norestart OPENDJ=C:\opendj /l*v install.log"
+          if ($p.ExitCode -ne 0) { Get-Content install.log -Tail 80; throw "msiexec /i failed: $($p.ExitCode)" }
+          $root = @("C:\opendj","C:\Program Files (x86)\OpenDJ","C:\Program Files\OpenDJ") | Where-Object { Test-Path "$_\setup.bat" } | Select-Object -First 1
+          if (-not $root) { Get-Content install.log -Tail 80; throw "OpenDJ install root with setup.bat not found" }
+          Write-Host "Installed to $root"
+          "OPENDJ_ROOT=$root" | Out-File -FilePath $env:GITHUB_ENV -Append
+      - name: Setup and start/stop the Windows service
+        shell: pwsh
+        run: |
+          $root = $env:OPENDJ_ROOT
+          $env:OPENDJ_JAVA_ARGS = "-server -Xmx512m"
+          & "$root\setup.bat" -h localhost -p 1389 --ldapsPort 1636 --adminConnectorPort 4444 --enableStartTLS --generateSelfSignedCertificate --rootUserDN "cn=Directory Manager" --rootUserPassword password --baseDN dc=example,dc=com --addBaseEntry --cli --acceptLicense --no-prompt --doNotStart
+          if ($LASTEXITCODE -ne 0) { throw "setup.bat failed: $LASTEXITCODE" }
+          & "$root\bat\windows-service.bat" --enableService
+          if ($LASTEXITCODE -ne 0) { throw "windows-service --enableService failed: $LASTEXITCODE" }
+          net start "OpenDJ Server"
+          if ($LASTEXITCODE -ne 0) { throw "net start failed: $LASTEXITCODE" }
+          for ($i=0; $i -lt 12; $i++) { try { $c = New-Object System.Net.Sockets.TcpClient('localhost', 1636); $c.Close(); break } catch { Start-Sleep -Seconds 5 } }
+          & "$root\bat\ldapsearch.bat" --hostname localhost --port 1636 --bindDN "cn=Directory Manager" --bindPassword password --useSsl --trustAll --baseDN "dc=example,dc=com" --searchScope base "(objectClass=*)" 1.1
+          if ($LASTEXITCODE -ne 0) { throw "ldapsearch failed: $LASTEXITCODE" }
+          net stop "OpenDJ Server"
+          if ($LASTEXITCODE -ne 0) { throw "net stop failed: $LASTEXITCODE" }
+          & "$root\bat\windows-service.bat" --disableService
+      - name: Uninstall MSI
+        shell: pwsh
+        run: |
+          $msi = (Get-ChildItem -Recurse -Filter *.msi -Path opendj-packages/opendj-msi | Select-Object -First 1).FullName
+          $p = Start-Process msiexec -Wait -PassThru -ArgumentList "/x `"$msi`" /quiet /qn /norestart /l*v uninstall.log"
+          if ($p.ExitCode -ne 0) { Get-Content uninstall.log -Tail 80; throw "msiexec /x failed: $($p.ExitCode)" }
+          Write-Host "Uninstalled OK"

opendj-doc-generated-ref/src/main/asciidoc/install-guide/chap-install.adoc

@@ -40,6 +40,8 @@ This chapter covers installation of OpenDJ server software and includes the foll
 
 * xref:#install-rpm["To Install From the RPM Package"]
 
+* xref:#install-msi["To Install With the Windows Installer (MSI)"]
+
 * xref:#install-properties-file["To Install OpenDJ Directory Server With a Properties File"]
 
 * xref:#pdb-to-je["To Move Data from a PDB Backend to a JE Backend"]
@@ -635,6 +637,48 @@ opendj         0:off    1:off    2:on    3:on    4:on    5:on    6:off
 
 ====
 
+[#install-msi]
+.To Install With the Windows Installer (MSI)
+====
+On Windows you can install OpenDJ directory server from the `.msi` package. The installer only copies the server files to disk: it does not configure or start a server, it does not register a Windows service, and it does not install a Java runtime.
+
+. Make sure a supported Java runtime is available, as described in xref:#before-you-install["To Prepare For Installation"].
++
+The installer does not check for Java. If your default Java environment is not appropriate, set `OPENDJ_JAVA_HOME` to the correct Java installation (or `OPENDJ_JAVA_BIN` to the absolute path of the `java` command), or make sure `java` is on the `PATH`, before you run `setup` or start the server.
+
+. Install the package, either with the GUI or silently:
++
+* GUI: double-click `opendj-{opendj-version}.msi` and follow the wizard.
++
+* Silent: run the following command (optionally set the installation directory with the `OPENDJ` property):
++
+
+[source, console, subs="attributes"]
+----
+C:\> msiexec /i opendj-{opendj-version}.msi /quiet OPENDJ="C:\opendj"
+----
++
+By default the package installs under `C:\Program Files\OpenDJ` (the 32-bit installer uses `C:\Program Files (x86)\OpenDJ` on 64-bit Windows).
+
+. Configure OpenDJ directory server by running the `setup` command, described in xref:../reference/admin-tools-ref.adoc#setup-1[setup(1)] in the __Reference__, from the installation directory. Use `setup.bat` for the GUI wizard or `setup.bat --cli` for the command-line:
++
+
+[source, console]
+----
+C:\path\to\opendj> setup.bat --cli
+----
+
+. (Optional)  Register OpenDJ as a Windows service and start it. The MSI does not register the service; use the `windows-service` command:
++
+
+[source, console]
+----
+C:\path\to\opendj\bat> windows-service.bat --enableService
+C:\> net start "OpenDJ Server"
+----
+
+====
+
 [#install-properties-file]
 .To Install OpenDJ Directory Server With a Properties File
 ====

opendj-doc-generated-ref/src/main/asciidoc/install-guide/chap-uninstall.adoc

@@ -12,7 +12,7 @@
   information: "Portions copyright [year] [name of copyright owner]".
 
   Copyright 2017 ForgeRock AS.
-  Portions Copyright 2024 3A Systems LLC.
+  Portions Copyright 2024-2026 3A Systems LLC.
 ////
 
 :figure-caption!:
@@ -33,6 +33,8 @@ This chapter includes the following procedures:
 
 * xref:#uninstall-rpm["To Uninstall the RPM Package"]
 
+* xref:#uninstall-msi["To Uninstall the Windows MSI Package"]
+
 
 [#uninstall-gui]
 .To Remove OpenDJ With the GUI Uninstaller
@@ -157,3 +159,28 @@ Removing the package does not remove your data or configuration. You must remove
 
 ====
 
+[#uninstall-msi]
+.To Uninstall the Windows MSI Package
+====
+Remove OpenDJ directory server installed from the `.msi` package like any other Windows program.
+
+. If OpenDJ is registered as a Windows service, remove the service first:
++
+
+[source, console]
+----
+C:\path\to\opendj\bat> windows-service.bat --disableService
+----
+
+. Uninstall the package, either through __Settings > Apps__ (or __Control Panel > Programs and Features__) by selecting OpenDJ and choosing Uninstall, or from the command-line:
++
+
+[source, console, subs="attributes"]
+----
+C:\> msiexec /x opendj-{opendj-version}.msi /quiet
+----
++
+Uninstalling removes the files installed by the package. Your configured instance data under the installation directory (for example `config`, `db`, and `logs`) is not removed; delete the installation directory manually to remove all files.
+
+====
+

opendj-doc-generated-ref/src/main/asciidoc/install-guide/chap-upgrade.adoc

@@ -45,6 +45,8 @@ This chapter includes the following procedures and examples:
 
 * xref:#upgrade-zip-example["Upgrading to OpenDJ {opendj-version-short}"]
 
+* xref:#upgrade-msi["To Upgrade the Windows MSI Installation"]
+
 * xref:#upgrade-repl["To Upgrade Replicated Servers"]
 
 * xref:#new-repl-mixed-topology["To Add a New Replica to an Existing Topology"]
@@ -243,6 +245,51 @@ $
 ----
 ====
 
+[#upgrade-msi]
+.To Upgrade the Windows MSI Installation
+====
+Before starting this procedure, follow the steps in xref:#before-you-upgrade["Before You Upgrade"]. Installing the newer `.msi` performs a major upgrade that replaces the installed program files, so make a full file-system backup of the current installation first.
+
+. Stop the current OpenDJ server.
+
+. If OpenDJ is registered as a Windows service, disable the service:
++
+
+[source, console]
+----
+C:\path\to\opendj\bat> windows-service.bat --disableService
+----
+
+. Back up the file-system directory where OpenDJ is installed.
+
+. Install the newer package (GUI or silent), using the same installation directory as the current server. Your configured instance data (`config`, `db`, `logs`) is kept; only the program files are replaced:
++
+
+[source, console, subs="attributes"]
+----
+C:\> msiexec /i opendj-{opendj-version}.msi /quiet OPENDJ="C:\path\to\opendj"
+----
+
+. Run the `upgrade` command, described in xref:../reference/admin-tools-ref.adoc#upgrade-1[upgrade(1)] in the __Reference__, to bring the configuration and application data up to date with the new binary and script files:
++
+
+[source, console]
+----
+C:\path\to\opendj> upgrade.bat --no-prompt --acceptLicense
+----
+
+. Start the upgraded OpenDJ server.
+
+. If you disabled the Windows service, enable it again:
++
+
+[source, console]
+----
+C:\path\to\opendj\bat> windows-service.bat --enableService
+----
+
+====
+
 [#upgrade-repl]
 .To Upgrade Replicated Servers
 ====

opendj-packages/opendj-msi/opendj-msi-standard/resources/msi/package.wxs

@@ -13,7 +13,7 @@
  ! information: "Portions Copyright [year] [name of copyright owner]".
  !
  ! Copyright 2013-2016 ForgeRock AS.
- ! Portion Copyright 2018 Open Identity Platform Community
+ ! Portions Copyright 2018-2026 3A Systems, LLC
  ! -->
 <Wix xmlns="http://schemas.microsoft.com/wix/2006/wi">
   <Product Id="*" Codepage="1252" Language="1033" Manufacturer="Open Identity Platform Community"