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.
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.
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.
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.
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.
Last updated