OpenIdentityPlatform · vharseko · Jun 26, 2026 · Jun 28, 2026 · Jun 28, 2026 · Jun 28, 2026
diff --git a/.gitattributes b/.gitattributes
@@ -1,3 +1,8 @@
+# WiX sources must stay LF so the WiX toolset parses them consistently across runners.
+*.wxs text eol=lf
+# The checked-in Windows launcher/service binaries are actively maintained: never diff,
+# merge or eol-convert them.
+*.exe binary
 # Keep HTML checked out with LF on all platforms so javadoc doclint
 # (JDK 25/26) does not treat CR (from CRLF) as part of a multi-line tag name.
 *.html text eol=lf
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
@@ -26,8 +26,11 @@ concurrency:
 
 # contents: write is required to push the generated documentation to the project wiki
 # with github.token. The doc site push uses a separate PAT, not this token.
+# actions: read is required to download the MSI artifact from the triggering Build run
+# (a permissions block sets every unlisted scope to none).
 permissions:
   contents: write
+  actions: read
 
 jobs:
   package-deploy-maven:
@@ -38,19 +41,12 @@ jobs:
         env:
           GITHUB_CONTEXT: ${{ toJSON(github) }}
         run: echo "$GITHUB_CONTEXT"
-      - name: Install wine+rpm for distribution
+      - name: Install rpm for distribution
         if: runner.os == 'Linux'
         shell: bash
         run:   |
-          sudo rm -f /etc/apt/sources.list.d/microsoft-prod.list
-          sudo dpkg --add-architecture i386
-          sudo mkdir -pm755 /etc/apt/keyrings && sudo wget -O /etc/apt/keyrings/winehq-archive.key https://dl.winehq.org/wine-builds/winehq.key
-          sudo wget -NP /etc/apt/sources.list.d/ https://dl.winehq.org/wine-builds/ubuntu/dists/$(lsb_release -c -s)/winehq-$(lsb_release -c -s).sources
           sudo apt-get update
-          sudo apt install --install-recommends winehq-stable || sudo apt install --install-recommends winehq-staging
-          wine --version
-          version="9.4.0"; sudo wget "https://dl.winehq.org/wine/wine-mono/$version/wine-mono-$version-x86.msi" -O /tmp/wine-mono.msi
-          wine msiexec /i /tmp/wine-mono.msi
+          sudo apt-get install -y rpm
       - uses: actions/checkout@v6
         with:
           fetch-depth: 0
