Deploy Umbraco using Octopus Deploy

Every once in a while you come across a tool that really fits its purpose and delivers good value for not a whole lot of effort. I'm happy to say that I think Octopus Deploy is one such tool! While Octopus isn't the first (or most mature in this space) it hits a sweet spot and really offers any sized team the ability to get on board the Continous Deployment / Delivery bandwagon.

My team is using it to deploy a range of .Net websites and we're considering it for pushing database changes too (although these days a lot of what we build utilises Entity Framework so we don't need to push that many DB scripts about any more) and one thing we've done a lot of is deploy Umbraco 4 sites.

It's About The Code

One important fact to get out here is that I'm only going to talk about how Octopus will help you deploy .Net code changes only. While you can generate SQL scripts and deploy them using Octopus (and ReadyRoll perhaps), Umbraco development has little to do with schema change and everything to do with instance data change. This is not an easy space to be - more so with larger websites - and even Umbraco has found it hard to solve despite producing Courier specifically for this challenge. This all being said, I'm sure if you spend time working with SQL Data Compare you can come up with a database deployment step using scripts.

Setting It Up

Before you start Umbraco deployments using Octopus you need to make a decision about what to deploy each time and then modify your target.

When developing with Umbraco you will have a "media", an "umbraco" and an "umbraco_client" folder in your solution folder but not necessarily included in your Visual Studio solution. These three folders will also be present on your target deployment server and in order to leverage Octopus properly you need to manage these three folders appropriately.

Media folder

This folder holds files that are uploaded by CMS users over time. It is rare that you would want to take media from a development environment and push it to any other environment other than on initial deployment. If you do deploy it each time then your deployment will be (a) larger and (b) more challenging to deploy (notice I didn't say impossible). You'll also need to deal with merging of media "meta data" in the Umbraco CMS you're deploying to (you're back at Courier at this stage).

Regardless of whether you want to push media or not you will need to deal with how you treat the media folder on your target server - Octopus can automatically re-map your IIS root folder for your website to your new deployment so you'lll need to write Powershell to deal with this (and merging content if required).

Our team's process is to not transfer media files via Octopus and we have solved the media folder problem by creating the folder as a Virtual Directory in IIS on the target web server. As long as the physical folder has the right permissions you will have no problems with this approach. The added benefit here is that when Octopus Deploy remaps your IIS root folder to a new deployment the media is already in place and not affected at all.

Umbraco folders

The two Umbraco folders are required for the CMS to function as expected. While some of you might make changes internally to these folders I'd recommend you visit your reasons for doing so and see if you can't make these two folders static and simply re-deploy the Umbraco binaries in your Octopus package.

There are a couple of ways to proceed with these folders - you can choose to redeploy them each time or you can treat them as exceptions and, as with the media folder, you can create Virtual Directories for them under IIS.

If you want to redeploy them as part of your package you will need to do a few things:

Create a small stub "umbraco.zip" that is empty or that contains a single file (or similar) in your Visual Studio solution.
Write some Powershell in your PostDeploy.ps1 file that unzips those folders into the right place on your target web server.
In your build script (on your build server, right?) utilise an appropriate MSBuild extension (like the trusty MSBuildCommunityTasks) to zip the two folders into a zip that replaces the stub you created in (1).
Run your build in Release mode (required to trigger OctoPack) which will trigger the packaging of your outputs including the new zip from (1).

On deployment you should see your Powershell execute and unpack your Umbraco folders into the right place!

Alternatively, you can choose not to redeploy these two folders each time - if this suits (and it does for us) then you can use the same approach as with the media folder and simply create two Virtual Directories. Once you've deployed everything will work as expected.

It's Packaged (and that's a Wrap)

So there we have a simple scenario for deploying Umbraco via Octopus Deploy - I'm sure there are more challenging scenarios than the above but I bet with a little msbuild and Powershell-foo you can work something out.

I hope you've found this post useful and I'd recommend checking out the Octopus Deploy Blog to see what great work Paul does at taking feedback on board for the product.