Deploying Sitecore items with Sitecore.Ship
As I mentioned in the previous post
Sitecore.Ship can be used to install Sitecore
zip packages by posting HTTP requests to the Sitecore site.
I forgot to talk about the configuration in the previous post so let’s have a look at that now. The Sitecore.Ship configuration is split into two parts:
ship.configfile (located in App_Config\Include) contains the patched
IgnoreUrlPrefixesattribute to include the
/services/url part which Sitecore.Ship is using.
web.configis updated with a
packageInstallationelement. The default values of this element are:
<packageInstallation enabled="true" allowRemote="false" allowPackageStreaming="false" recordInstallationHistory="false" />
The attributes are pretty self explanatory. I’ll get to the
recordInstallationHistoryin a later post. Just make sure it is
falseotherwise there will be errors about a missing PackageId.
Uploading and installing a package
One of the most useful commands of Sitecore.Ship is
fileupload. When you issue an HTTP request to
you can upload and install a Sitecore package.
The wiki describes that you need to provide the path of the package as form-data in the request. Lets have look how that is done exactly.
The easiest way to test the commands Sitecore.Ship offers is to use an HTTP/REST client such as Postman, which I’m using here.
Once you’ve started Postman you’ll see this screen:
Change the following fields to do a post request to upload and install a package:
- Note that the value of the Key parameter (
pathin this example) is actually irrelevant, it can be any value.
Once the value type is set to
Filean Open file dialog can be used to select the file to upload.
Now press the blue Send button to do the post request. If everything went well output shows the Sitecore IDs and path of the items that were in the package and have been installed:
So far so good, but we don’t want to use Postman manually in order to upload and install packages for every deployment right? We need a solution that can be automated and used in a continuous integration setup.
I first looked into PowerShell and the
Invoke-RestMethod command but it appeared that OOTB this method does not support
multipart form data, which is required to call the
There is a workaround to create the required multipart boundaries
in the request but I did not like this approach. I looked for another solution and found cURL.
cURL is a very powerful commandline application to script HTTP jobs. Getting the syntax right can be a little tricky although there is quite some documentation. Luckily Postman can generate various scripts including one for cURL:
However the cURL script in the screenshot above contains a lot of unncessesary statements and actually gives errors. I’ve found that this is the minimal cURL syntax which works for me:
curl -F "path=@<path to update or zip package>" 'http://<website>/services/package/install/fileupload'
Sofar we’ve only replaced Postman with cURL, but since cURL is a commandline tool it can be easily called from a script during a deployment process as we’ll see next.
In the Gist below you can see the deploy-sitecorepackage.ps1 script which I use to upload and deploy Sitecore packages.
I actually prefer to use the more verbose cURL syntax (e.g.
--form instead of
-F) because I believe the intention
of the script is much more clear to the reader who might not know the syntax well.
A full description of the parameters can be found in the cURL manual.
The deploy-sitecorepackage.ps1 script uses another script called get-curlpath.ps1 to obtain the path to the cURL executable.
These PowerShell scripts can now easily be used in continuous integration & delivery tools such as Octopus Deploy or Microsoft Release Management.
In the next post I’ll explain how Sitecore.Ship can be used to record the package installation history.