@@ -114,11 +110,22 @@ jobs:
         with:
          name: OpenDJ RPM Package
          path: opendj-packages/opendj-rpm/opendj-rpm-standard/target/rpm/opendj/RPMS/noarch/*.rpm
+      # The MSI can only be built on Windows; reuse the one already built by the triggering
+      # Build run (windows-latest-11 artifact) instead of rebuilding it here.
+      - name: Download Windows build artifact (contains the MSI)
+        continue-on-error: true
+        uses: actions/download-artifact@v8
+        with:
+          name: windows-latest-11
+          run-id: ${{ github.event.workflow_run.id }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          path: windows-build
       - name: Upload artifacts OpenDJ MSI Package
+        continue-on-error: true
         uses: actions/upload-artifact@v7
         with:
          name: OpenDJ MSI Package
-         path: opendj-packages/opendj-msi/opendj-msi-standard/target/*.msi
+         path: windows-build/opendj-packages/opendj-msi/opendj-msi-standard/target/*.msi
       - name: Upload artifacts OpenDJ Docker Packages
         uses: actions/upload-artifact@v7
         with:
@@ -193,3 +200,4 @@ jobs:
             git commit -a -m "upload ${{github.event.repository.name}} docs after deploy ${{ github.sha }}"
             git push --force https://github.com/OpenIdentityPlatform/doc.openidentityplatform.org.git
           fi
+
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -45,18 +45,11 @@ jobs:
         env:
           GITHUB_CONTEXT: ${{ toJSON(github) }}
         run: echo "$GITHUB_CONTEXT"
-      - name: Install wine+rpm for distribution
+      - name: Install rpm for distribution
         shell: bash
         run:   |
-          sudo rm -f /etc/apt/sources.list.d/microsoft-prod.list
-          sudo dpkg --add-architecture i386
-          sudo mkdir -pm755 /etc/apt/keyrings && sudo wget -O /etc/apt/keyrings/winehq-archive.key https://dl.winehq.org/wine-builds/winehq.key
-          sudo wget -NP /etc/apt/sources.list.d/ https://dl.winehq.org/wine-builds/ubuntu/dists/$(lsb_release -c -s)/winehq-$(lsb_release -c -s).sources
           sudo apt-get update
-          sudo apt install --install-recommends winehq-stable || sudo apt install --install-recommends winehq-staging
-          wine --version
-          version="9.4.0"; sudo wget "https://dl.winehq.org/wine/wine-mono/$version/wine-mono-$version-x86.msi" -O /tmp/wine-mono.msi
-          wine msiexec /i /tmp/wine-mono.msi
+          sudo apt-get install -y rpm
       - uses: actions/checkout@v6
         with:
           fetch-depth: 0
@@ -96,6 +89,15 @@ jobs:
           MAVEN_OPTS: -Dhttps.protocols=TLSv1.2 -Dmaven.wagon.httpconnectionManager.ttlSeconds=120 -Dmaven.wagon.http.retryHandler.requestSentEnabled=true -Dmaven.wagon.http.retryHandler.count=10
         if: ${{ env.MAVEN_USERNAME!='' && env.MAVEN_PASSWORD!='' }}
         run: mvn --batch-mode -Darguments="-Dgpg.passphrase=${{ secrets.GPG_PASSPHRASE }}" -DsignTag=true -DtagNameFormat="${{ github.event.inputs.releaseVersion }}" -DreleaseVersion=${{ github.event.inputs.releaseVersion }} -DdevelopmentVersion=${{ github.event.inputs.developmentVersion }} release:prepare release:perform --file pom.xml
+      # Hand the just-released server zip to the release-msi job (the MSI can only be
+      # built on Windows), so it does not have to rebuild opendj-server-legacy.
+      - name: Upload the server zip for the MSI job
+        continue-on-error: true
+        uses: actions/upload-artifact@v7
+        with:
+          name: release-server-zip
+          retention-days: 1
+          path: target/checkout/opendj-server-legacy/target/package/*.zip
       - name: Release on GitHub
         uses: softprops/action-gh-release@3d0d9888cb7fd7b750713d6e236d1fcb99157228 # v3.0.2
         with:
@@ -110,7 +112,6 @@ jobs:
             target/checkout/opendj-ldap-toolkit/target/*.zip
             target/checkout/opendj-packages/opendj-deb/opendj-deb-standard/target/*.deb
             target/checkout/opendj-packages/opendj-rpm/opendj-rpm-standard/target/rpm/opendj/RPMS/noarch/*.rpm
-            target/checkout/opendj-packages/opendj-msi/opendj-msi-standard/target/*.msi
             target/checkout/opendj-packages/opendj-docker/target/Dockerfile.zip
             target/checkout/opendj-packages/opendj-openshift-template/*.yaml
             target/checkout/opendj-doc-generated-ref/target/*.zip
@@ -156,6 +157,69 @@ jobs:
           git tag -f ${TAG_NAME}
           git push --quiet --force origin ${TAG_NAME}
 
+  # The MSI can only be built on Windows. Reuses the server zip built by release-maven
+  # (installed into the local repo), so only the opendj-msi-standard module is built here.
+  # continue-on-error: an MSI failure must not break the release.
+  release-msi:
+    name: Windows MSI release
+    runs-on: 'windows-latest'
+    continue-on-error: true
+    # contents: write is required by action-gh-release to attach the MSI to the release;
+    # the workflow-level default above is contents: read.
+    permissions:
+      contents: write
+    needs:
+      - release-maven
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event.inputs.releaseVersion }}
+          submodules: recursive
+      - name: Set up Java
+        uses: actions/setup-java@v5
+        with:
+          java-version: '11'
+          distribution: 'temurin'
+      - name: Cache Maven packages
+        uses: actions/cache@v5
+        with:
+         path: ~/.m2/repository
+         key: ${{ runner.os }}-m2-repository-${{ hashFiles('**/pom.xml') }}
+         restore-keys: ${{ runner.os }}-m2-repository
+      - name: Setup WiX (.NET tool)
+        shell: bash
+        run: |
+          echo "DOTNET_ROLL_FORWARD=Major" >> "$GITHUB_ENV"
+          export DOTNET_ROLL_FORWARD=Major
+          dotnet tool install --global wix --version 5.0.2 || dotnet tool update --global wix --version 5.0.2
+          echo "$HOME/.dotnet/tools" >> "$GITHUB_PATH"
+          export PATH="$HOME/.dotnet/tools:$PATH"
+          wix --version
+          wix extension add -g WixToolset.UI.wixext/5.0.2 || true
+      - name: Download the server zip built by release-maven
+        uses: actions/download-artifact@v8
+        with:
+          name: release-server-zip
+          path: server-zip
+      - name: Install the server zip into the local Maven repository
+        shell: bash
+        run: |
+          ZIP=$(ls server-zip/*.zip | head -1)
+          echo "Installing $ZIP as opendj-server-legacy:${{ github.event.inputs.releaseVersion }}:zip"
+          mvn --batch-mode install:install-file -Dfile="$ZIP" \
+            -DgroupId=org.openidentityplatform.opendj -DartifactId=opendj-server-legacy \
+            -Dversion=${{ github.event.inputs.releaseVersion }} -Dpackaging=zip
+      - name: Build the MSI (packaging only, no rebuild)
+        env:
+          MAVEN_OPTS: -Dhttps.protocols=TLSv1.2 -Dmaven.wagon.httpconnectionManager.ttlSeconds=120 -Dmaven.wagon.http.retryHandler.requestSentEnabled=true -Dmaven.wagon.http.retryHandler.count=10
+        run: mvn --batch-mode --errors -DskipTests package -pl :opendj-msi-standard --file pom.xml
+      - name: Attach the MSI to the GitHub release
+        uses: softprops/action-gh-release@3d0d9888cb7fd7b750713d6e236d1fcb99157228 # v3.0.2
+        with:
+          tag_name: ${{ github.event.inputs.releaseVersion }}
+          fail_on_unmatched_files: true
+          files: opendj-packages/opendj-msi/opendj-msi-standard/target/*.msi
+
   release-docker:
     name: Docker release
     runs-on: 'ubuntu-latest'

diff --git a/opendj-doc-generated-ref/src/main/asciidoc/install-guide/chap-install.adoc b/opendj-doc-generated-ref/src/main/asciidoc/install-guide/chap-install.adoc
@@ -640,14 +640,16 @@ 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.
+On Windows you can install OpenDJ directory server from the `.msi` package. The installer copies the server files to disk and registers the `OpenDJ Server` Windows service, but it does not configure or start a server (run `setup` first) 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.
+The installer itself does not check for or install Java, but `setup` and the server require it: install a JRE (for example link:https://adoptium.net[Eclipse Temurin, window=\_blank]) and set `JAVA_HOME` to your Java installation, or make sure the `java` executable is on the `PATH`. If your default Java environment is not the one OpenDJ should use, set `OPENDJ_JAVA_HOME` to the correct Java installation (or `OPENDJ_JAVA_BIN` to the absolute path of the `java` command) before you run `setup` or start the server.
 
 . Install the package, either with the GUI or silently:
 +
+The package is not code-signed, so Windows SmartScreen or User Account Control may warn about an unrecognized publisher; choose to run the installer anyway.
++
 * 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):
@@ -658,7 +660,7 @@ The installer does not check for Java. If your default Java environment is not a
 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).
+When `OPENDJ` is not given, the installer uses an existing OpenDJ installation directory when it detects one — the location recorded in the registry by a previous x64 package, or the legacy 32-bit default `C:\Program Files (x86)\OpenDJ` — and otherwise installs under `C:\Program Files\OpenDJ`.
 
 . 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:
 +
@@ -668,12 +670,11 @@ By default the package installs under `C:\Program Files\OpenDJ` (the 32-bit inst
 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:
+. Start the OpenDJ Windows service. The installer already registered it as `OpenDJ Server`; after configuring with `setup`, start it (it is not started automatically during installation):
 +
 
 [source, console]
 ----
-C:\path\to\opendj\bat> windows-service.bat --enableService
 C:\> net start "OpenDJ Server"
 ----
 

diff --git a/opendj-doc-generated-ref/src/main/asciidoc/install-guide/chap-uninstall.adoc b/opendj-doc-generated-ref/src/main/asciidoc/install-guide/chap-uninstall.adoc
@@ -162,17 +162,9 @@ 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.
+Remove OpenDJ directory server installed from the `.msi` package like any other Windows program. The uninstaller stops and removes the `OpenDJ Server` Windows service that the package registered.
 
-. 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:
+* 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"]

diff --git a/opendj-doc-generated-ref/src/main/asciidoc/install-guide/chap-upgrade.adoc b/opendj-doc-generated-ref/src/main/asciidoc/install-guide/chap-upgrade.adoc
@@ -70,7 +70,7 @@ To move to a newer version, edit the `default.java-home` setting in the `opendj/
 
 . Download the latest release from the link:https://github.com/OpenIdentityPlatform/OpenDJ/releases[GitHub, window=\_blank] site.
 
-. (Optional)  If you are upgrading OpenDJ directory server on Windows, and OpenDJ is registered as a Windows service, disable OpenDJ as a Windows service before upgrade, as in the following example:
+. (Optional)  If you are upgrading OpenDJ directory server installed from the cross-platform (.zip) delivery on Windows, and OpenDJ is registered as a Windows service, disable OpenDJ as a Windows service before upgrade, as in the following example:
 +
 
 [source, console]
@@ -79,6 +79,8 @@ C:\path\to\opendj\bat> windows-service.bat --disableService
 ----
 +
 After upgrade, you can enable OpenDJ as a Windows service again.
++
+This step does not apply to servers installed from the `.msi` package: the installer manages the `OpenDJ Server` service itself (see xref:#upgrade-msi["To Upgrade the Windows MSI Installation"]), and `windows-service.bat --disableService` refuses to remove the installer-managed service.
 
 . Make sure you perform a full backup of your current OpenDJ installation to revert if the upgrade fails.
 +
@@ -257,25 +259,19 @@ $
 ====
 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
-----
+. Stop the current OpenDJ server (if it runs as a Windows service, `net stop "OpenDJ Server"`).
 
 . 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:
+. Install the newer package (GUI or silent). The installer detects the existing installation — the location recorded in the registry by a previous x64 package, or the default directory of the older 32-bit package (`C:\Program Files (x86)\OpenDJ`) — and installs into the same directory, so your configured instance data (`config`, `db`, `logs`) is kept and only the program files are replaced. If the older server was installed in a custom directory the installer did not detect, select that directory in the GUI or pass it explicitly:
 +
 
 [source, console, subs="attributes"]
 ----
 C:\> msiexec /i opendj-{opendj-version}.msi /quiet OPENDJ="C:\path\to\opendj"
 ----
++
+The installer replaces a service registered by the older `windows-service.bat` command with the MSI-managed `OpenDJ Server` service automatically; no manual `--disableService`/`--enableService` is needed.
 
 . 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:
 +
@@ -285,14 +281,12 @@ C:\> msiexec /i opendj-{opendj-version}.msi /quiet OPENDJ="C:\path\to\opendj"
 C:\path\to\opendj> upgrade.bat --no-prompt --acceptLicense
 ----
 
-. Start the upgraded OpenDJ server.
-
-. If you disabled the Windows service, enable it again:
+. Start the upgraded OpenDJ server:
 +
 
 [source, console]
 ----
-C:\path\to\opendj\bat> windows-service.bat --enableService
+C:\> net start "OpenDJ Server"
 ----
 
 ====