Deploy to Sitecore website using TeamCity with Web Deploy 4.0 (or SMB)

In this blog post, I will explain how I setup TeamCity to build and deploy my Sitecore Visual Studio solution to my Sitecore website using Microsoft Web Deploy 4.0 or SMB.  Off the bat, I want to callout that, to use Web Deploy, you will need to open ports 80 and 8172 from the TeamCity server(s) to the destination server(s).  If this is not an option for you, I provide an alternative solution using SMB which requires UNC access from the TeamCity server(s) to the destination server(s).  I recommend using Web Deploy because, to me, it seems like a more robust and “proper” solution but in all honesty, the SMB option works just as well.

Open ports between servers for Web Deploy

As I mentioned above, you need to make sure that ports 80 and 8172 are open between the server(s) that will run TeamCity and the server(s) to which you’ll be deploying.  We’ll be installing two Windows Services on all servers that will require that these ports be open.

I’m mentioning this now because you may need to reach out to your IT/Security Team to open firewall ports and that could take some time.  If this is the case for you, stop reading this blog post, open Outlook, create a new email to the appropriate people at your company/client and ask them to open those two ports for incoming requests from the TeamCity server(s) to the destination server(s).

You can use telnet in a Command Prompt as Administrator from within the TeamCity server(s) to test if these ports are open to your destination server(s):

telnet name-of-destination-server 80
telnet name-of-destination-server 8172

If you get a blank Command Prompt after running each command above, that means the ports were open and you were able to connect.  If you get an error message, you can try substituting the server name with the IP address of the server.

Open ports between servers for SMB

If you can’t have ports 80 and 8172 open, another option is to use the SMB (Server Message Block) protocol.  This option manifests itself in TeamCity as a UNC connection.  In other words – you use the UNC path from your TeamCity server(s) to the destination server(s).  To test this, open File Explorer and try going to a folder on one of the destination servers:

\\name-of-destination-server\c$\inetpub\wwwroot\name-of-website\Website

If you’re able to connect, SMB (UNC) is working from your TeamCity server(s) to your destination server(s).  In my experience, most server environments allow for this type of access even from a server behind the firewall to a server in the DMZ.  Maybe I’ve just been lucky.

If you think you’re getting blocked when trying UNC, you can try substituting the server name with the IP address of the server.  If that still doesn’t work, here are some ports you can ask your IT/Security Team to open:

  1. TCP Port 445
  2. TCP Port 137
  3. TCP Port 139
  4. UDP Port 137
  5. UDP Port 138

Source: https://www.serverintellect.com/support/windowsserver/server-to-server-file-transfer-using-unc-pathing/

Install TeamCity

Now that you’ve confirmed you can deploy from the TeamCity server(s) to the destination server(s) using either Web Deploy or SMB, you need to install the latest version of TeamCity, which, at the time of writing was version 2017.2.4 (build 51228) – https://www.jetbrains.com/teamcity/download/.

You can choose whatever options you want while installing TeamCity but I recommend the following:

  • set the port to 8080
  • set the TeamCity data directory to c:\TeamCityData
  • run the TeamCity Server and Build Agent under the SYSTEM account
  • setup an external database for TeamCity
    • I’ve seen TeamCity completely die after some time running with the built-in database provider so beware!

Install IIS Management Service (Web Management Service)

This section only applies if you’re using Web Deploy.  If you are using SMB, skip this section and go down to the Setup TeamCity Build Configuration section.

