Umbraco Cloud
CMSHeartcoreDXPMarketplace
  • What is Umbraco Cloud?
  • Frequently asked questions
  • Security
    • Web Application Firewall
  • Sustainability Best Practices
  • Getting Started
    • Explore Umbraco Cloud
    • The Cloud Portal
      • Organizations
      • Sustainability Dashboard
    • Project Overview
    • Environments
    • Flexible Environments
    • Baselines
      • Baseline Merge Conflicts
      • Break Reference between Baseline and Child Project
      • Handling configuration files
      • Pushing Upgrades to a Child Project
    • Plans
    • Migrate to Umbraco Cloud
    • Repositories in a Cloud Project
    • Best Practice for Working in Teams
    • Migrate between regions
  • Set up
    • Ready to Set Up Your Project?
    • Working with a Local Clone
      • Legacy Umbraco Visual Studio Setup
    • Manage Environments
    • Project Settings
      • Managing Transport Security
      • CDN Caching and Optimizations
      • Dedicated Resources
      • Upgrade your Plan
      • Public Access
      • Managing Hostnames
        • New Certificate Authority for custom hostnames
        • Rewrite rules
        • Custom Certificates
      • Management API Security
      • Umbraco CI/CD Flow
        • Cloud API For CI/CD Flow
        • Configuring a CI/CD pipeline
          • Azure DevOps
          • GitHub Actions
        • Troubleshooting
        • Known Limitations and Considerations
      • External Services
      • Usage
        • Bandwidth
      • Availability and Performance
      • Hostname Monitoring
      • Team Members
        • Technical Contact
      • Secrets Management
      • Project History
    • Private NuGet Feed on Umbraco Cloud
    • Going Live
    • Media
    • External Login Providers
    • Azure Blob Storage
      • Connect to Azure Storage Explorer to upload files manually
      • Connect and Upload Files Programmatically to Azure Blob Storage
    • Users
    • Multi-Factor Authentication
    • Application Insights
    • Config Transforms
    • SMTP Settings
    • Payments
    • Power Tools (Kudu)
      • View the Files on your Cloud Environments
      • Generate UDA files
      • Manually run Extractions on your Cloud Environments
  • Deployments
    • Deployment
    • Deploying between environments
    • Transferring Content, Media, Members, and Forms
    • Deploying Deletions
    • Deployment Webhook
    • Deploying Changes
    • Umbraco Forms on Cloud
    • Deploy Dashboard
    • Hotfixes
      • Apply hotfix by manually moving files
      • Apply hotfix by using Git
    • Restoring Content
      • Partial Restores
  • Databases
    • Keep Your Data Secure and Accessible
    • Working with databases
    • Database backups
    • Database
      • Connecting to the Database on Mac
    • Working with a Cloud database locally
  • Product Upgrades
    • Stay Up to Date with Umbraco Cloud
    • Product Upgrades
    • Major Upgrades
    • Minor Upgrades
    • Version Specific Upgrades
      • Migrate from Umbraco 8 to the latest version
      • Migrate from Umbraco 7 to Umbraco 8 on Umbraco Cloud
    • Upgrade your projects manually
      • Manual upgrade of Umbraco CMS
      • Manual upgrade of Umbraco Deploy
    • Dependencies on Umbraco Cloud
  • Troubleshooting
    • Resolve Issues Quickly and Efficiently
    • Troubleshooting FAQ
    • Log files
    • The Umbraco Backoffice
    • The Frontend
    • The Umbraco Cloud Portal
    • Site Performance checklist
    • Troubleshooting deployments
      • Extraction error: Config transforms failing
      • Extraction error: Data Type collisions
      • Dependency Exception
      • Merge Conflicts on Flexible Environments
      • Troubleshooting deployments failing with no error message
      • Troubleshooting duplicate dictionary items
      • Troubleshooting language mismatches
      • Path too long Exception
      • Schema Mismatches
      • How to resolve collision errors
      • Extraction error: "Type not found! "
    • Cloud Errors
  • Release Notes
    • Overview 2025
      • June 2025
      • May 2025
      • April 2025
      • March 2025
      • February 2025
      • January 2025
    • Overview 2024
      • December 2024
      • November 2024
      • October 2024
      • September 2024
      • August 2024
      • July 2024
      • May 2024
      • April 2024
      • March 2024
      • February 2024
      • January 2024
    • Overview 2023
      • December 2023
      • October 2023
      • September 2023
      • August 2023
      • June 2023
      • May 2023
      • April 2023
      • March 2023
      • February 2023
      • January 2023
    • Overview 2022
      • December 2022
      • November 2022
      • September 2022
      • August 2022
      • June 2022
      • May 2022
      • April 2022
      • March 2022
      • February 2022
      • January 2022
Powered by GitBook
On this page
  • Requirements
  • Prepare your project
  • Create a database backup file
  • Create a new project on Umbraco Cloud
  • Create a new project
  • Upload the database to Umbraco Cloud
  • Merge the projects
  • Generate data files
  • Migrate media files
  • Verify the migration
  • Next steps
  • Deploy the migration to the Live environment
  • Publish the website

