Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
In this article, we will cover the steps in order for you to install and configure Umbraco Deploy on a new or existing website.
Ensure to first read and follow the setup guides for either new or existing projects below:
After the Umbraco files have been committed add the following lines to the .gitignore so that they will not be picked up by Git when we are deploying.
The deploy-specific update here will ensure that temporary files generated by Deploy during its operations will not be included in source control.
Make sure that the updates to the .gitignore file are also committed.
When Umbraco has been installed in a repository, we can install Umbraco Deploy in the project.
To install Umbraco Deploy, run dotnet add package Umbraco.Deploy.OnPrem
from the command line or Install-Package Umbraco.Deploy.OnPrem
from the package manager console in Visual Studio.
To be able to use Umbraco Forms with Umbraco Deploy, you need to install the Umbraco.Deploy.Forms
package as well.
In order to deploy content based on certain rich core and community property editors - including Multi URL Picker and Block List/Grid Editor - there is one further NuGet package to install: Umbraco.Deploy.Contrib
.
With Umbraco Deploy installed, to use it in the project you will need to create and add configuration for an API key/secret.
For improved security, it is recommended to set the ApiSecret
(instead of the ApiKey
) setting to a cryptographically random value of 64 bytes. Using Base64-encoding to get the string representation, will result in a value of 88 characters. For versions prior to Deploy 12 or when not using the API secret setting, the recommendation is to set the ApiKey
to a randomly generated string of 64 characters.
Once the API secret has been added, it is now time to configure the environments, also in the appsettings.json
file.
An example configuration with a single upstream environment file will look like this:
The setting under Project:CurrentWorkspaceName should match the Name provided in the list of Workspaces that match the current environment. Using this Umbraco Deploy will indicate the correct current environment on the "Workspaces" dashboard.
In Umbraco Deploy 9, this value was set using the configuration key Debug:EnvironmentName. Although included under a "Debug" section, this setting is required for the installations of Umbraco Deploy on-premises (i.e. other than on Umbraco Cloud). Hence why it was moved to the "Project" section in Umbraco Deploy 10.
Expected values for Type are "development", "staging" or "live". These settings are required, though strictly only for the latter is it necessary to use the specific value of "live", so other values can be used if you have more than these three environments.
You will need to generate a unique GUID for each environment. This can be done in Visual Studio:
Open "Tools".
Select "Create GUID".
Use the Registry Format.
Copy the GUID into the id
value.
Generate a "New GUID" for each environment you will be adding to your setup.
Or by running the following PowerShell command:
The URL configured for each environment should be the root URL for the website and needs to be accessible by the other environments over HTTPS.
Once the configuration has been set up with the correct information we can now go ahead and make sure that the source control is including our files in the /umbraco/Deploy
folder of our Umbraco project.
This can be done by going to the /umbraco/Deploy/Revision
folder of the project and create a test .uda
file, and then check in either your Git GUI or in the command line and verify whether the test file is being tracked.
We can see that the file has been created and it is being tracked by Git and we can go ahead and delete the test file.
Now that Umbraco Deploy has been installed on the project, we can go ahead and commit the files to the repository.
Do not push the files up yet as a CI/CD build server will first need to be set up and connected to our repository.
Before moving on to setting up the build server, make sure that your license is included in your project.
For Umbraco Deploy On-Premise, this will be a key provided to you when taking out your subscription to the product. It should be added to your configuration at the key Umbraco:Licenses:Umbraco.Deploy.OnPrem
.
For example, in appsettings.json
:
Umbraco Cloud projects use a license file placed in the /umbraco/Licenses
folder that is provided when your project is created.
Read more about the Umbraco Deploy licensing model.
How to upgrade Umbraco Deploy
As with all of our products, it is always recommended to run the latest version of Umbraco Deploy.
On the Umbraco Deploy page in the Packages page you can see what the latest version is, as well as read the changelog.
Umbraco Deploy can be upgraded via NuGet.
Open the Package Console in Visual Studio and type:
Update-Package Umbraco.Deploy.OnPrem
You will be prompted to overwrite files. You should choose "No to All" by pressing "L" .
You can open the NuGet Package Manager and select the Updates pane to get a list of available updates. Choose the package called Umbraco.Deploy.OnPrem and click update. This will run through all the files and make sure you have the latest changes while leaving the files you have updated.
Contains version-specific documentation for when upgrading to new major versions of Umbraco Deploy.
Version specific documentation for upgrading to new major versions of Umbraco Deploy.
This article provides specific upgrade documentation for migrating to Umbraco Deploy version 15.
If you are upgrading to a minor or patch version, you can find the details about the changes in the Release Notes article.
Version 15 of Umbraco Deploy has a minimum dependency on Umbraco CMS core of 15.0.0
. It runs on .NET 9.
Version 15 contains breaking changes. The breaking changes appear in areas related to extending Deploy to support additional entities and property editors. For reference though, the full details are listed here:
Asynchronous methods have been added to the following interfaces:
IPropertyTypeMigrator
:
MigrateAsync(...)
These methods all have a default implementation that forwards the calls to the synchronous methods (to maintain backwards compatibility). The synchronous methods have been obsoleted and Deploy will now always call the new asynchronous methods. Implementations should be updated to start using those instead.
PropertyTypeMigratorBase
and GridPropertyTypeMigratorBase
: the synchronous Migrate(...)
method is obsoleted and causes a compiler error when directly invoked (to avoid potential deadlocks, because it forwards to the asynchronous method using GetAwaiter().GetResult()
);
All property type migrator implementations inheriting from the above base classes have been updated to use the asynchronous methods as well.
AcceptInvalidCertificates
settingThe AcceptInvalidCertificates
setting previously configured the ServicePointManager
to accept all certificates. However, this class is obsoleted in .NET 9 and no longer affects HttpClient
.
Deploy uses a type of client to make HTTP requests between environments and this client can be configured to accept any certificate:
Umbraco CMS dependency was updated to 15.0.0
.
You can find the version-specific upgrade notes for versions out of support in the Legacy documentation on Github.
Get an overview of the things changed and fixed in each version of Umbraco Deploy.
In this section we have summarised the changes to Umbraco Deploy and Deploy Contrib released in each version. Each version is presented with a link to the Deploy issue tracker showing a list of issues resolved in the release. We also link to the individual issues themselves from the detail.
If there are any breaking changes or other issues to be aware of when upgrading they are also noted here.
If you are upgrading to a new major version you can find the details about the breaking changes in the version specific updates article.
This section contains the release notes for Umbraco Deploy 15 including all changes for this version.
Compatibility with Umbraco 15
See full details of breaking changes under the Version-specific Upgrade Guide
Removed AcceptInvalidCertificates
setting (configure DeployHttpClient
typed client instead)
Removed RemoteTreeNode
model (use RemoteTreeEntity
instead) and TryParseEntityIdFromNodeIdDelegate
(use TryParseUdiRangeFromNodeIdDelegate
instead) in DeployTransferRegisteredEntityTypeDetail
Added MigrateAsync(...)
method to IPropertyTypeMigrator
and updated PropertyTypeMigratorBase
and implementations to use async instead
Compatibility with Umbraco 15 and Deploy 15
Removed obsolete (and unused) legacy PrevaluePropertyValueArtifactMigratorBase
, CheckBoxListPropertyValueArtifactMigrator
DropDownListFlexiblePropertyValueArtifactMigrator
and RadioButtonListPropertyValueArtifactMigrator
migrators, as they are replaced with PrevalueArtifactMigrator
and property type migrators that support nested/recursive properties (see PR #71)
Removed MediaPickerDataTypeArtifactMigrator
, as it is replaced with ReplaceMediaPickerDataTypeArtifactMigrator
and DefaultLegacyDataTypeConfigurationArtifactMigrator
Removed MultiNodeTreePickerDataTypeArtifactMigrator
, as it is replaced with DefaultLegacyDataTypeConfigurationArtifactMigrator
You can find the release notes for versions out of support in the Legacy documentation on Github and Umbraco Deploy Package page
Umbraco Deploy is a commercial product. You will need a valid license to use the product.
A license for Umbraco Deploy is included when hosting on Umbraco Cloud.
Licenses are sold per domain and will also work on all subdomains. With every license, you will also be able to configure two development/testing domains.
Let's say that you have a license configured for your domain, mysite.com
, and you've configured two development domains, devdomain.com
and devdomain2.com
.
The license will cover the following domains:
localhost
*.mysite.com
www.mysite.com
mysite.com.local
devdomain.com
www.devdomain.com
devdomain2.com
www.devdomain2.com
You can have only 1 license per Umbraco installation.
There are a few differences as to what the licenses cover:
A single license covers one Umbraco solution. It includes all domains hosted by the solution, all production environments (if load-balancing), and all non-production environments.
To clarify the above:
You only need one license when you have a solution covering multiple domains- for example, www.mysite.com and www.mysite.dk - load balanced in production over multiple servers running from the same database, managed from the same backoffice instance, and with any number of non-production environments (staging, QA, etc.)
You need two licenses if you have a web presence that consists of two separate websites hosted on different domains or sub-domains - for example, www.mysite.com and shop.mysite.com - with each of these managed as a separate Umbraco installation using their own database and backoffice in production.
The license for Umbraco Deploy comes with a recurring yearly fee. Learn more about this and pricing on Umbraco.com.
You can look at the pricing, plans, features, and purchase the license on the Umbraco Deploy On-premises page.
Once you've configured your license with the correct domains, you are ready to install the license on your Umbraco installation.
For Umbraco Deploy On-Premise 12 and above, this will be a key provided to you when taking out your subscription to the product. It should be added to your configuration at the key Umbraco:Licenses:Umbraco.Deploy.OnPrem
.
For example, in appsettings.json
:
Umbraco Cloud projects use a license file placed in the /umbraco/Licenses
folder that is provided automatically when your project is created.
On start-up and on a schedule, Umbraco running Deploy On-premise will call out to a service. It will pass the configured license key to determine its validity. The response triggers a notification that the Umbraco Deploy will handle. It will amend the available functionality as appropriate to a valid, invalid or expired license.
You can view the status of the Umbraco Deploy On-premise license in the backoffice. This is available via the Settings section, listed along with any other products using the same licensing service:
UmbracoApplicationUrl
The website domain used for validating the license is determined from your Umbraco instance. To ensure the correct one is used, you can configure the UmbracoApplicationUrl
.
If you are running on a single domain for both your frontend and backend environments, it's not necessary to configure a UmbracoApplicationUrl
.
If you have different domains for your frontend and backend, then it's advised that you configure an UmbracoApplicationUrl
set to your backoffice URL. This helps the licensing engine know which URL should be used for validation checks. Without this configuration setting, the licensing engine will try and work out the domain to validate from the HTTP request object. This can lead to errors when switching between domains.
An UmbracoApplicationUrl
can be configured in your appSettings.json
file like so:
See the Fixed Application URL documentation for more details about this setting.
Some Umbraco installations will have a highly locked down production environment, with firewall rules that prevent outgoing HTTP requests. This will interfere with the normal process of license validation.
On start-up, and periodically whilst Umbraco is running, the license component used by Umbraco Deploy will make an HTTP POST request to https://license-validation.umbraco.com/api/ValidateLicense
.
If it's possible to do so, the firewall rules should be adjusted to allow this request.
If such a change is not feasible, there is another approach you can use.
You will need to have a server, or serverless function, that is running and can make a request to the online license validation service. That needs to run on a daily schedule, making a request and relaying it onto the restricted Umbraco environment.
To set this up, firstly ensure you have a reference to Umbraco.Licenses
version 13.1 or higher. This will be the case if you are running Umbraco Deploy 13.1 or higher. If you are on an earlier version, you can add a direct package reference for Umbraco.Licenses
.
Then configure a random string as an authorization key in configuration. This is used as protection to ensure only valid requests are handled. You can also disable the normal regular license checks - as there is no point in these running if they will be blocked:
Your Internet enabled server should make a request of the following form to the online license validation service:
The response should be relayed exactly via an HTTP request to your restricted Umbraco environment:
A header with a key of X-AUTH-KEY
and value of the authorization key you have configured should be provided.
This will trigger the same processes that occur when the normal scheduled validation completes ensuring your product is considered licensed.
Documentation on how to work with Umbraco Deploy.
This is the documentation for the Umbraco Deploy 15 Release Candidate.
This version of the Umbraco Deploy documentation is currently slimmed down to contain only new and updated material related to the upcoming release.
Due to the above, some links might reference the GitHub file instead of the GitBook article.
Umbraco Deploy is a deployment tool that helps you with the process of transferring code and data between multiple environments. Deploy can be configured for many different setups and is great for both small setups as well as large and more complex infrastructures.
Umbraco Deploy is also the engine that runs behind the scenes on Umbraco Cloud. Here it takes care of all the deployment processes of both code, schema and content on projects.
With Umbraco Deploy you get to use the Umbraco Cloud Deployment technology outside of Umbraco Cloud to ease deployment between multiple Umbraco environments. This is done by connecting external hosted Umbraco projects with a local instance of your Umbraco website.
In the Umbraco Deploy documentation can read all about how to set up and work with Umbraco Deploy.
You can find articles about how to set up Umbraco Deploy on a new or an existing website, and articles about the deployment workflow.
How does Umbraco Deploy work and how to get started using Umbraco Deploy
In this article you can learn more about what it takes to get started using Umbraco Deploy. You can also get a high-level overview of how the product works.
Umbraco Deploy works by serializing non-content Umbraco items (called “Schema” items) to disk. These serialized files are located in the /umbraco/Deploy/Revision
folder at the root of your website.
These items are entities like Document Types, Media Types, Data Types, etc, and these files must be committed to source control (for example Git). Umbraco Deploy works by “extracting” this serialized information back into your Umbraco installation. This is done by deployment triggers when a deployment is sent to a target environment.
For example, when working locally you might create a new Document Type. This will automatically create a new on-disk file in the umbraco/Deploy/Revision
folder which is the serialized version of the new Document Type. You would then commit this file to your repository and push this change to your hosted source control (for example GitHub).
When you want this deployed to your next environment, you would trigger your CI/CD process (for example Azure DevOps or Github Actions). This will push the changes to your environment. Once the build deployment completes successfully, a Deployment Trigger would be executed as an HTTPS request to your target environment. All changes found in the umbraco/Deploy/Revision
folder will then be extracted into the Umbraco target environment.
There are three main steps you need to go through in order to start using Umbraco Deploy on your website.
Set up Git repository and new Umbraco project
Set up a repository and then install a new Umbraco project inside it.
Install Umbraco Deploy via NuGet
Umbraco Deploy can be installed via NuGet.
Umbraco Deploy needs a CI/CD build server needs to be set up to run when you want changes to be deployed to next upstream environment
A description of the proper workflow when working with Umbraco Deploy
Umbraco Deploy uses a deployment model that relies on Git and Umbraco Deploy core technology to move your changes from one environment to another. Umbraco Deploy uses a classic "left to right" deployment model, meaning that changes are first made in the Development or local environment and then deployed to the production environment.
If your project contains a Staging environment, deployments will be made from Development to Staging and then from Staging to Live.
Umbraco Deploy uses a two-part deployment approach where we keep meta data (Document types, templates, etc) and content (Content nodes and Media) as separate parts of a deployment. In order to be able to distinguish between the two types of deployments we use the term transfer for content and media deployments and the term deploy for meta data deployments.
In summary:
Meta data such as Document Types, Templates, Forms, Views and config files are stored in a repository and are deployed between environments. This can be achieved using a CI/CD deployment pipeline with something like Github Actions or Azure DevOps.
Content and Media items are not stored in the repository. These need to be transferred directly from the Umbraco backoffice using the "Queue for Transfer" option. Once a content editor has all the items needed for a transfer they will use the Deployment Dashboard in the Content section to transfer the items in the queue.
In order to be able to transfer content and media, the source environment and the target environment needs to have the same setup - meaning they need to be completely in sync and have the same file structure. To achieve this you need to deploy your meta data changes to the target environment.
Moving your content and media between your environments is done through the Umbraco backoffice. You can transfer content from one environment to another, e.g. from local to your development environment. You also have the option to restore content and media to your local or development environment from your production or staging environment.
Transferring and restoring content and media is the same whether you are working locally and transferring between two environments.
Another approach for transferring content and schema between environments is to use import and export. In one environment, you can export selected content, a tree, or the whole workspace to a .zip file. There are options to include related media files, schema and code files such as templates and stylesheets.
That .zip file can then be uploaded into a new environment, where it will be validated and then processed to update Umbraco.
As part of the import process, we provide hooks to allow for migrations of the imported artifacts (like data types) and property data. This should allow you to migrate your Umbraco data from one Umbraco major version to a newer one.
We recommend using the content and media backoffice transfer options for day-to-day editorial activities. Import and export is intended more for larger transfer options, project upgrades, or one-off tasks when setting up new environments.
Read more about the import and export feature.
In Umbraco Deploy we have included a Deploy Dashboard in the Settings section of the Umbraco backoffice to make it easier to run operations like schema deployment from data files and extract schema to data files.
When running the extract schema to data files
operation, Umbraco Deploy will run an echo > deploy-export
in the data folder of your project which is used to generate UDA files based on the schema in your database.
Running the schema deployment from data files
operation will initiate an extraction on the environment
The extraction will end in one of two possible outcomes:
deploy-complete
: The extraction succeeded and your environment is in good shape!
deploy-failed
: The extraction failed - open the deploy-failed file, to see the error message.
It is also possible to see which version of Umbraco Deploy you are running, when the last operation was started and the status of the deployment operation.