BuildMaster Documentation

Manual Installation

Note: The following manual installation instructions for BuildMaster is for informational purposes only and is not fully supported. Please visit the Download page to download the installer.

The manual installation packages can be found on the All Versions page.

BuildMaster consists of four main deployable components:

  • Web Application – the primary interface to BuildMaster
  • Service – running aside the web application, the BuildMaster Service is a Windows Service that performs tasks requested through the Web Application
  • Database – a SQL Server database which stores the state and history
  • Agent – a light-weight application installed on servers used by BuildMaster to manage and orchestrate the servers (may be installed as a Windows service or hosted through IIS)

Prior to installation of BuildMaster or a BuildMaster Agent, a BuildMaster "home" directory needs to be created. We recommend C:\BuildMaster (or a similarly rooted path) because a number of 3rd-party tools that BuildMaster integrates with have issues with very long path names. Replace any instances of {BuildMaster.RootDir} in the following documentation with the actual path you have selected.

BuildMaster's Identity

BuildMaster may be configured to use its own domain account or may run as NETWORK SERVICE or LOCAL SYSTEM. While not required, administrator-level privileges are strongly recommended as it will eliminate any difficulty or confusion with moving files and running different actions.

BuildMaster's Encryption Key

In order to store sensitive data, such as resource credentials, a 32-character hex string is used for AES encryption. You can generate this however you'd like, including by clicking here, and copying the resulting JavaScript-generated pseudorandom string.

Take note of this encryption key; if you do not set one, then sensitive data will be stored unencrypted.

Database Installation

  1. Create a database named BuildMaster on any SQL Server database server (see Supported SQL Server editions for more information.)
  2. Unzip BuildMaster-DbChangeScripts.zip into any directory and run the executable with the following arguments:

    bmdbupdate.exe Update /conn=[connection string] /init=yes

  3. Take note of the connection string used in this step

Web Application Installation

  1. Create a web root directory (e.g. WebApp) in {BuildMaster.RootDir}, which will be referred to as {BuildMaster.WebApp.RootDir} for the remainder of these instructions
  2. Unzip BuildMaster-WebApp.zip into {BuildMaster.WebApp.RootDir}
  3. Create a directory which will be used for website background operations (e.g. _WEBTEMP) in {BuildMaster.RootDir}
  4. Edit Web_appSettings.config to ensure two settings:
    • Core.DbConnectionString - the same one entered into the database installation earlier
    • Core.BaseWorkingDirectory - should be the same as {BuildMaster.RootDir}\_WEBTEMP
    • Persistence.EncryptionKey - the same encryption key generated earlier

    Note: Make sure to double-check that the values of these configuration settings are correct!

  5. Create an application pool in IIS to run under the appropriate identity; for IIS7 and later, a classic (non-integrated) pipeline should be used.
  6. Create a website that points to {BuildMaster.WebApp.RootDir} using whichever host name configuration or ports preferred. Note: A virtual directory is not supported at this time. Verify that the website is configured for ASP.NET 4.0

Service Installation

  1. Create a service root directory (e.g. Service) under {BuildMaster.RootDir}, which will be referred to as {BuildMaster.Service.RootDir} for the remainder of these instructions
  2. Unzip BuildMaster-Service.zip into {BuildMaster.Service.RootDir}
  3. Create a directory which will be used for service operations (e.g. _SVCTEMP) in {BuildMaster.Service.RootDir}
  4. Edit App_appSettings.config to ensure two settings:
    • Core.DbConnectionString - the same one entered into the database installation earlier
    • Core.BaseWorkingDirectory - should be the same as {BuildMaster.RootDir}\_SVCTEMP
    • Persistence.EncryptionKey - the same encryption key generated earlier

    Note: Make sure to double-check that the values of these configuration settings are correct!

  5. Install the Windows service by running the following command from an elevated command prompt or PowerShell session in {BuildMaster.Service.RootDir}:

    bmservice.exe install

Extensions

  1. Create a directory to store extensions (i.e. Extensions) under {BuildMaster.RootDir}, which will be referred to as {BuildMaster.Extensions.RootDir} for the remainder of these instructions
  2. Unzip the 4 included extensions in BuildMaster-Extensions.zip into {BuildMaster.Extensions.RootDir}
  3. Additional extensions downloaded from within BuildMaster will be stored in {BuildMaster.Extensions.RootDir}, and you may also download extensions manually from: the extensions overview page

Manual Agent Installation

Note: agents should be installed on remote servers that BuildMaster will orchestrate or deploy to, and are not required to be installed on the BuildMaster server itself.

Note: the agent version you download MUST be the same version as the BuildMaster software. Do not attempt to install a newer agent version, or the BuildMaster software will report errors when attempting to connect to the agent. Older agents (provided the major version number is the same) will automatically be upgraded to the same version as the BuildMaster software.

Agent Option #1: TCP Remote Agent Service

  1. Create an agent service root directory (e.g. Agent) under {BuildMaster.RootDir}, which will be referred to as {BuildMaster.TcpAgent.RootDir} for the remainder of these instructions
  2. Unzip BuildMaster-Agent-Standalone.zip into {BuildMaster.TcpAgent.RootDir}
  3. Create a directory which will be used for agent operations (e.g. _AGTTEMP) in {BuildMaster.TcpAgent.RootDir}
  4. Edit app_appSettings.config and ensure the following settings:
    • Core.BaseWorkingDirectory - points to a temporary directory, unique per agent
    • Agent.AgentExtensionsPath - a path where the BuildMaster extensions will be stored, unique per agent
    • Agent.Port - the port used to access the agent, should be unique for the system, and accessible for inbound connections (i.e. firewall disabled) for BuildMaster to be able to communicate with it
    • Agent.ServiceName - the name of the Windows service this agent will run under, unique per agent

    Note: Make sure to double-check that the values of these configuration settings are correct!

  5. Install the TCP agent's Windows service by running the following command from an elevated command prompt or PowerShell session in {BuildMaster.TcpAgent.RootDir}:

    bmtcpagent.exe install

Agent Option #2: IIS Remote Agent Servers

  1. Create a home directory for the agent web application (e.g. Agent) in {BuildMaster.RootDir}, which will be referred to as {BuildMaster.IisAgent.RootDir} for the remainder of these instructions
  2. Unzip BuildMaster-Agent.zip into {BuildMaster.IisAgent.RootDir}
  3. Create a directory which will be used for agent operations (e.g. _AGTTEMP) in {BuildMaster.IisAgent.RootDir}
  4. Edit Web_appSettings.config to ensure one setting:
    • Core.BaseWorkingDirectory - points to a temporary directory, unique per agent
    • Agent.AgentExtensionsPath - a path where the BuildMaster extensions will be stored, unique per agent

    Note: Make sure to double-check that the values of these configuration settings are correct!

  5. Create an application pool in IIS to run under the appropriate identity; for IIS7 and later, a classic (non-integrated) pipeline should be used
  6. Create a website with a Home Directory of {BuildMaster.IisAgent.RootDir} using whichever host name configuration or ports preferred.

    Note: A virtual directory is not supported at this time. Verify that the website is configured to support ASP.NET 4.0 applications.