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.

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.

using System;
using System.Security.Cryptography;

byte[] secret = new byte[64];
RandomNumberGenerator.Create().GetBytes(secret);
string apiSecret = Convert.ToBase64String(secret);

Console.Write(apiSecret);

$secret = [byte[]]::new(64); [System.Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($secret); return [System.Convert]::ToBase64String($secret)

{
  "Umbraco": {
    "Deploy": {
        "Settings": {
            "ApiSecret": "<your API secret here>",
        }
    }
  }
}

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());

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

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

Configuring Environments

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:

{
   "Umbraco": {
      "Deploy": {
         "Settings": {
            "ApiSecret": "<your API secret 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.

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": {
    "CMS": {
      ...
    },
    "Licenses": {
      "Umbraco.Deploy.OnPrem": "<your license key>"
    },
    "Deploy": {
       ...
    }

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.