Installation of TFSDeployer

Dave Comfort / Scott Colestock

(Drawn from: http://notgartner.wordpress.com/2006/12/16/getting-started-with-tfs-deployer/)

 

Introduction

This document will describe the software and steps necessary to install TFSDeployer to machine(s) where builds must be deployed.

 

Background Information

TFSDeployer is a deployment tool written by the people at Readify that integrates with TFS.  It is designed to work with build quality change events that are initiated from TFS/Team Explorer. TFSDeployer has the following message flow:

 

There is more information about TFSDeployer at the following location:  http://notgartner.wordpress.com/2006/12/16/getting-started-with-tfs-deployer/

 

 

The sequence of messages exchanged is as follows:

 

  1. The Target machine has the TFSDeployer service running.  When TFSDeployer starts, it subscribes to ‘Build Quality Change’ events in TFS.
  2. The Team Explorer user decides that a particular build should be deployed to a particular environment (in this example ‘Dev’).  The user transitions the build quality indicator for that build from ‘Unexamined’ to ‘In Dev’.

 

 

 

  1. The build quality event is delivered to the TFS Event System.
  2. The TFS Event System determines which subscribers should receive the event, and delivers it accordingly via WCF.
  3. Upon receiving the build quality change event on the Target machine, the TFSDeployer service will:
    1. Retrieve DeploymentMappings.xml and determine if ‘this’ server should respond to the build quality event delivered.
    2. If it should respond, TFSDeployer will download the Power Shell script specified in the DeploymentMappings.xml file, and any other files stored in this well known TFS Version Control location.
  4. If TFSDeployer should respond to the build quality event, it will create a Power Shell instance and run the Power Shell script downloaded in the prior step.  The Power Shell script will deploy the solution to the Target machine.

 

 

 

Creating Deployment Mappings

 

DeploymentMappings.xml

This file provides TFSDeployer the information about what type of build quality change events the Target machines should respond to.  This file must be checked into a ‘well known’ location in TFS version control.  The location should be in a ‘Deployment’ sub-directory under each Team Build Type directory. For example, in the screenshot below we have a Team Build Type called CrmOnTimeContinuous which is part of the CrmOnTime team project, so the path that TFS Deployer will look for its configuration/scripts is $/CrmOnTime/TeamBuildTypes/CrmOnTimeContinuous/Deployment.  (Obviously, TFSDeployer is handed some information about the build type name when it receives the build quality change event.)

http://notgartner.files.wordpress.com/2006/12/windowslivewritergettingstartedwithtfsdeployer-7ebfimage0131.png

There should be one ‘Mapping’ element for each build quality transition for each Target server.  Below is an example:

 

 

In this example we have four mappings.  Each mapping has the same settings except for the ‘Computer’ attribute.  This means that the ‘DeploytoBizTalkServer.ps1’ script will be run on both devbiztalkserver1 and devbiztalkserver2 when the build quality setting for the build transitions from ‘Unexamined’ to ‘In Dev’.

 

Installing TFSDeployer on a Target machine

1. Install TFSDeployer

  1. Copy TFSDeployerSetup.msi (http://notgartner.com/downloads/tfsdeployersetup.msi) to some directory on the Target machine. 
  2. Run TFSDeployerSetup.msi.
  3. Update the exe with http://notgartner.com/Downloads/TfsDeployer.exe.
  4. Run “TFSDeployer.exe –i” to install the service itself.
  5. Edit TFSDeployer.exe.config in C:\Program Files\TFS Deployer.

 

This is the basic configuration file used by TFSDeployer.  It must be edited to provide information about the Target machine, email URLs, etc.  Below is a description of which parameters must be edited:

 

·        \Configuration\ApplicationSettings\TfsDeployer.Properties.Settings\setting name=”ToAddress”

This setting is the ‘default’ email address that will be used when deployments are completed (either successfully or not).  This email address will only be used if there is no ‘NotificationAddress’ element in the DeploymentMappings.xml file for any particular mapping.  In setting this value you should ask the question:  “Who should know about deployments on this machine if there is no ‘NotificationAddress’ element for a particular mapping”.

 

·        \Configuration\ApplicationSettings\Readify.Useful.TeamFoundation.Common.Properties.Settings\setting name=”BaseAddress”

This is the address that Team Foundation Server will use to publish build quality change events to the TFSDeployer service running on this Target machine. The address specified should be addressable from across the network so using ‘localhost’ is not acceptable.

 

·        \Configuration\ApplicationSettings\Readify.Useful.TeamFoundation.Common.Properties.Settings\setting name=”RegistrationUserName”

This is the name of the account that the service process is running under and which the subscriptions will be assigned to in Team Foundation Server.  See below for the permission requirements for this account.

 

·        \Configuration\ApplicationSettings\Readify.Useful.TeamFoundation.Common.Properties.Settings\setting name=”TeamFoundationServerUrl”

This is the address at which TFS is addressable across the network.  This is the URL that TFSDeployer will use to create a ‘build change event’ subscription in TFS and download files (DeploymentMappings.xml, etc) from.

 

·        \Configuration\ApplicationSettings\Readify.Useful.TeamFoundation.Common.Properties.Settings\setting name=”UseDefaultCredentials”

Should always be set ‘True’, unless you are using TFSDeployer in a cross domain configuration.

 

·        \Configuration\UserSettings\ TfsDeployer.Properties.Settings \setting name=”FromAddress”

This is the address that all deployment notification e-mails are sent from.

 

·        \Configuration\UserSettings\ TfsDeployer.Properties.Settings \setting name=”SmtpServer”

This is the address of the SMTP server used to send deployment notification e-mails.

2. Establishing Service Account

The account that the TFSDeployer service runs under must have permissions to:

 

    1. Subscribe to TFS Build Quality Change events.  Use the TFS Project Security to set this up.

(The account needs to be a member of the ‘TFS Administrators’ group.)

    1. Retrieve content from TFS Version Control.  Use the TFS Project Security to set this up.

 

 

 

    1. Deploy the build on the Target machine.  The Power Shell instance that TFSDeployer creates will inherit the identity of the TFSDeployer Service.  So this account will need all the permissions necessary to deploy the build.  For BizTalk installations the account must have the following permissions on the Target machine:

                                                               i.      Must be a member of the (domain-level) BizTalk Server Administrators group.

                                                             ii.      Must be a member of the (domain-level) SSO Administrators group.

                                                            iii.      Must be a local admin on the box or have sufficient permissions such that environment variables can be read from the powershell script.

                                                           iv.      Must be able to create a WCF endpoint.  If account permissions don’t already provide for this implicitly, this will be possible if permissions are granted to this account via the HttpConfig.exe program.

1.      Start the HttpConfig.exe program (see http://www.stevestechspot.com/downloads/httpconfig.zip)

2.      Press the ‘Add’ button.

3.      Enter   http://+:8999/+/       for the URL.

 

 

4.      Add the account to the permissible accounts (make sure ‘Register’ is Allowed):

 

 

 

 

3. Install .Net 3.0 on Target machine

TFSDeployer uses WCF to create an endpoint that will be used by the TFS Event System to deliver events to TFSDeployer.   Download here.

4. Install Power Shell on Target machine

a. TFSDeployer will create Power Shell instances.  Install the latest version for the OS you are deploying to.  Download here.

 

b. Start a Power Shell instance and type the following command (do for both 32-bit and 64-bit):   

 

set-executionpolicy remotesigned

 

5. Configure and Start  the TFSDeployer Service

 

    1. Change the service’s ‘LogOn’ account to be the account set up in Step 2 above, via services.msc.
    2. Verify that the ‘StartupType’ is ‘Automatic’.
    3. Start the TFSDeployer service.

 

Troubleshooting:

 

1)      Try stopping the TFSDeployer service, going to the command line, and running “TFSDeployer.exe –d”.  This will give you feedback as to whether the service is successfully subscribing to TFS events and receiving the notifications.  You likely want to run the command line via “runas” and specify the service credentials you are typically using.

2)      Your Powershell script will be receiving the build number and drop location from TFSDeployer.  If you structure your script as follows, you can launch it directly from the Powershell command line (with command line arguments) to help troubleshoot it:

$buildNumber = $TfsDeployerBuildData.BuildNumber

$dropLocation = $TfsDeployerBuildData.DropLocation

if($buildNumber -eq $null)

{

  $buildNumber = $args[0]

  $dropLocation = $args[1]

}

 

If the service fails to execute your script, you can change to a directory similar to this one - this is where the service does the “get” of your deployment mappings and script:

 

C:\Documents and Settings\tfsdeployer_svc\Local Settings\Temp\TFSDeployerConfiguration2

 

In this location you will be able to launch your powershell script directly and supply the required command line arguments.