A guide to help you migrate your Umbraco CMS site to Umbraco Cloud.
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.
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.
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.
Run the project.
Access the Umbraco Backoffice.
Empty the Recycle bin in the Content section.
Empty the Recycle bin in the Media section.
Stop the project.
Delete the following folders from the project directory:
umbraco/Data/TEMP
umbraco/Logs
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.
Migrate your content and data to Umbraco Cloud using Umbraco Deploy.
Use Microsoft SQL Server Management Studio or a similar tool to export a .bacpac file of your project database.
Save the .bacpac file on your machine.
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:
Create an Umbraco Cloud Trial project.
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.
Click Create project in the Umbraco Cloud Portal.
Choose Umbraco Cloud as the Type.
Choose a plan that enables you to add a Development environment.
Select the version that matches the project you want to migrate.
Give the project a name.
Choose from which Region the site should be hosted.
Select a project owner.
Ensure a Technical contact is added.
Click Continue.
Verify all the information is correct.
Check the "Terms and conditions" box.
Click Create Project.
Once the project is set up, add a Development environment. This will enable you to start over with the migration, should something go amiss.
Many processes happen in the background when a new Cloud environment is set up. It might take several minutes before the environments are ready to use.
With the Cloud project set up and ready, the migration can start in the next step.
The database is uploaded to the Umbraco Cloud project via the Umbraco Cloud Portal.
Follow the Upload Database and Restore Database sections in the Database Backups article to complete this step in the migration.
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.
To continue the migration the next step is to clone down the Umbraco Cloud environment to merge it with the Umbraco CMS project.
Follow the steps outlined in the Working with a Local Clone article to clone down the Development environment of the Umbraco Cloud 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.
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
Merge the relevant configuration files.
Use a tool like DiffMerge to identify which configurations to merge.
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
Merge custom code in the Program.cs file.
Open the appSettings.json file.
Connect the Cloud clone to the Umbraco CMS project database by adding a new connection string:
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.
Access the backoffice of the local Cloud clone using Umbraco ID.
Navigate to the Deploy dashboard in the Settings section.
Locate the Export Schema to Data Files in the Deploy Operation section.
Click Export Schema to initiate the export.
Use the Deploy Status section at the top to determine when the export is complete.
Stop the project.
Add and commit the changes through Git.
Learn more about working with a local Cloud clone in the Deploying Changes article.
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.
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?
We recommend following the Copy blobs between Azure accounts guide in the official Microsoft Documentation.
Follow the guide in the Connect to Azure Storage Explorer article to access the Azure Blob Storage container connected to the Development environment.
Locate the media files for your Umbraco CMS project.
Copy the ~/wwwroot/media folder into the Azure Storage Explorer.
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.
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.
Follow the steps outlined in the Working with a Local Clone article to clone down, restore, and run the Development environment locally.
You might need to do a Workspace restore from the Media section in the Umbraco backoffice to restore the media files.
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.