Any servers to which you’ll be deploying from TeamCity will need the IIS Management Service (aka Web Management Service).  On Windows Server 2016, this is a feature of IIS that you need to enable.  To enable this feature:

  1. open Server Manager
  2. in the top right, click Manage
  3. click Add Roles and Features
  4. on the Before you begin screen, click Next
    1. if you don’t see this screen first, just move on to the next step.
  5. on the Select installation type screen, select Role-based or feature-based installation and click Next
  6. on the Select destination server screen, select Select a server from the server pool, highlight the server in the Server Pool table below and click Next.
  7. on the Select server roles screen, select Web Server (IIS).
    1. if this is your first time enabling the IIS feature on this server, the Add features that are required for Web Server (IIS) window will display.
      1. check off the box for Include management tools (if applicable) and click Add Features.
  8. back on the Select server roles screen, click Next.
  9. on the Select features screen, click Next.
  10. on the Web Server Role (IIS) screen, click Next.
  11. on the Select role services screen, check the box next to Management Service (under Management Tools)
  12. click Next.
    1. if you have not yet installed ASP.NET 4.6 or higher, the Add features that are required for Management Service? screen will display.
      1. check off the box for Include management tools (if applicable) and click Add Features.
  13. back on the Select role services screen, click Next.
  14. on the Confirm installation selections, click Install.
  15. click Close.
  16. Once the installer completes
    1. open the Services management console and make sure the Web Management Service is set to Automatic and is running.

TeamCity will need Web development build tools which you can install using the Visual Studio Installer.  This installer will install all of the web targets TeamCity will need to be able to build and deploy a ASP.NET web application.  This installer will also install Web Deploy 4.0.

  1. Download and run Build Tools for Visual Studio 2017 – https://www.visualstudio.com/downloads/#build-tools-for-visual-studio-2017
  2. Check the box next to Web development build tools
  3. Click Install in the bottom right

After you complete the above steps, you have to update the installation of Microsoft Web Deploy 4.0 to include all features:

  1. open the Windows menu and search for Add or remove programs
  2. click on Microsoft Web Deploy 4.0
  3. click Modify
  4. click Next
  5. click Change
  6. click the dropdown button to the left of Web Deployment Framework
  7. click on Entire feature will be installed on local hard drive
  8. click Next
  9. click Change
  10. click Finish
  11. open the Services management console and make sure the Web Deployment Agent Service is set it to Automatic and is running.

Visual Studio Publishing Profiles (only required for Web Deploy)

This section only applies if you’re using Web Deploy.  If you are using SMB, skip this section and go down to the Setup TeamCity Build Configuration section.

Now that we’ve got the required software installed on our services, we need to configure publishing profiles in Visual Studio for each server to which we want to deploy from TeamCity.  Web Deploy will use these publish profiles to deploy the build artifacts that TeamCity generates.

  1. open your solution in Visual Studio
  2. click the Edit Publish Profiles button
    edit publish profiles

    1. if you don’t see this button, make sure you’ve enabled the Web One Click Publish chunk
  3. click New Profile…
  4. select IIS, FTP, etc
  5. click Create Profile
  6. on the Publish window
    1. for Publish method, select Web Deploy
    2. in the Server field, enter the URL to the server
      1. this needs to be a URL that works over HTTP or UNC from within the TeamCity server to the destination server
    3. in the Site name field, enter the name of the IIS website
    4. in the User name and Password fields, enter the information for an account that has administrative privileges on the destination server
    5. Save password is optional.  I decided not to save my password in my publishing profile and instead, I enter it in TeamCity, which I’ll explain below.
    6. Destination URL is optional as well.
    7. Click Validate Connection
      1. if you get errors, the likely causes are either ports are not open or services are not started on the target machines
    8. Click Save.

Make sure to commit the

You’re going to setup one publishing profile for each server to which you want to deploy from TeamCity.

Setup TeamCity Build Configuration

At this point, you should have:

  1. TeamCity installed
  2. decided which approach you’re going to use – Web Deploy or SMB – and ensured the proper ports are open for whichever approach you select
  3. if you’re using Web Deploy, you should have
    1. installed required services
    2. setup your publishing profiles

Initial Steps (applies to Web Deploy and SMB)

You need to complete the following steps regardless of which approach you follow:

  1. login to TeamCity
  2. click Create project
  3. pick whichever source control option you’re using
  4. on the Create Project From URL page, enter a Project name and a Build configuration name

