Build Extensions Whitepaper This document details the process of implementing automated deployments for a Sitecore project. It focuses on how Team Development for Sitecore (TDS) and Razl can be used to automate certain steps of the deployment to streamline the deployment process. Although this document is focused on TDS and Razl the solutions also makes use of freely available open source tools such as Sitecore SIM and Sitecore Ship. This document will guide you through the different steps you will need to perform in order to setup an automated deployment. Though TeamCity is used as the example build server however TeamCity is not a prerequisite and the steps detailed can easily be reproduced on any build server. After reading this document you should have an good understanding of the steps, processes and methodologies involved in setting up automated deployments.

Contents Introduction .................................................................................................................................... 1 What and Why? .............................................................................................................................. 2 Implementing .................................................................................................................................. 3 Code Deployment ....................................................................................................................... 3 Code Deployment with Content Update .................................................................................... 6 Clean Deployment with Full Live Content Copy ....................................................................... 10 Package Deployment using Sitecore Ship ................................................................................. 16 Going Further ................................................................................................................................ 21 Deployment Setup .................................................................................................................... 21 Publishing .................................................................................................................................. 22

Copyright © 2014 Hedgehog Development

Before delving into how to implement automated deployments we need to understand what we hope to achieve and why. The aim of any automation is to remove the need for someone to perform a repetitive task so that their time can be better utilized elsewhere. By automating our build process we are hoping to achieve the same goal, thus allowing a developer to spend more time developing the solution. Automating the deployment process also gives extra benefits beyond just freeing developer time. Leveraging automated deployment:  Creates a consistent, repeatable process – once the deployment works once you can be confident that it will work in the future  Allows for more frequent deployments – deployment only require a single click to start, therefore development teams are more inclined to deploy more frequently.  Shortens time for your solution to go live – features tend to get to live quicker because they can be released more easily by the development team. There is no longer a need to batch deployments.  Reduces the chance of errors – there is no longer the chance of a someone skipping a step or forgetting something. Releases are often smaller as well as they become more frequent which reduces the chances of breaking changes.  Reduces key person dependencies – by automating the deployment process it can be understood by others. Information on how to deploy is no longer contained in a single developers head.

Copyright © 2014 Hedgehog Development

The following section looks at the different methods of implementing automated deployments. The document treats live and staging deployments separately because there is normally more complexity in a final solution when deploying to live environments. The examples in this document have been setup using the TeamCity build server however this build server is not a requirement and the steps can be easily replicated to other build servers.

Code Deployment This deployment strategy deploys the latest code and Sitecore items in source control to a staging server. It assumes that there is already a staging Sitecore instance setup and running and all changes will be deployed on top of this instance. For rapid deployments of code changes to the staging environment this solution is an excellent option and is the minimal solution. After each developer checks in their code this method can be used to deploy their changes to staging within a few minutes, allowing the test team to instantly see bug fixes and new features. Assumptions  A staging server with a Sitecore instance already exists  The build server has UNC access to the staging server. Tools  Sitecore  Build Server  Team Development for Sitecore Process Overview 1. The development team checks in their latest code 2. The build server pulls and compiles the latest changes 3. Team Development for Sitecore deploys the latest code to the staging server

Copyright © 2014 Hedgehog Development

Steps: 1. Within Visual Studio create a web project 2. Add a TDS project to your solution. 3. Your solution should now contain a web project and a TDS project:

4. Click on the build configuration list and select Configuration Manager:

5. From the Active Solution Configuration list select

6. Call the configuration Staging and copy the settings from Debug:

Copyright © 2014 Hedgehog Development

7. Click Ok and close the Configuration Manager 8. Right click on the TDS project and select Properties 9. Ensure that on the General tab the website project has been selected as the Source Web Project:

10. Select the Build tab and ensure that Staging is the selected configuration:

11. Enter the details of the staging environment into the Sitecore Web Url and Sitecore Deploy Folder fields. The locations must be accessible from your build server:

12. Check Install Sitecore Connector:

13. Save the solution and check everything into source control. 14. On the build server create a new build configuration that builds the solution file using MSBuild. Ensure that the solution’s staging build configuration is being built. To do this you need to pass the following command line parameters to MSBuild:

15. Run the build.

Copyright © 2014 Hedgehog Development

The build will compile the web application, after which TDS will copy the files to the staging server and also deploy any items.

Code Deployment with Content Update This solution builds on the Code Deployment method by also updating the content on the staging environment with content from the live server. This ensures that the staging environment not only has the latest code updates but also has the latest content. This improves testability because the testing team can test changes with real content. It is recommended to implement this solution as part of a nightly build because it can take some time to copy all the content from live to staging depending on the volume of changes. The solution uses the Razl history function to copy data, this requires that the target instance has the Sitecore History Engine turned on.