Was this helpful?

Edit on GitHub
Export as PDF
  1. Getting Started

Migrate to Umbraco Cloud

A guide to help you migrate your Umbraco CMS site to Umbraco Cloud.

PreviousPlansNextRepositories in a Cloud Project

Last updated 2 months ago

Was this helpful?

One way to start your Umbraco Cloud journey is to migrate an existing Umbraco CMS project to the platform. There are some requirements that this project needs to meet as well as some specific steps to follow.

In this article, you can find all the information you need to migrate your existing Umbraco CMS project to Umbraco Cloud.

Requirements

To properly migrate your Umbraco CMS project to Umbraco Cloud it is important to ensure that your project meets the requirements.

Each requirement outlined below is presented with recommended suggestions when a project does not meet the requirements.

Use a supported version of Umbraco CMS

The project needs to run one of the currently supported versions of Umbraco CMS.

One of the first steps in this migration guide is to create a new project on Umbraco Cloud. You can only create Umbraco Cloud projects that use supported versions of Umbraco CMS, which requires you to upgrade your project accordingly.

Recommendation

  • Upgrade the project to the latest Long-Term Supported (LTS) version of Umbraco CMS.

    • Find more details on upgrading in the .

If you prioritize new features over long-term support, you can upgrade to the latest support Short-Term Supported (STS) version instead.

Learn more about the versioning strategy including which versions are currently supported in the .

Ensure all packages and add-ons are compatible

In case the project uses packages or add-ons, these will need to be compatible with both Umbraco Cloud and the Umbraco CMS version used.

Most packages and add-ons are compatible with Umbraco Cloud. It is recommended, however, to verify the compatibility for each package and add-on used, before continuing the migration. This is especially true for packages and add-ons that store data in the Umbraco project.

Recommendations

  • Use the to verify compatibility for each package/add-on used on your Umbraco CMS project.

    • Verify version compatibility for all packages and add-ons used.

    • Verify Umbraco Cloud compatibility for all packages and add-ons used.

      • Contact the package/add-on owner if in doubt.

      • All Umbraco HQ packages and add-ons are compatible with Umbraco Cloud.

  • Remove any packages and add-ons not compatible with Umbraco Cloud or the Umbraco CMS version.

Optionally, look for alternative packages to replace any incompatible packages used on the project.

Avoid legacy code

Due to incompatible legacy code in old Umbraco CMS versions, we strongly recommend avoiding migrating projects upgraded from versions older than version 7.

Was the project created using Umbraco 6 or older versions, both the source code and the database can contain legacy code. This code is incompatible with modern versions of Umbraco CMS and Umbraco Cloud and cannot be migrated.

Recommendation

  • Build a new project using a supported Umbraco CMS version, instead of migrating.

  • Reach out to our support team to discuss recommendations moving forward from here.

Prepare your project

Before initiating the migration, the project should be cleared of unnecessary files and data. This includes emptying recycle bins in the Umbraco backoffice and deleting temporary files in the project repository.

Follow the cleanup steps on the local environment/clone of the Umbraco CMS project.

  1. Run the project.

  2. Access the Umbraco Backoffice.

  3. Empty the Recycle bin in the Content section.

  4. Empty the Recycle bin in the Media section.

  5. Stop the project.

  6. Delete the following folders from the project directory:

    • umbraco/Data/TEMP

    • umbraco/Logs

Create a database backup file

The data from the Umbraco CMS project will be migrated to Umbraco Cloud by uploading a database .bacpac file. The next steps will guide you through creating a .bacpac file from the project database.

Creating a bacpac file requires that the project use an SQL Server database. If the project is using an SQLite database a couple of different options are available:

  • Find an external tool to convert the SQLite database to SQL Server.

  1. Save the .bacpac file on your machine.

Create a new project on Umbraco Cloud

When migrating a project to Umbraco Cloud it is important to do so with a clean project. Using a clean project ensures that no unknown factors can come into play during the migration.

You can create a new Umbraco Cloud project in one of the two ways:

    • The project will be free for 14 days, whereafter a subscription is required.

  • Create a new Umbraco Cloud project from the Umbraco Cloud Portal.

    • Follow the setup instructions detailed below.

Create a new project

  1. Click Create project in the Umbraco Cloud Portal.

  2. Choose Umbraco Cloud as the Type.

  3. Choose a plan that enables you to add an extra mainline environment.

  4. Select the version that matches the project you want to migrate.

  5. Give the project a name.

  6. Choose from which Region the site should be hosted.

  7. Select a project owner.

  8. Ensure a Technical contact is added.

  9. Click Continue.

  10. Verify all the information is correct.

  11. Check the "Terms and conditions" box.

  12. Click Create Project.

Once the project is set up:

  1. Select Configure environments.

  2. Add a new mainline environment.

    • Throughout this guide, this mainline environment will be referred to as the Development environment.

