Umbraco Upgrade v8 -> v13

Igloo v5 (Umbraco v8) to v13.x (Umbraco v13)

Safeguard your production site

• Take a backup of your existing site and database just in case.

• If you are able to we’d encourage you to use the backup to set up a development environment for the site and database to mitigate any risk to you production environment.

Prepare your v8 database for migration

• Upgrade your v8 site to the latest Umbraco v8 release (8.18.13 at the time of writing)

  • Minor upgrades for Umbraco 8

  • Version Specific Upgrades

• Upgrade your Umbraco Forms package to the latest Umbraco 8 targeted version (8.13.13 at the time of writing)

  • Version Specific Upgrade Notes

• Update your Umbraco Forms Configuration to store the forms data in the database in App_Plugins\UmbracoForms\UmbracoForms.config

  <setting key="StoreUmbracoFormsInDb" value="True" />

• The usual authorised upgrade process should be followed to migrate your database.

Migrate your v8 database to v10

We now need to spin up a vanilla v10 Umbraco instance to migrate your v8 content.

We need this intermediary step as sql migrations are only maintained in Umbraco releases for the two previous major versions, so v10 has v8 migrations, but v13 only includes from v11 (at least that’s our understanding)

For expediency, we can use Package Script Writer (or any method you chose, this is a throw-away installation so there is no need to complicate it)

# Ensure we have the version specific Umbraco templates
dotnet new -i Umbraco.Templates::10.0.0 --force

# Create solution/project
dotnet new sln --name "IglooMigration"
dotnet new umbraco --force -n "Igloo.www"
dotnet sln add "Igloo.www"

#Add packages
dotnet add "Igloo.www" package Umbraco.Forms 10.0.0

We find running the code in Visual Studio code (with the Powershell extension) gives a nicer experience than the terminal (with debugging if required). Make sure you’ve trusted the workspace and set the language to Powershell. Then, you can run/debug via the top right toolbar.

Once you have the site ready to go, we need to point the installation to the v8 database we prepared earlier.

As mentioned, we’re doing this against a local clone of the database, so usually use LocalDB and a trusted connection, so add/update appsettings.Development.json to include;

"ConnectionStrings": {
    "umbracoDbDSN": "Server=(localdb)\\MSSQLLocalDB;Database={yourDBName};Integrated Security=true",
    "umbracoDbDSN_ProviderName": "Microsoft.Data.SqlClient"
  },

You will see

warning NU1902: Package 'Umbraco.Cms' 10.0.0 has a known
moderate severity vulnerability, https://github.com/advisories/GHSA-cfr5-7p54-4qg8

but that is to be expected as we’re running a specific version with a vulnerability, but only as a temporary database migration step.

Running the site, you’ll again see the authorised update process.

Migrate your v10 database to v13

We now need to spin up a vanilla v13 Umbraco instance to migrate your v10 content.

Again, for expediency, we can use Package Script Writer

# Ensure we have the version specific Umbraco templates
dotnet new -i Umbraco.Templates --force

# Create solution/project
dotnet new sln --name "IglooMigration"
dotnet new umbraco --force -n "Igloo.www"
dotnet sln add "Igloo.www"

#Add packages
dotnet add "Igloo.www" package Umbraco.Forms
dotnet add "$project" package LittleNorth.Igloo --prerelease 

You might want to update the solution/project names (IglooMigration/Igloo.www in the example) to match your requirements, as this will be your site moving forward. The prerelease tag for the igloo package could be removed if you read this after we’ve released it.

Once you have the site ready, we need to point the installation at the v10 migrated database we upgraded in the previous step.

Again we add/update appsettings.Development.json to include;

"ConnectionStrings": {
    "umbracoDbDSN": "Server=(localdb)\\MSSQLLocalDB;Database={yourDBName};Integrated Security=true",
    "umbracoDbDSN_ProviderName": "Microsoft.Data.SqlClient"
  },

Before running the site, we need to manually add/check that the required igloo migration value is in the database, as we already have all the datatypes/doctypes and default content from the previous v8 installation.

The TSQL to run is the following, or you can use any other method.

Insert into dbo.umbracoKeyValue ([key], value) values(
    'Umbraco.Core.Upgrader.State+Igloo','bb70df1e-70f9-42d5-a3e6-cba1837966ce')

Running the site, you’ll again see the authorised update process.

Re-add your Igloo License.Key

You will see a no valid license at this point and an empty document, so you will need to copy your igloo.key file containing your license from the previous install. It goes in the igloo folder. Or you can re add via the backoffice also.

Migrate Doctype Property Names

There are a few changes to make in the back office to the document types.

Latest From Feed Settings

Back-office> Setttings> DocumentTypes > Widgets > Latest From Feed > Latest From Feed Settings

We need to update Number of Posts from a textstring to a numeric.

Feed

Back-office> Setttings> DocumentTypes > Base Document Types > Feed

This one is just an alias change, HideDate → HideDates

Person Settings

Back-office> Setttings> DocumentTypes > Widget > Grid > Person Settings

Update two aliases hideDescriptions → hideDescription, hideEmails → hideEmail

Troubleshooting

If you happen to miss one of these changes or if others are still lurking, you’ll see something similar to the following.

Igloo Customisations

This process should now have your content migrated both to Umbraco 13 and Igloo 13.

If you have customized the Igloo CSS beyond the inbuilt Igloo theming engine, you will now have to merge your changes from your previous site.

If you have created additional widgets, these will also need to be migrated, the content/doctypes will be present from the migrated database, but you will need to migrate your views and associated code from the previous site.

Functionality beyond Igloo

If you have other functionality above and beyond core Igloo, you will also have to revisit that to update to the v13 standards.