Assumptions  A staging server with a Sitecore instance that already exists.  The build server has UNC access to the staging server.  The staging server has a licensed version of Razl 2.2.5 or higher.  The live server has been setup. Tools    

Sitecore Build Server Team Development for Sitecore Razl

Process Overview 1. The development team checks in their latest code 2. The build server pulls and compiles the latest changes 3. Team Development for Sitecore deploys the latest code to the staging server 4. Razl uses the Sitecore History Engine to pull any changes made in the last day

Copyright © 2014 Hedgehog Development

Steps: 1. Within Visual Studio, create a web project. 2. Add a TDS project to your solution. 3. Your solution should now contain a web project and a TDS project:

4. Click on the build configuration list and select Configuration Manager:

5. From the Active Solution Configuration list select

Copyright © 2014 Hedgehog Development

6. Call the configuration Staging and copy the settings from Debug:

7. Click Ok and close the Configuration Manager 8. Right click on the TDS project and select Properties 9. Ensure that on the General tab the website project has been selected as the Source Web Project:

10. Select the Build tab and ensure that Staging is the selected configuration:

11. Enter the details of the staging environment into the Sitecore Web Url and Sitecore Deploy Folder fields. The locations must be accessible from your build server:

12. Check Install Sitecore Connector:

Copyright © 2014 Hedgehog Development

13. Right click on the solution in the Solution Explorer and click Add > New Item… 14. Select XML File and call the file Razl-LiveToStaging.xml 15. Enter the following into the Razl-LiveToStaging.xml: http://staging.hhogdev.com C63C521E-A912-4EB4-82F0-78F553CE3EF5 master \\10.10.10.15\sitecore\website http://live.hhogdev.com 81D4B24E-238B-46B4-83A4-302E7B113BFA master 2

This script will copy content from the live server to the staging server using the CopyHistory command. The from parameter has an integer value of 2, this instructs Razl to copy all history entries within the last 2 days. The live connection does not install the Razl connector because this would cause the live site to recycle. Instead you should install the connector using Razl’s package installer method, this only needs to be done once. After installing the Razl package on live you need to ensure that the AccessGuid in the script matches the AccessGuid on live. 16. Save the solution and check everything into source control 17. On the build server create a new build configuration that builds the solution file using MSBuild. Ensure that the solution’s staging build configuration is being built, to do this you need to pass the following command line parameters to MSBuild:

18. Create a second build step to run a command line task:

19. Set the Command Executable to run Razl: 20. Set the Command Parameters:

Copyright © 2014 Hedgehog Development

The parameters instruct Razl to run in script mode, we than pass it the location of where out script lives. You can find more information on Razl script mode in the Razl documentation. 21. Save the build step. 22. Run the build. This build will deploy the latest code changes and then using the Sitecore History Engine copy content from live to the staging environment. This solution does not call a publish on the staging instance, the process to do this is discussed later. The Razl script is not limited to a single command and additional custom commands could be added to copy across different sections of live content. Also read the Razl help documentation for information on how to include and exclude certain items from being copied by the CopyHistory command.

Clean Deployment with Full Live Content Copy This method builds on the Code Deployment process and adds the ability to tear down a Sitecore instance and rebuild it from scratch. This process will also copy over all content from the live server after the deployment of the latest code has been completed. This ensures that the testing team always have a clean instance to use every day. This solution is recommended as a nightly build process because of the time required to rebuild the staging instance and copy data from live. The solution makes use of Sitecore SIM which is a widely used open source tool for managing Sitecore instances and the Sitecore SIM Console which is a simple console application developed by Hedgehog for the purpose of deployments, the source code for the console can be downloaded from GitHub.

Assumptions  A staging server with a Sitecore instance already exists.  The build server has UNC access to the staging server.  The staging server has a licensed version of Razl 2.2.5 or higher.  The live server has been setup.  Sitecore SIM is installed and setup on the staging server.  The appropriate version of Sitecore has been downloaded and dropped into the Sitecore SIM repo.  Sitecore SIM Console has been added to the Sitecore SIM folder.

Copyright © 2014 Hedgehog Development



Tools      

SQL Server and the Sitecore instance are on the same machine. This is required for Sitecore SIM to correctly attach the databases.

Sitecore Build Server Team Development for Sitecore Razl Sitecore SIM Sitecore SIM Console

Process Overview: All steps in the process are performed using the build server  The development team checks in their latest code  Using Sitecore SIM delete the current Sitecore Instance  Using Sitecore SIM create a new Sitecore instance  The build server pulls and compiles the latest changes  Team Development for Sitecore deploys the latest code to the staging server  Razl copies content from live to staging

