How to Use the Onion DevOps Project Template

The Onion-DevOps-Architecture project now is available as an Azure DevOps template. This will allow you to get up and running with the end-to-end Onion DevOps sample code and AzDo pipelines.

The import of the template gets you about 90% of the way. This post will take you from importing the template to running the site. It focuses on getting the template imported, built, and running. Details about the Onion DevOps Architecture can be found on the github site, or in Jeffery Palermo’s book.

Creating a New Project from the Onion DevOps Template

Open the Azure DevOps Demo Generator site and login with your Azure account. When you login you’ll be on the Create New Project page. Click Choose template in the dialog (best to do that first since currently the other fields clear when you return).

On the next page, you’ll be able to select the template. Click DevOps Labs and find the Onion DevOpstemplate and select it.

NOTE the template isn’t in DevOps Labs yet. For NOW, you have to log in to https://azuredevopsdemogenerator.azurewebsites.net/?enableextractor=true and then you’ll have a Private tab for selecting a template and can upload a zip someone kindly supplied you (for a nominal number of YEI points).

Back on the Create New Project page, select your AzDo Organization, and give the project a name. You may see a warning below indicating that the organization is missing some extensions used by the template. You must check the boxes to continue.

Click Create Project and a progress bar (you may have to scroll down) will show the new project being created. In a few minutes the Navigate to project button will light up and you’re ready to get going!

You should make sure that the import succeed by quickly poking around the new project. It should have the following:

• One Repo, with files
• One Build pipeline
• One Release pipeline
• The Board should have:
  • a Board with four swimlanes, Proposed, Ready, In Progress, and Done
  • Five sprints in the Backlogs

If things don’t look correct, there may be permission issues. Check with the administrator of the template project.

Preparing the New Onion DevOps Project

For security reasons, sensitive data is not imported from the source Project. Therefore you have a bit of configuration to do before you’ll be able to build and deploy the code. Also the pipelines have values to some items by GUID, that won’t be in your project, and must be changed.

Azure Setup

In the build pipeline Variable is a DatabaseResourceGroupName that is set to BuildDatabases-$(System.TeamProject)-$(Build.DefinitionName). This will evaluate to BuildDatabases-Onion-DevOps-Architecture-Onion-DevOps-Architecture-CI at build time, so you must create a Resource Group in Azure with that name. Note the subscription you use since you’ll need that in the next steps.

Application Insights

The release pipeline will log to Azure’s Application Insights. You will need this configured for the subscription you used above. You may want to do this step at the same time you update the Release pipeline below since the three values you copy here are needed there.

1. Open the Application Insights blade in the Azure Portal
2. Click Add to add a new one (or use an existing one if you prefer)
3. In the Overview, copy the Instrumentation Key to an editor or somewhere you can use it for pasting later.
4. In API Access and copy the Application ID like the key.
5. Click Create API Key to generate a new one with full access, and copy it, too.

Azure DevOps Setup

The connection to Azure that is imported is specific to the original environment, so a new one must be created. Click Project Settings in the lower left and then click Service connections You should see a service connection called DeleteThis . Disconnect that connection. Create a new one with these steps, or you can use an existing connection.

1. Click New service connection
2. Select Azure Resource Manager
3. Give it a meaningful name
4. Select the Azure subscription
5. Do not select a Resource Group

To publish your builds, you need an Artifact Feed. To create one do the following:

1. Click on the Artifacts icon on the left.
2. Click the + New Feed link
3. Give it a name such as OnionDevOps and note it since you will need it in the next step.

The Build Pipeline

1. Click the Pipeline->Builds icon on the left. You should see the Onion-DevOps-Architecture-CI build pipeline
   
2. Click the Edit button in the upper right. You should see the tasks for the build.
3. You will notice some say Some settings need attention. All of these require the Azure Subscription, and optionally Location to be set. For each one:
   1. Open the task
   2. Select the Azure subscription (the Service connection name from above)
   3. Set the Location, if needed.
4. Click the NuGet push build task.
   1. The Target Feed will have an invalid value imported into it.
   2. Select the feed you created earlier.
5. Click the Variables link near the top.
   1. Change the DatabasePassword value by unlocking it (even though it shows ****, it doesn’t have a value)
   2. Set it to a super-secret password
   3. Lock it back up.
6. Click Save and queue, the Run to start a build. The build will need to succeed before you can continue.

The Release Pipeline

After the build runs successfully, you should have a failed TDD release pipeline. At this point you can finish configuring the Release pipelines.

1. Click the Releases icon on the left . You should see the Azure PaaS Pipeline release pipeline.
2. Click the Edit button in the upper right. You will see three stages, TDD, UAT, and Prod.
3. For each TDD, UAT, and Prod
4. Like the build, some tasks say Some settings need attention. All of these require the Azure Subscription, and optionally Location to be set. For each one:
   1. Open the task
   2. Select the Azure subscription (the Service connection name from above)
   3. Set the Location, if needed.
5. For the four tasks that download a package, the Feed must be set to the feed you created earlier (OnionDevOps) , and then select the appropriate package. If you don’t have any packages to select from, make sure you have a good build.
   1. Obtain Database Package is OnionDevOpsArchitecture.Database
   2. Obtain UI Package is OnionDevOpsArchitecture.UI
   3. Obtain Job Package is OnionDevOpsArchitecture.Job
   4. Obtain Acceptance Test Package is OnionDevOpsArchitecture.AcceptanceTests
6. Click on the Pipeline tab at the top to get the view of the stages.
   1. Click on the Prod Pre-deployment conditions button
   2. Change the Approvers to be a valid user.
7. Click the Variables link near the top.
   1. Change the DatabasePassword value by unlocking it, setting it to a super-secret password, then locking it back up. You may get login errors if it is not locked!
   2. The Azure Application Insight values from above also must be set. The variables to set are AppInsightsApiKey (secret), AppInsightsApiKey and
ApplicationInsights.InstrumentationKey. The template has a separate value for each stage. You can using the same one for each stage.
   3. To make a unique URL that won’t collide with others, put something in UniquePrefix like your initials.

Now, you can create a new Release. You probably have a failed TDD build that was kicked off when you did the build, before updating the Release pipeline. You can now click Create release to create a new one (simply re-deploying the failed one won’t pick up your changes to the pipeline).

The TDD stage should starting running. By default the TDD and UAT stages are not gated, and will deploy for each build. Prod requires you to approve it before deploying.

Release Troubleshooting

The nuget command failed with exit code(1) make sure that Target Feed of the NuGet push task is set.

Failure: Login failed for user ‘dbuser’. when creating the database is probably due to not locking (encrypting) the DatabasePassword

Cannot bind argument to parameter ‘apiKey’ because it is an empty string. The Application Insight values need to be set, including the secret AppInsightsApiKey

Failed in downloadPackage with error make sure the package download task have valid values.

Accessing the Site

Once you have a green build, you can access the sample site. You can find the URL for it in Azure, by browsing in the App Services blade, or searching for ui-master, which should return the app. It will have your UrlPrefix and the build number. Something like Prod-ZZZ-UI-master-15

Final Thoughts on the Onion DevOps Architecture

The Azure DevOps Demo Generator site provides a quick way for you to get some sample code up and running in no time. The Onion DevOps Architecture is a great sample that gives you all the basics to get an application up and running in Azure DevOps. Check out the Jeffery Palermo’s book for a thorough discussion on the topic.

Originally published September 9, 2019. Information refreshed June 8, 2022.