Installing and upgrading Igloo on Umbraco Cloud
On Umbraco Cloud you install packages into a local copy of your site, then deploy them up. Igloo works the same way, and Umbraco's own deployment steps are the ones to follow.
The short version: install or upgrade Igloo in a local clone, then commit and push. Cloud picks up everything Igloo added from the files you pushed.
Your document types, data types and templates reach a Cloud environment from your repository. Add Igloo straight to a Cloud environment and none of them turn up.
Before you start
- A clone of your Cloud project on your machine. See Working with a local clone.
- A backup of your project's database, taken from the Umbraco Cloud portal.
- Your Igloo licence key.
1. Clone the left-most environment
If your project has more than one environment, clone the left-most one, usually Development. Deployments travel left to right, so starting anywhere else leaves you unable to deploy forward.
Bring your clone up to date before you change anything:
git pull
2. Install or upgrade Igloo locally
Add or update the LittleNorth.Igloo NuGet package, build, and run the site locally. See Installation, or Upgrading Igloo if you're moving between major versions.
Running it locally is the step that matters. The first boot is when Igloo sets itself up and writes out the files Cloud will need.
3. Check the files were created
Run git status in your clone. You should see new or changed files under /umbraco/Deploy/Revision, which is where your document types and data types live, plus the usual templates and CSS:
git status
If Igloo is sitting there in your local backoffice and git status shows nothing, stop and check the site did boot locally. Without these files, Cloud has nothing to pick up.
4. Test locally
Open the local backoffice, check Igloo's document types are present, and load the front end. Anything broken is far quicker to sort out here than on a Cloud environment.
Upgrading? This is also where you rebuild whatever doesn't carry across. See Umbraco Upgrade v13 -> v17 and Widget Mapping v13 -> v17.
5. Commit and push
git add .
git commit -m "Install Igloo"
git push
If the push is rejected, run git pull first, then push again.
Watch the deployment through in the Umbraco Cloud portal before you move on.
6. Deploy through your other environments
Use the Deploy changes to… button in the Cloud portal to move the same deployment through your remaining environments. One at a time, checking each before you continue. Never push from your local clone into a right-hand environment.
7. Transfer your content
Your deployment carries the schema. Content and media move separately, transferred from the backoffice with Add to Transfer Queue, as Umbraco covers in its deployment overview.
Worth knowing for Igloo, because a few things that look like settings are content nodes:
| What | How it gets there |
|---|---|
| Document types, data types, templates | With your deployment |
| Views, CSS, custom widget code | With your deployment |
Design nodes and Palettes | Transfer from the backoffice |
Settings node, including Scripts | Transfer from the backoffice |
| Pages, media, starter content | Transfer from the backoffice |
Once the deployment is through, transfer your Design nodes and Palettes and your Settings to each environment, along with the content and media. An environment with no Design nodes renders unstyled. Content templates behave the same way, as does anything else sitting in the content tree.
8. Add your licence to each environment
Either commit umbraco/Licenses/igloo.key so it deploys with your code, or add your key through the Igloo tab in Settings on each environment. If you commit it, check your project's .gitignore isn't excluding it. An environment without the key starts up showing an invalid licence banner.
See Installation for both methods, and the FAQ for how licensing works across localhost and Cloud domains.
Upgrading Umbraco at the same time
If your Igloo upgrade comes with an Umbraco major upgrade, follow the order Umbraco recommends in Major Upgrades: upgrade locally, check the backoffice loads, then deploy. You may also need to set the .NET framework runtime for each environment in the Cloud portal first.
Igloo has no upgrade path that skips a major version. Take one major at a time and finish the whole local-to-Cloud round trip before you start the next. See Upgrading Igloo.
If something doesn't look right
Igloo's document types are missing on a Cloud environment. The environment hasn't received them. Check the /umbraco/Deploy/Revision files are in your repository, then deploy again.
A migration error mentioning a property that doesn't exist has the same cause: the environment is missing the schema those files provide. Put it right in your local clone, push, and deploy. Correcting it on the Cloud environment itself will only leave that environment out of step with the others.
The site renders unstyled. Your Design nodes haven't been transferred yet. See step 7.
A deployment fails. Read the deployment log in the Cloud portal before you retry. It names what couldn't be applied.
Still stuck? Email us at hello@iglootheme.com and we'll help.
Why it works this way
The technical detail, if you want it
Igloo sets itself up with an Umbraco package migration. Whether that migration is allowed to create schema and content comes down to a setting, Umbraco:CMS:PackageMigration:RunSchemaAndContentMigrations, which Umbraco Cloud overrides. As Umbraco's Package migration settings documentation puts it, package migrations run fully only in local environments.
This is deliberate, and it applies to every package on Cloud.
Schema on Cloud belongs to Umbraco Deploy. Create it locally and Deploy serialises it to .uda artifact files in /umbraco/Deploy/Revision, and those files are what move it between environments. Let each environment generate its own copy and they'd drift apart within a deployment or two.
The local run in step 2 carries the weight here. Step 3 is there to catch the case where those files never appeared.