Copyright © 2014 Hedgehog Development

Steps: 1. Within Visual Studio, create a web project 2. Add a TDS project to your solution. 3. Your solution should now contain a web project and a TDS project:

4. Click on the build configuration list and select Configuration Manager:

5. From the Active Solution Configuration list select

Copyright © 2014 Hedgehog Development

6. Call the configuration Staging and copy the settings from Debug:

7. Click Ok and close the Configuration Manager 8. Right click on the TDS project and select Properties 9. Ensure that on the General tab the website project has been selected as the Source Web Project:

10. Select the Build tab and ensure that Staging is the selected configuration:

11. Enter the details of the staging environment into the Sitecore Web Url and Sitecore Deploy Folder fields. The locations must be accessible from your build server:

12. Check Install Sitecore Connector:

Copyright © 2014 Hedgehog Development

13. Right click on the solution in the Solution Explorer and click Add > New Item… 14. Select XML File and call the file Razl-LiveToStaging.xml 15. Enter the following into the Razl-LiveToStaging.xml: http://staging.hhogdev.com C63C521E-A912-4EB4-82F0-78F553CE3EF5 master \\10.10.10.15\sitecore\website http://live.hhogdev.com 81D4B24E-238B-46B4-83A4-302E7B113BFA master {0DE95AE4-41AB-4D01-9EB0-67441B7C2450} true {3D6658D8-A0BF-4E75-B3E2-D050FABCF4E1} true

This script will copy content from the live server to the staging server using the CopyAll command. The itemId specifies the item from which to start copying Sitecore items. The live connection does not install the Razl connector because this would cause the live site to recycle. Instead you should install the connector using Razl’s package installer method, this only need to be done once. After installing the Razl package on live you need to ensure that the AccessGuid in the script matches the AccessGuid on live. 16. Save the solution and check everything into source control. 17. On the build server create a new build configuration. 18. The first step will delete the target Sitecore instance using the Sitecore.Console:

Copyright © 2014 Hedgehog Development

Parameters: a. Delete – instructs the console to delete the instance b. “staging.hhedgedev.com” – the name of the installed instance to remove c. “c:\sitecore” – the location where the instance is installed d. “Data Source=.;User ID=Sitecore;Password=sitecore123” – connection to the SQL server 19. The second step installs the new Sitecore SIM instance:

a. b. c. d. e. f.

Install – instructs SIM to install a new instance “staging.hhogdev.com” – the name of the Sitecore instance to install “Sitecore 7.1 rev.130926.zip” – the Sitecore version to install “c:\sitecorerepo” – the folder containing the Sitecore zip file “c:\sitecore” – the folder to install the Sitecore instance to “Data Source.;User ID=Sitecore;Password=sitecore123” – the connection string for the SQL instance g. “c:\Sitecore\license.xml” – the license file to use for the Sitecore instance 20. Create a third step that builds the solution file using MSBuild. Ensure that the solutions staging build configuration is being built, to do this you need to pass the following command line parameters to MSBuild:

21. The fourth step class Razl to copy data from Live to Staging:

The parameters instruct Razl to run in script mode, we then pass it the location of where out script lives. You can find more information on Razl script mode in the Razl

Copyright © 2014 Hedgehog Development

documentation. 22. Save the build step. 23. Run the build.

