Note:
This section discusses how the Phoenix Installer project is put together from a software developer perspective. For end-user information on how to use the Phoenix Installer, please consult the Phoenix Help Wiki.

This topic contains the following sections.

Quick Guide to Building the Installer

How the Installer Project is Put Together

This section will attempt to demystify the inner workings of the Phoenix Installer.

The installer is simply a Visual Studio Setup Project. It was added to the solution using Add > New Project and selecting the Setup and Deployment project template as illustrated below.

Figure:Adding the Setup Project

Project Outputs

The installer does not create the actual Phoenix website or database -- this is the job of the Phoenix Node Configuration Tool. As the diagram below shows, all the installer needs is the output of the Phoenix.Services project and the output of the NodeConfigTool project.

Figure:Primary Outputs required by Installer

Project outputs were added by right-clicking the installer project and selecting Add > Project Output.

Figure:Adding Primary Outputs

Custom Actions

During installation, there are some additional steps we need to take to ensure that several Phoenix components are configured properly. The PhoenixServices for example need to create some local folders, and some environment variables must be set so that MapServer will function.

This logic is found in the Phoenix.Services..::.PhoenixSearchServiceInstaller class. This class is decorated with a [RunInstaller(true)] attribute which will ensure that the Windows installer (the .msi) can see our installer code.

The code within the PhoenixSearchServiceInstaller class contains references to three ServiceInstaller classes (one for each of the three services). Each of these classes is responsible for executing the steps needed to configure the service.

The Custom Actions Editor within Visual Studio is used to wire up our installer class. Notice that all four actions Install, Commit, Rollback and Uninstall have been set to the primary output of the Phoenix.Services project even though not all events are handled in our installer class.

Figure:Project Outputs

During installation, the events occur in the order shown below.

  1. ServicesInstaller..::.Install(IDictionary)
  2. PhoenixEmailServiceInstaller..::.Install(IDictionary)
  3. PhoenixFileServiceInstaller..::.Install(IDictionary)
  4. PhoenixSearchServiceInstaller..::.Install(IDictionary)
  5. ServicesInstaller..::.Commit(IDictionary)
  6. PhoenixEmailServiceInstaller..::.Commit(IDictionary)
  7. PhoenixFileServiceInstaller..::.Commit(IDictionary)
  8. PhoenixSearchServiceInstaller..::.Commit(IDictionary)
Note:
The Windows installer does not start firing events until the user has clicked on the final confirmation button.

Back to Top

Building the Phoenix Installer

Although the installer project itself is quite simple, care must be taken to ensure that it is built properly. The installer project is simply a container for other components that it has been charged to deploy. It is getting the parts properly built that is the trick.

The installer is dependant on the output of two projects: Phoenix.Services and NodeConfigTool. Both must be built prior to building the installer.

Important Note:
In Visual Studio, pressing F6 or Ctrl+Shift+B is not enough to force all installer dependancies to build. The solution file has been configured not to build the NodeConfigTool project in Release mode. This is due to the additional (and potentially time-consuming) build events that occur when this project is built. You must manually build the NodeConfigTool project prior to building the installer.
The illustrations below show the order that projects are built.

Back to Top

A Step by Step Guide

This section will show you how to properly build the Phoenix Installer.

1. Set Active Configuration

Before building the installer make sure the solution's active configuration is set to "Release" mode. The installer cannot be build in "Debug" mode as some components are hard-coded to look in the release folder for required elements.

Figure:Select 'Release' mode

2. Pre-compile the Web Project

Tip:
This step is a prerequisite for the NodeConfigTool. You are only required to perform this step if there have been changes to the web application or phoenix class libraries.

The Phoenix web application must first be pre-compiled.

To pre-compile the web project we use a Web Deployment Project. This project takes both the content (markup) and the code (C#) for each page, parses it, compiles it, and merges it into a single assembly. The resulting web-application, will be easier to deploy, run faster, and be more secure.

Figure:Pre-compiling the Web Project

3. Concatenate the Database scripts

Tip:
This step is a prerequisite for the NodeConfigTool. You are only required to perform this step if there have been changes to any of the database script (.sql) files.

The numerous database scripts must be concatenated together.

The easiest way to concatenate the database scripts is to execute the batch file joinscripts.bat which can be found in the Phoenix.Database project in the Deployment subfolder.

Caution:

Please review the joinscripts.bat file before executing it. In particular, you need to set the two variables: output and installscripts.

Variable Description
output The folder that the sql scripts will be concatenated to. This value is relative to the current path (the path the script is run from). Example: set output=V2.9 Create
installscripts The folder where the NodeConfigTool will see them. This path is relative to the 'output' path. Normally it's value of ..\..\..\Installer\NodeConfigTool\Scripts should not change.

3.1. Open a Command Line

3.2. Change your current directory to the folder that contains the batch script.

3.3. Type joinscripts

The sql scripts will be joined and copied into the configured locations. Note that three script files were created.

  • 2functions.sql -- contains all the User Defined Functions
  • 3views.sql -- contains all Views
  • 4sprocs.sql -- contains all Stored Procedures (sprocs)

4. Build the NodeConfigTool tool

Recall that the NodeConfigTool is the application that creates and configures individual Phoenix nodes. In order to do this, it must contain the latest binaries of the Phoenix web application as well as the database scripts, so they can be deployed any time the tool is executed. Therefore, some additional steps must be taken prior to building NodeConfigTool.

To ensure that these steps have been taken, the NodeConfigTool project contains a Pre-Build Event which Visual Studio will execute before the project is actually compiled. To view or edit the Build events, right-click the project and select properties. Click on the Build Events tab.

Figure:Reviewing the NodeConfigTool Build Events

The pre-build event is configured to run a console application called prebuild.exe. It is the job of prebuild to sanitize and compress the files in the web application folder, as well as the database scripts.

Review the prebuild topic for more information.

Build the NodeConfigTool project as you normally would.

5. Build the Installer

You are now ready to build the installer.

Highlight the Phoenix.Installer project and select build.

Figure:Building the Installer

If there were no errors, you should have an installer application in the output folder. D:\projects\pathways\phoenix\trunk\Installer\Release, for example.

Installer Data Flow

See Also