Installing Umbraco Deploy

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.

**/media/*

# Umbraco deploy specific
**/umbraco/Deploy/deploy*

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:

using System;
using System.Security.Cryptography;

byte[] secret = new byte[32];
RandomNumberGenerator.Create().GetBytes(secret);

var apiKey = new StringBuilder(secret.Length * 2);
for (int i = 0; i < secret.Length; i++)
{
   apiKey.AppendFormat("{0:X2}", secret[i]);
}

Console.Write(apiKey.ToString());

Or by running the following PowerShell command:

$secret = [byte[]]::new(32); [System.Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($secret); return -join ($secret | %{ '{0:X2}' -f $_ })

This same Deploy API key must be used on each environment for the same website.

The key should be applied in appsettings.json.

{
  "Umbraco": {
    "Deploy": {
        "Settings": {
            "ApiKey": "<your API key here>",
        }
    }
  }
}

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:

{
   "Umbraco": {
      "Deploy": {
         "Settings": {
            "ApiKey": "<your API key here>"
         },
         "Project": {
            "CurrentWorkspaceName": "Live",
            "Workspaces": [
               {
                  "Id": "efef5e89-a19b-434b-b68a-26e022a0ad52",
                  "Name": "Live",
                  "Type": "live",
                  "Url" :"https://localhost:44307"
               }
            ]
         }
      }
   }
}

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:

1. Open "Tools".

2. Select "Create GUID".

3. Use the Registry Format.

4. Copy the GUID into the id value.

5. Generate a "New GUID" for each environment you will be adding to your setup.

Or by running the following PowerShell command:

[guid]::NewGuid().ToString()

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.