Package Deployment using Sitecore Ship This solution uses TDS to create update packages that deploy the latest code and items. The solution makes use of the Sitecore Ship (https://github.com/kevinobee/Sitecore.Ship) module to automatically deploy the update package onto the live server. Be aware that deploying code via this method will cause the Sitecore instance to recycle therefore you should ensure that the server is out of load and drained correctly before kicking of the build process. The process deploys both files and items in a single update package, this is designed for deployment to the Content Manage Servers (CMS), if you want to deploy to the Content Delivery Servers (CDS) the process is the same except that you will need to configure TDS to generate separate file and item Update Packages. You can then deploy just the file Update Package. This solution requires that the first deployment to the live server is manual because the Sitecore Ship module needs to be setup on the live server. Assumptions  The live server has a Sitecore instance already setup and running.  The live server has the Sitecore.Ship module added  The paths used by the Sitecore.Ship service are protected from external users via a firewall but accessible from the build server.  Sitecore Ship package streaming is enabled: Tools     

Sitecore Build Server Team Development for Sitecore Sitecore Ship Curl

Process Overview: All steps in the process are performed using the build server  Development team checks in their latest code  The build server pulls and compiles the latest changes  Team Development for Sitecore builds the update package to deploy to live

Copyright © 2014 Hedgehog Development

 

Curl posts the created package to the Sitecore Ship service Sitecore Ship installs the package

Steps 1. Within Visual Studio, create a web project. 2. Add a TDS project to your solution. 3. Your solution should now contain a web project and a TDS project:

4. Click on the build configuration list and select Configuration Manager:

5. From the Active Solution Configuration list select

6. Call the configuration Live and copy the settings from Release:

Copyright © 2014 Hedgehog Development

7. Click Ok and close the Configuration Manager 8. Right click on the TDS project and select Properties 9. Ensure that on the General tab the website project has been selected as the Source Web Project:

10. Select the Update Package tab and ensure that Live is the selected configuration:

11. Enter the details required to create the update package:

Copyright © 2014 Hedgehog Development

12. Add the Web.config from your development instance to your web application:

13. Ensure that the modifications made by the Sitecore Ship install are added to the Web.Live.Config, you will also need to specify the configuration for the live server within this file:

Copyright © 2014 Hedgehog Development



14. Save the solution and check everything into source control. 15. On the build server create a new build configuration. 16. Create a build step that builds the solution file using MSBuild. Ensure that the solutions live build configuration is built, to do this you need to pass the following command line parameters to MSBuild:

17. Create another Command Line build setup as the second step. This will be responsible for deploying the Update Package to the target instance.

Copyright © 2014 Hedgehog Development

18. Save and Run the Build

Deployment Setup This section looks at how and when you could use each environment to help you manage your full development lifecycle. During the day to day development of features you may want the ability to instantly deploy the latest features to a testing server as part of your continuous integration process. Once deployed to the continuous integration server you can then have your automated browser tests run against this environment to ensure that the latest check-in hasn’t broken the build. The Code Deployment process is best suited to this scenario because it is the quickest method of deployment, if this deployment process takes too long check-ins will start to backup and you won’t get your test feedback in timely manner. This build is known as the CI Build. The next environment to consider is the testing/staging environment used by the testing team and content team. This environment needs to be stable during the day when the client and testing team are using it but should be updated with the latest features overnight. For this environment the Code Deployment with Content Update or the Clean Deployment with Full Live Content Copy should be used. These builds should take place at night to avoid any disruption to the users and because the content copy can take a while to complete. Most build servers will allow a build to have a dependency on the successful completion of another build. This should be setup for this build so that it has a dependency on a successful completion of the CI Build, this will ensure that the staging environment is only updated with a working release. It is very frustrating for testing teams and the client if they come in the next day to find that the staging environment is no longer accessible. This build is known as the Staging Build.

Copyright © 2014 Hedgehog Development

The final build or more likely builds will be to the live servers. Live server deployments are more complex because they often require the removal of servers from load balancing, careful handling of a user’s session and integration with third party systems. While automation is possible it should not be undertaken lightly and without serious consideration. To minimise the amount of time a server is down it is best to separate the process of building the Update Package from the process of deploying the update package. By separating the two it becomes a very quick process to deploy the update package to each server. Assuming that the live environment had 1 CMS and 4 CDS servers (each CDS server has its own web database) the deployment process might be: 1. Build Server - Build the code base and use TDS to generate separate item and file Update Packages. 2. Build Server - Deploy the item and file Update Packages to the CMS server using a deployment build 3. Manual - Remove CDS 1 and CDS 2 from load 4. Build Server - Deploy the file Update Package to CDS1 and CDS2 5. Build Server – Call a publish on the CMS server to publish content to CDS1 and CDS2 6. Manual - Put CDS1 and CDS2 back into load 7. Manual - Remove CD3 and CD4 from load 8. Build Server - Deploy the file Update Package to CDS3 and CDS4 9. Build Server – Call a publish on the CMS server to publish content to CDS3 and CDS4 10. Manual - Put CDS3 and CDS4 back into load In total 6 build configurations would need to be setup on the build server to achieve this result: 1. Code build 2. CMS deployment 3. CDS1 deployment and publish 4. CDS2 deployment and publish 5. CDS3 deployment and publish 6. CDS4 deployment and publish These builds would all be based on the Package Deployment using Sitecore Ship process but separated across the 6 builds.

Publishing The solutions above did not discuss the process of publishing content from the master database to the web database after deployment. This can easily be achieved by either setting up a

Copyright © 2014 Hedgehog Development

custom page that can be called by the build process or by using the Sitecore Ship module. Sitecore ship has the ability to start a Sitecore publish by calling a URL, for example the following will perform a full publish in English: http://staging.hhogdev.com/services/publish/full For more information on controlling how Sitecore Ship publishes refer to the documentation here at https://github.com/kevinobee/Sitecore.Ship.

Copyright © 2014 Hedgehog Development