How to Remotely Sync Unicorn 3 to Install Serialized Items Into Sitecore
Posted 09/01/2016 by David DeBruin
This is the first in a several part series that I will be adding to the blog over the new few weeks that covers the Sitecore Habitat Framework and Continuous Integration.
This particular post deals with remotely syncing Unicorn, from, for example, a build server. In the current set up I am dealing with we have developers working on their local boxes. Code is checked in to Bitbucket (Git) from their local boxes. TeamCity then is set up on the build server and automatically pulls code from Bitbucket upon check-in. The code is then built on the build server, pushed to the integration environment and then Unicorn is remotely synced from the build server to install the new templates and content in Sitecore on the integration machine from the serialized files that Unicorn uses.
Version of Unicorn used when creating this post - 3.1.1
Here is the summary of sections in this post. Click to jump to the section.
- Enable HTTPS on target server
- Install certificate in Trusted Root Certification Authorities
- Download PowerShell sample script, PowerShell module and MicroCHAP.dll from Unicorn GitHub
- Duplicate the sample.ps1 file and rename it something that makes sense for your project - such as project name
- Generate a lengthy secret key and add to PowerShell script and Unicorn.UI.config
- Run the PowerShell script
There are some very good guides already out there on the Internet for some of these steps. I won't be detailing those steps. Instead I'll link to the guides I found useful.
1. Enable HTTPS on target server
The genius Scott Guthrie has a fantastic post on this topic right here - tip-trick-enabling-ssl-on-iis7-using-self-signed-certificates. Over the course of the past 10+ years of my career Scott Gu has been a constant source of tremendous information on ASP.NET.
2. Install certificate in Trusted Root Certification Authorities
This section involves taking the self-signed certificate we created in step 1 and adding it to the Trusted Root Certification Authorities for the server. The reason for doing this is to avoid any handshake problems during the CHAP communication that Unicorn uses for it's remote syncing. Here is an article describing how to do this - installing-a-self-signed-certificate-as-a-trusted-root-ca-in-windows-vista. The article is for Vista but I found the process to be identical on Windows Server 2012.
3. Download PowerShell sample script, PowerShell module and MicroCHAP.dll from Unicorn GitHub
Out on GitHub in Unicorn's space - Unicorn GitHub space - there is a folder that contains everything you need to remotely sync Unicorn. Clone or download the Unicorn repository. Inside of the doc\PowerShell Remote Scripting folder is the files we are after.
Place the sample.ps1, Unicorn.psm1 and MicroCHAP.dll somewhere on your build server and add a reference to MicroCHAP.dll in your project and rebuild. Check the bin to make sure you see the MicroCHAP.dll. (Note - if you are using the Habitat Framework this DLL should already be a part of your solution. It is referenced in the Sitecore.Foundation.Serialization project which is located from the root of Habitat @ src\Foundation\Serialization\code\Sitecore.Foundation.Serialization.csproj) This DLL is what the Unicorn.psm1 PowerShell module will call to do the remote sync. I don't believe the MicroCHAP.dll is required to be in the same folder as the sample.ps1 and Unicorn.psm1 when remotely syncing Unicorn because I tried it when I removed the DLL and it still worked. But there is a reference to the DLL in the Unicorn.psm1 module so I would just leave the DLL in the same folder as the sample script and module just to be safe.
4. Duplicate the sample.ps1 file and rename it something that makes sense for your project - such as project name
For this example I'm going to name mine UnicornRemoteSync.ps1. The directory on our build server should now look like this:
4a. Explanation of sample script
Open up our duplicated and renamed sample script. There are 2 lines that matter to us. This line:
That line will sync all of your solution configurations at once. And this line:
Which syncs specific configurations. In the line above it would sync two configurations named Test1 and Test2 in that order. You only need to use one of these lines so whichever one you are going to use put a comment (#) in front of the other line.
Important note about the "Sync All" option above -
You may have noticed that on the Unicorn control panel (/unicorn.aspx) it puts the configurations in order based on dependencies. If there a configuration that requires certain file to exist for before running the control panel is smart enough to put the configurations in order so that everything in synced in the order that it should be synced so that everything exists at run time. Notice the highlighted text below from the Unicorn control panel:
Well running the sync all configuration from the script above DOES NOT run the configurations in order of dependency like the control panel does. I can into errors trying to use the all sync because it was syncing configurations that were subitems of another configuration that hadn't been run yet. For that reason I ended up switching to using a named list of my configurations in order of dependency. If you are unsure what the correct order should be just run the Unicorn control panel (/unicorn.aspx) and write down the order that is displayed on that page since the control panel puts them in the correct order.
5. Generate a lengthy secret key and add to PowerShell script and Unicorn.UI.config
Go here http://passwordsgenerator.net and generate a nice long (at least 64 characters is recommended) string of random characters. The config file won't like it if you use some special characters because they will need to be escaped so to keep it easy don't use symbols. Here is my setting from that page:
I generated a key of 100 characters with no symbols.
After generating the key add the key to the UnicornRemoteSync.ps1 PowerShell script we created above by duplicating the sample provided. Add the key between the single quotes replacing the "your-sharedsecret-here" text:
Then open up the Unicorn.UI.config (from the root - src\Foundation\Serialization\code\App_Config\Include\Unicorn\Unicorn.UI.config) and uncomment the shared secret line:
Then add the secret key to the SharedSecret node:
Next replace the ControlPanelUrl setting:
with the Url to the Unicorn control panel of the website on your target server. This is a good time to check and make sure you can access that Url as well. Try it in a browser and make sure it's accessible from the build server. If you can't access it then you won't be able to remotely sync until you fix whatever the problem is.
6. Run the UnicornRemoteSync.ps1 PowerShell script
Before adding a step in TeamCity or any other Continuous Integration tool open PowerShell ISE on the build server and run the script we created. Doing it this way you'll be able to easily see any errors in the output window. The only error you'll encounter for the most part would be communication issues between the two servers or if you didn't enter a matching secret key on the two servers.