salt-windows-msi

Windows MSI installer build toolkit

• The 'nsis/' directory contains an NSIS-based setup project.
• The 'wix/' directory (and wix.sln) produce .msi and .exe setup projects implemented using WiX.

Builds for both projects are semi-automated using an MSBuild project in this directory.

##General Requirements##

• A recent version of MSBuild. The one included with the .NET Framework v4 works fine.
• NuGet, to restore dependencies. Download from http://nuget.org and place in ./.nuget relative to this directory.
• WiX v3.9.
• MSBuild Community Tasks Unzip task (restored by NuGet).
• MSBuild Community Tasks WebDownload task (restored by NuGet).

##NSIS Installer##

###Components###

• common/buildenv/: Static Minion package content
• dist.$(TargetPlatform)/: extracted at build time from the salt distribution archive.
• common/targets/: MSBuild targets files used during the build.
  • Minion.Common.targets: contains targets to discover the correct distribution zip file, extract it and calculate versions based on its name.
• nsis/: Contains NSIS project files
  • Salt-Minion-Setup.nsi: NSIS project file

###Building###

From the command line:

msbuild msbuild.proj /t:nsis /p:NuGet=/path/to/nuget.exe [ /p:property=value [ /p:... ] ]

See the msbuild section for details on available targets and properties.

The project can also be built using the 'makensis.exe' utility directly. To do so, use one or more of the following command line defines:

• BUILDENV: path to the buildenv/ directory. Defaults to '..\common\buildenv'.
• DISTFILES: path to the extracted distribution files. The default assumes the distfiles are extracted into ${BUILDENV} (i.e. there is no default).
• PRODUCT_VERSION: the version being built. Defaults to '{{ salt_version }}'.
• TARGET_PLATFORM: win32 or amd64. Defaults to $%PROCESSOR_ARCHITEW6432%.

The build will produce $(StagingDir)/nsis/Salt-Minion-$(DisplayVersion)-$(TargetPlatform)-Setup.exe.

##WiX/MSI Installer##

###Components###

• common/buildenv/: Static Minion package content
• dist.$(TargetPlatform): extracted at build time from the appropriate frozen Minion distribution archive.
• common/targets/: MSBuild targets files used by the WiX projects.
  • BuildDistFragment.targets: contains msbuild targets to generate a WiX fragment from the extracted distribution.
  • DownloadVCRedist.targets: contains msbuild targets to download the appropriate Visual C++ redistributable for the WiX Bundle build.
  • Minion.Common.targets: contains targets to discover the correct distribution zip file, extract it and calculate versions based on its name.
• wix.sln: Visual Studio solution file. Requires VS2010 or above. See note above about dependencies.
• wix/MinionConfigurationExtension/: A WiX Extension implementing custom actions for configuration manipulation.
• wix/MinionMSI/: This is the WiX .msi project
  • buildenv.wxs: WiX fragment describing the contents of the buildenv/ folder.
  • dist-$(TargetPlatform).wxs: WiX fragment describing the contents of the distribution zip file. This is autogenerated and added to the compile at build time; it does not show up in the Visual Studio solution.
  • SettingsCustomizationDlg.wxs: A custom MSI dialog for the master/minion id properties.
  • MinionMSI.wixproj: the main project file.
  • MinionConfigurationExtensionCA.wxs: A WiX fragment setting up the configuration manipulator custom actions.
  • Product.wxs: contains the main MSI description and event sequence
  • service.wxs: contains a WiX component for nssm.exe and the associated Windows Service description/control settings.
  • WixUI_Minion.wxs: WiX fragment describing the UI for the setup.
  • Banner.jpg: Used as the top bar banner in most of the UI dialogs.
  • Dialog.jpg: Used as the dialog background for Welcome and Exit dialogs.
• wix/MinionEXE/: This is the WiX bundle .exe project
  • Bundle.wxs: contains the bundle description and package chain

###Building###

From the command line:

msbuild msbuild.proj /t:wix /p:NuGet=/path/to/nuget.exe [ /p:property=value [ /p:... ] ]

See the msbuild section for details on available targets and properties.

The solution can also be built in Visual Studio, but the embedded defaults for version, paths, etc. may be incorrect on your machie.

The build will produce:

• $(StagingDir)/wix/Salt-Minion-$(DisplayVersion)-$(TargetPlatform)-Setup.msi
• $(StagingDir)/wix/Salt-Minion-$(DisplayVersion)-$(TargetPlatform)-Setup.exe

###Differences vs. NSIS installer###

This WiX project mimics the NSIS installer as much as possible, with the following exceptions:

• Allows installation to any directory.
• Supports unattended installation.
• The .msi does not download or install the VC++ redistributable. The .exe does, but the UI experience is very different.
• The .msi UI does not display files as they are copied, only a status bar.

There are some additional benefits provided via msiexec:

• A problem during the .msi install will be rolled back automatically.
• .msi offers much better built-in logging (/l option to msiexec).

###Unattended install###

It is possible to install a Salt Minion unattended while still providing customized values for the master hostname, minion id, installation path, etc. using the following command line:

msiexec /i Salt-Minion-$version-$platform.msi /qn [ PROPERTY=VALUE [ .. PROPERTY=VALUE ] ]

Since the .msi does not install the Visual C++ redistributable, it must be installed separately.

Available properties:

• INSTALLFOLDER: Where to install the files. Default is 'c:\salt'.
• MASTER_HOSTNAME: The master hostname. The default is 'salt'.
• MINION_HOSTNAME: The minion id. The default is '%COMPUTERNAME%'.
• START_MINION_SERVICE: Whether to start the salt-minion service after installation. The default is false.

###Extending###

Additional configuration manipulations may be able to use the existing MinionConfigurationExtension project. Current manipulations read the value of a particular property (e.g. MASTER_HOSTNAME) and apply to the existing configuration file using a regular expression replace. Each new manipulation will require changes to the following files:

• MinionConfiguration.cs: a new method (i.e. new custom action).
• MinionConfigurationExtensionCA.wxs: a <CustomAction /> entry to make the new method available.
• Product.wxs: a <Custom /> entry in the <InstallSequence /> to make the configuration change.
• Product.wxs: a <Property /> entry containing a default for the manipulated configuration setting.
• README.md: alter this file to explain the new configuration option and log the property name.

If the new custom action should be exposed to the UI, additional changes are required:

• SettingsCustomizatonDlg.wxs: There is room to add 1-2 more properties to this dialog.
• WixUI_Minion.wxs: A <ProgressText /> entry providing a brief description of what the new action is doing.

If the new custom action requires its own dialog, these additional changes are required:

• The new dialog file.
• WixUI_Minion.wxs: <Publish /> entries hooking up the dialog buttons to other dialogs. Other dialogs will also have to be adjusted to maintain correct sequencing.
• MinionMSI.wixproj: The new dialog must be added as a <Compile /> item to be included in the build.

##MSBuild##

Both sets of projects can be build from the command line using the included msbuild project.

General command line:

msbuild msbuild.proj [/t:target[,target2,..]] [/p:property=value [ .. /p:... ] ]

A 'help' target is available which prints out all the targets, customizable properties, and the current value of those properties:

msbuild msbuild.proj /t:help

##Suggested Improvements##

• Have the WiX setup detect and uninstall existing NSIS installations (and vice-versa).
• Add other configuration manipulations.
• Write new configuration to minion.d instead of editing the distributed minion config.
• Develop a custom bootstrapper application to replace the default WiX bootstrapper, and move the UI from the .msi to the bundle .exe.
• Nice install dialog art.