Installing Umbraco Deploy
In this article, we will cover the steps in order for you to install and configure Umbraco Deploy on a new or existing website.
Prerequisites
Ensure to first read and follow the setup guides for either new or existing projects below:
Source Control Configuration
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.
Installing and Configuring Umbraco Deploy
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 Editor - there is one further NuGet package to install: Umbraco.Deploy.Contrib
.
When Umbraco Deploy has been installed, to be able to use it in the project you will need to create and add configuration for an API key.
The API key should be a randomly generated string of 64 characters (recommended). The minimum requirement is 10 characters.
You can use the following C# code to generate the API key:
Or by running the following PowerShell command:
This same Deploy API key must be used on each environment for the same website.
We strongly recommend generating different keys for different websites/projects.
The key should be applied in appsettings.json
.
Configuring Environments
Once the API key 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.
Validating Source Control
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.
Include your Umbraco Deploy license file
Before moving on to setting up the build server, make sure that your license is included in your project.
The file needs to be placed in the /umbraco/Licenses
folder.
Read more about the Umbraco Deploy licensing model.
Last updated