You should now be brought to the page for the Build you created in the previous step.  TeamCity will scan the repository and auto-detect build steps for you.  You can just cancel this process – we are going to create a build step ourselves based on our requirements.

  1. In the left, click on Build Steps
  2. click Add build step
  3. in the Runner type dropdown, select Visual Studio (sln)
  4. enter a Step name (optional)
  5. in the Solution file path, you can use the tree icon button to the right to either select your solution file or your web application CSPROJ file.
    1. I prefer selecting the CSPROJ file because it could reduce the build time if there are projects in the solution that I don’t need to build for this scenario.
  6. in the Visual Studio dropdown, select the version of Visual Studio you are using for development
    1. if you installed the Build Tools for Visual Studio 2017 as I suggested above, you should select MS VS 2017 in this dropdown.
  7. for Targets, I recommend Rebuild but you can enter just Build if you’d prefer
  8. for Configuration, enter the configuration you want to use such as DebugRelease, an environment-specific configuration that performs the appropriate transforms, etc…

We’ve got a few more steps to complete the build setup but they will depend on whether you’ll be using Web Deploy or SMB.

Next Steps for Web Deploy

  1. click Show advanced options
  2. add the following lines to the Command line parameters field
    /p:DeployOnBuild=True
    /p:PublishProfile="NameOfPublishProfile"
    /p:ProfileTransformWebConfigEnabled=False
    /p:Password=**********

The above are MSBuild switches.

DeployOnBuild doesn’t actually “deploy” on build.  What it actually does is create the deployment package – a ZIP of the publishable files – DLL’s, CSHTML, configs (with transformations if you’re using SlowCheetah), CSS, JS, images, etc…

PublishProfile is pretty self-explanatory – it’s the name of the publish profile you created in Visual Studio.  The double-quotes are required.

In all honesty, I’m not 100% clear on what ProfileTransformWebConfigEnabled does but according to this, https://confluence.jetbrains.com/pages/viewpage.action?pageId=74845238, you should set it to False because, otherwise, it will affect your own config transforms.

Password is the password for the user that you entered in Visual Studio when you created the publishing profile.  If you opted to save the password in the publishing profile PUBXML file, you can leave this out in TeamCity.

Save the build step and try running it.  If you get a success message, you can further validate it worked by going to the folder on the destination server and check the datetime on some of the files that should’ve been deployed.

If you get any errors in TeamCity, go to the build log and double-check the error details.  Most errors I got were either firewall related, i.e., the required ports were not open, or, the services weren’t running on the destination servers.

Next Steps for SMB

  1. Save the current build step.
  2. Run the build with just the Visual Studio (sln) step that you setup.

We will need this step to be complete so we can review the logs and find our checkout directory which will be required in a later step below.  To determine your checkout directory:

  1. go to the Build Log for your successful build
  2. find the log entry that starts with Checkout directory
  3. save this path to Notepad or how ever else you’d like

Next, we’ll create the SMB build step:

  1. Create a new build step.
  2. in the Runner type dropdown, select SMB Upload
  3. enter a Step name (optional)
  4. enter the UNC path to the destination server, example:
    \\name-of-destination-server\c$\inetpub\wwwroot\name-of-website\Website
  5. Enter a username and password
    1. only required if you’re prompted for one when you try to access this UNC path using File Explorer
  6. In the Paths to sources field, enter the relative path to the PackageTmp folder.  Here’s how you find this:
    1. go to the Checkout directory
    2. Web application project
    3. obj
    4. name of Configuration you set in the Visual Studio (sln) build step, for example, Release
    5. Package
    6. PackageTmp

So this path would be something like:

\MyWebApplicationProject\obj\Release\Package\PackageTmp

Save the build step and try running it.  If you get a success message, you can validate that it worked by going to the folder on the destination server and checking the datetime on some of the files that should’ve been deployed.

If you get any errors in TeamCity, go to the build log and double-check the error details.  Most errors I got were either firewall related, i.e., the required ports were not open, or, the the username and password was incorrect.

Conclusion

After going through the steps above, you now have setup TeamCity to deploy your Sitecore Visual Studio solution to your Sitecore websites hosted on any server where the TeamCity server can access.

I hope this helps you!  Leave me a message if you have any questions or feedback!

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s