Having more than one environment on your project, will enable you to start over with the migration process should it be needed.

Many processes happen in the background when a new Cloud environment is set up. It might take some time before the environments are ready to use.

With the Cloud project set up and ready, the migration can start in the next step.

Upload the database to Umbraco Cloud

The database is uploaded to the Umbraco Cloud project via the Umbraco Cloud Portal.

You will not be able to view the front end of the website yet, as the project files have yet to be migrated.

The Umbraco Cloud project is now ready for the next step where the two projects will be merged.

Merge the projects

To continue the migration the next step is to clone down the Umbraco Cloud environment to merge it with the Umbraco CMS project.

Do not run the project after cloning it down.

In the following steps, the Umbraco CMS project will be merged into the Umbraco Cloud project.

  1. Move the following files from the Umbraco CMS project into the cloned Cloud project:

    • View files in ~/Views (.cshtml)

    • Controllers and Models

    • CSS files and scripts in ~/wwwroot

  2. Merge the relevant configuration files.

    • Do not merge the following configuration keys in appSettings.json:

      • Umbraco:CMS:Global:Id

      • Umbraco:CMS:Global:UseHttps

      • Umbraco:CMS:Global:NoNodesViewPath

      • ConnectionStrings:umbracoDbDSN

      • ConnectionStrings:umbracoDbDSN_ProviderName

  3. Merge custom code in the Program.cs file.

  4. Open the appSettings.json file.

  5. Connect the Cloud clone to the Umbraco CMS project database by adding a new connection string:

"ConnectionStrings": {
    "umbracoDbDSN": "Server=myServerAddress;Database=myDataBase;User Id=myUsername;Password=myPassword;TrustServerCertificate=true;",
    "umbracoDbDSN_ProviderName": "System.Data.SqlClient"
  }
  1. Run the project locally.

All data, content, and configuration have been merged into the cloned Cloud environment.

There will be no images or media files in the project. These will be migrated later in the process.

The next step in the migration is to generate data files needed to synchronize with the Cloud project.

Generate data files

  1. Access the backoffice of the local Cloud clone using Umbraco ID.

  1. Navigate to the Deploy dashboard in the Settings section.

  2. Locate the Export Schema to Data Files in the Deploy Operation section.

  3. Click Export Schema to initiate the export.

  1. Use the Deploy Status section at the top to determine when the export is complete.

  1. Stop the project.

  2. Add and commit the changes through Git.

  3. Push the migration to the Cloud environment.

All content, data, and configuration, except for the media files, have been migrated to the Cloud project.

The next step will be to add the media files to the Cloud project using Azure Blob Storage.

Migrate media files

All media on Umbraco Cloud projects are stored in a dedicated Azure Blob Storage container.

Do you use Azure Blob Storage to store the media files that need to be migrated?

  1. Locate the media files for your Umbraco CMS project.

  2. Copy the ~/wwwroot/media folder into the Azure Storage Explorer.

  1. Reload the front end and backoffice of the Umbraco Cloud project to verify that the images have been added correctly.

The Umbraco CMS project has now been migrated to an Umbraco Cloud project.

Verify the migration

Verifying the migration by cloning the Development environment to your local machine is recommended.

This needs to be a new clone. The clone used throughout the migration steps can be deleted.

You might need to do a Workspace restore from the Media section in the Umbraco backoffice to restore the media files.

Next steps

The Umbraco CMS project has now been migrated onto Umbraco Cloud.

Following this guide, the Umbraco CMS project has been migrated to the Umbraco Cloud Development environment. For the migration to be complete, it should be deployed to the Umbraco Cloud Live environment.

To publish the website to the web, attach a hostname to the Live environment.

Migrate your content and data to Umbraco Cloud using .

Use or a similar tool to export a .bacpac file of your project database.

Create an .

Follow the Upload Database and Restore Database sections in the article to complete this step in the migration.

Follow the steps outlined in the article to clone down the Development environment on the project.

Use a tool like to identify which configurations to merge.

Learn more about working with a local Cloud clone in the article.

We recommend following the guide in the official Microsoft Documentation.

Follow the guide in the article to access the Azure Blob Storage container connected to the Development environment.

Follow the steps outlined in the article to clone down, restore, and run the Development environment locally.

Umbraco CMS documentation
Long-Term Support and End-Of-Life article
Umbraco Marketplace
Umbraco Deploy
Microsoft SQL Server Management Studio
Umbraco Cloud Trial project
Database Backups
Working with a Local Clone
DiffMerge
Deploying Changes
Copy blobs between Azure accounts
Connect to Azure Storage Explorer
Working with a Local Clone
Deploy the migration to the Live environment
Publish the website
Use the "Create project" option in the Umbraco Cloud Portal to create a new Umbraco Cloud project.
Use the Umbraco ID signin option when accessing the backoffice on a clone Cloud environment.
Use the "Export schema" option to generate Data Files based on schema in the database.
The Deploy Status section showing a status of "Last deployment operation completed".
Media folder added to the "media" folder using Azure Storage Explorer.