Transforming Sitecore config files per role with Octopus Deploy

When using Octopus Deploy to deploy Sitecore solutions that are scaled i.e. have one or more Content Delivery or Content Management servers, there are configuration changes that need to be made for each role. For example a Content Delivery server does not require a connection string for the master database or setting out of process session state for Content Delivery servers.

Config transforms are an obvious way to accomplish this but they are usually setup per environment, however with a little tweaking and some built in Octopus functionality we can achieve config transforms per server role.

Add a new config file to your solution I have added Web.CD.config.

Next, unload your project, and edit the .csproj file. To fix the linking linking of the files. This is done simply by adding a DependentUpon element inside each Item. Let’s say you have this:

<None Include="Web.CD.config">

Update the XML to look like this :

<None Include="Web.CD.config">

And you end up with nicely linked and stacked files


The new config transform must be have Build Action of Content so it is deployed with your NuGet package.



The config transform in this example is straight forward I am going to change the session state to be Mongo instead of InProc.

With that in place and committed there are some changes to make to Octopus to use the new transform file

Create your variables with the appropriate scope, here I have added a new variable called WebConfigTransform that will be available in Octopus and set the value to Web.CD.Config for servers in the Role ContentDelivery for environments UAT and LIVE


You can also have Octopus substitute variables in your transforms with variables defined in Octopus,  its not required in this example but useful when you are transforming ConnectionStrings.config for example more on it



Finally tell Octopus which transform to apply to which config file and the appropriate file will be used per role as defined.


Once you have this setup and created a new release check the output from your step with transforms and you with see Octopus switching in the appropriate transform per role.

Here is the output from my package deployment step on one of the Content Delivery Servers :-

Transforming 'C:\Octopus\Applications\Environment\Project\1.5.1\Web.config' 
using 'C:\Octopus\Applications\Environment\Project\1.5.1\Web.CD.config'.
Transforming 'C:\Octopus\Applications\Environment\Project\1.5.1\App_Config\ConnectionStrings.config' 
using 'C:\Octopus\Applications\Environment\Project\1.5.1\App_Config\ConnectionStrings.CD.config'.

Cleanup afterwards

I have another step in my process to remove the transforms after they have been used so they are not left behind on the server using some PowerShell.

Exclude CD transforms from local One-Click Publish Profile

You will also need to prevent these files being deployed during local development using One-Click Publish.

Find your projects *.pubxml file, should be in the \Properties\PublishProfiles directory  of your web project and add a new PropertyGroup element inside add a ExcludeFilesFromDeployment element and add a list of semicolon separated files to exclude.


Your should end up with something like this.