Guide for setting up teamcity for umbraco development

TeamCity is an awesome tool for automating builds, deploys, and tests. For each of our projects, we might have many developers/designers working away on a site. We needed a way for our dev site to stay up-to-date without someone having to manually push code. This is why we like TeamCity. We can set TeamCity up to watch our code repositories, automatically publish new changes, and run all sorts of unit tests without anyone lifting a finger.

Part 1 - Installing TeamCity on Windows Server

1. Download the latest TeamCity.

2. Install it on your build server. This guy has a great blog about it. The process is really straight forward. Some things to keep in mind are that TeamCity and IIS don't play nice together. I've had success installing TeamCity on an isolated server where IIS is not installed. If you do choose to install TeamCity on a server where IIS lives. Definitely don't go with the default port 80 for teamcity. 8080 is a solid choice. Follow the directions on the blog I referenced above. Good luck. It is definitely possible to set up TeamCity side by side with IIS, I just haven't worked through that myself yet. 

   During the installation, you will be asked to install a Build Agent. Give it a descriptive name and take note of the port that the Build Agent will be listening on. When you are asked which account the Build Agent Service should run under, select 'SYSTEM account'.

3. Once TeamCity is installed, you will be prompted to log in. You may want this UI to be accessible from a remote machine. Basically, what you need is an actual domain for your TeamCity UI. Here is how I did it.

   Find the TeamCity directory where TeamCity is installed (likely at C:\TeamCity). Open the \TeamCity\conf\server.xml file.

   Find the <Host> element and add an <Alias> under it like this:

   <Host name="localhost" appBase="webapps" unpackWARs="true" autoDeploy="true">
   <Alias>teamcity.mydomain.com</Alias>

   You should now be able to add a host file entry to a remote machine like this:

   xxx.xxx.xxx.xxx teamcity.mydomain.com

   Need more instructions on modifying your host file?

   If you have your teamcity server hosted with Azure, follow these instructions. There are additional endpoints that need to be configured.

   If you are still having problems, you may need to check your firewall settings.

Useful References:

• http://blogs.endjin.com/2010/11/a-step-by-step-guide-to-hosting-teamcity-in-iis-7/
• http://www.danmusk.com/setting-up-teamcity-8-on-an-azure-virtual-machine/

Part 2 - Installing Additional Build Agents

In the TeamCity UI, you should see an "Agents" tab on top. This is where you manage all of your Build Agents. If you just installed TeamCity, you should see only one build agent under the "Connected" tab. This is the Build Agent that you installed and configured when you installed TeamCity. The easiest way to install additional build agents is to go into the 'Administration' section and click 'Install Build Agents'. Once you have download the .msi, install it on the server where you want the Build Agent to live.

You may need to manually configure your new Build Agent. To do this, find the install location of the Build Agent (likely at C:\BuildAgent).

Open the \BuildAgent\conf\buildAgent.properties. Here, you can modify the name of your build agent as well as point it towards your teamcity server. After modifying the Build Agent this way, you will need to restart the windows service corresponding to that Build Agent for the changes to show up.

Once you think that your Build Agent is configured correctly you can log back in to your TeamCity UI and navigate to the Agent tab. Click on the Unauthorized tab. From here, you should be able to manually authorize the build agent. I've found some logs to be helpful in this authorization process at \BuildAgent\logs\teamcity-agent.log. By viewing this log file, you can determine if your build agent has run into problems (probably firewall related) or is still in the process of trying to connect to TeamCity.

Part 3 - Writing Your First Build Configuration

1. The first thing we are going to want to do is to create a Sub Project for our Build Configuration. Go to the 'Administration' Section of the TeamCity UI. Click the <Root project>

   Click the "Create subproject" button. Give your subproject a description and a name. We like to create a subproject for each of our clients. For example, ours might be called, "The Business That Builds All The Widgets"

2. At this point, you can create a Build Configuration under your subproject. I usually like to go one level deeper. I might create another subproject called, "Umbraco CMS". I like to do this because I might end up building a separate website for "The Business That Builds All The Widgets". Structure your Sub Projects so that they make sense to you.

3. Now click "Create build configuration". I'd give it a name like, "Dev" or "Staging".

4. Click "VCS settings >>" This is the area where you can let your Build Configuration know about any Source Control repos you might have. Follow the steps. Make sure the VCS is assigned to your build configuration.

5. Click "Add build step >>". This is where you tell your build agent to do work. Select a runner type. I'm going to choose "MSBuild" for the sake of example. Once you have created a build step, your Build Configuration is considered valid and is created, and you should see a sidebar on the right where you can adjust various aspects of the Build Configuration.

6. Click "Build Triggers". You use build triggers to trigger builds when a specific action occurs. Add a VCS trigger to trigger a build when new code is checked in to source control.

Part 4 - Using Web Deploy to Deploy to a Remote Server

1. This is a great blog about how to install Web Deploy. The short story is that you can use the Microsoft Web Platform Installer to install the Web Deployment Tool. Remember not to just install Web Deploy 3.5 with the recommended settings. You probably want to do the custom install and make sure that the Management Service Delegation is installed. If you forget, you can change the installation in Control Panel.

2. Once Web Deploy is installed, make sure that the Web Deployment Agent Service is installed and running.

3. Now that your web server has the Web Deployment Agent Service running, you can configure TeamCity to use WebDeploy to deploy your site. Go to your Build Configuration and make sure there is a step with a runner type of MSBuild. Add the following Command line parameters:

   /p:VisualStudioVersion=11.0
   /p:Configuration=Release
   /p:DeployOnBuild=True
   /p:DeployTarget=MSDeployPublish
   /p:MsDeployServiceUrl=DevWebServer/MsDeployAgentService
   /p:AllowUntrustedCertificate=True
   /p:MSDeployPublishMethod=RemoteAgent
   /p:CreatePackageOnPublish=True
   /p:DeployIisAppPath=MySite
   /p:IgnoreDeployManagedRuntimeVersion=True
   /p:FilesToIncludeForPublish=AllFilesInProjectFolder
   /p:SkipExtraFilesOnServer=True
   /p:ExcludeFoldersFromDeployment="App_Data\Logs;App_Data\preview"
   /p:IncludeSetAclProviderOnDestination=False
   /p:AutoParameterizationWebConfigConnectionStrings=False
   /p:AuthType=NTML /p:Username=

   Using "/p:AuthType=NTML /p:Username=" will cause webdeploy to use Windows Authentication. If you want to use an IIS User's username and password, see this link about Web Deploy Error Codes or maybe this link. I haven't had any success with the second method yet.

Useful References:

• http://weblogs.asp.net/scottgu/archive/2010/09/13/automating-deployment-with-microsoft-web-deploy.aspx
• http://www.yaplex.com/deployment/teamcity-deployment-using-msbuild-and-web-deploy-using-windows-authentication/
• http://www.troyhunt.com/2010/11/you-deploying-it-wrong-teamcity_24.html
• http://forums.iis.net/t/1180199.aspx
• http://www.asp.net/web-forms/tutorials/deployment/configuring-server-environments-for-web-deployment/choosing-the-right-approach-to-web-deployment
• http://blogs.iis.net/krolson/archive/2009/11/04/using-iis-manager-accounts-for-web-deployment-tool-msdeploy-delegation.aspx

If any of this isn't working for you, shoot me a comment. This blog post will probably turn out to be a living document that I will have to update periodically as I find better ways to use TeamCity.