Building Windows Installers using Wix4

Owned by Rod Widdowson
Last updated: Aug 12, 2024
3 min read

Two installers are built to support Windows users:

  1. The IdP installer is a thin shim on top of the standard installer

    1. It unpacks the distribution into ProgramData

    2. It collects some configuration information and captures it to properties files

    3. It runs the standard installer using Property Driven Installation

  2. The Jetty installer deploys three subsystems

    1. A specific version of Jetty

    2. Procrun (a windows executable which allows Java programs to be run as a “Service” (Windows-speak for a daemon)

    3. A version of jetty-base for Windows targeted at the IdP installation

Both of these can be build using WiX4 which in turn is invoked as part of a standard maven run (on a suitable configured Windows machine). These pages describe how to build a release of these installers

Prerequisites (one-off)

The Windows machine you will use to do the build Installation box must have the following installed

  • Java JDK version 17 or later

    • Ensure that JAVA_HOME is set correctly

  • Maven

  • Git

  • A recent version of the .NET SDK

  • An appropriate settings.xml

Building a Release of the IdP installer

The install requires the idp-distribution zip file for the release and so the build can be done any time after it is available in Nexus.

Checkout the Release tag

git checkout "tag"

Check the msi Version

The msi.version property is the version that the msi file will carry. It is separate from the project.version because

  • It must be strictly numeric.

  • It has a final digit (to allow multiple installer releases for the same IdP release). We usually use ‘99’ to mean “SNAPSHOT”.

At the time of release the version should match the project version with an appropriate 4th digit. If you need to edit it you will need to push a tag for the changed file.

Build the msi file

This is done using maven, on an appropriate windows machine. You need to run the idp-msi and the idp-bom projects only.

mvn clean install -rf :idp-msi

Make sure that the bom project runs - this will run the “m2 enforcer”.

Sign and deploy the msi file

Use the maven sign-and-deploy plugin. The following is an untested example

ssh -L 1581:127.0.0.1:1581 -N build.shibboleth.net -f REM or use Putty set VERSION=5.1.2 set NEXUS_URL=http://127.0.0.1:1581/nexus/content/repositories/releases set REPO_ID=release SET CL1=mvn -Dmaven.repo.local=%MAVEN_REPO% gpg:sign-and-deploy-file -Durl=%NEXUS_URL% -DrepositoryId=%REPO_ID% SET CL2=-Dfile=shibboleth-identity-provider-%VERSION%-x64.msi -DgroupId=net.shibboleth.idp -DartifactId=idp-msi SET CL3=-Dversion=%VERSION% -DgeneratePom=false -Dclassifier=msi Set SIGN_AND_DEPLOY=%CL1% %CL2% %CL3% %SIGN_AND_DEPLOY%

If you are deploying a version with a non zero version (e.g. 5.1.2.1) you will need to rename the msi file by hand.

Building a Release of the Jetty Installer

There are two parts to releasing the Jetty installer:

  • Updating the jetty-base tree to reflect any changes in jetty

  • Building and publishing the msi file

Updating Jetty Base

The following is for Jetty 12.x

For Jetty 12, we track the project version of jetty-base. The branch we build from is currently named 12-windows

Preparation

  • Clone and checkout the correct branch:

  • Merge (not rebase) forward to the latest changes on the 12branch

  • Update the pom to reflect the jettty and procrun versions

  • Review the 12 version of src\main\resourcs\jetty-base\start.d\idp.ini and make any required changes to src\main\resourcs\jetty-base\start.d.dist\idp-system.ini

  • Set revision to zero (f needed)

  • test build and smoke test

  • Commit the changes.

Building the Jetty Installer

Set up tag point (and tag if possible)

  • Edit pom.xml to remove SNAPSHOT from versions.

  • Tag (this may be deferred if running on a GPG deficient build machine)

  • Edit pom.xml to change the the version, adding -SNAPSHOT Make sure that there is alignment between the version and the version properties

  • Commit

Build the release version

Test the released version

Commit the Work

(this assumed that the build was done on a GPG-deficient machine)

  • Push the work done above (on the build machine)

  • Move msi to GPG machine

  • Checkout to the build point and tag

  • Clean git reposuitory and move the test msi file into target

  • Push to nexus using the gpg:sign-and-deploy-file plugin:

Push changes to git: