Installing Invictus Dashboard

Prerequisites
obtain access Shared
To access the resources stored on Azure Storage and Azure Container Registry you have to request an SAS-token and ACR Password from coditproducts@codit.eu.
Container revisions
We use Multiple Revision mode in our Container App deployments, which means that older revisions could clutter the Container App Environment. We provide a clean-up script that should be run after logging in on the correct subscription, but can be ran in Azure DevOps Pipelines as well.
Include VNET support Shared
Invictus includes network infrastructure which allows all its resources to run within an Azure Virtual Network (VNET).
Required deployment

An Azure Virtual Network

Including two subnets, one each for:

Private Endpoints

Container App Environment

The subnets must have the following services enabled

Microsoft.AzureCosmosDB

Microsoft.EventHub

Microsoft.KeyVault

Microsoft.ServiceBus

Microsoft.Storage

The Container App subnet must also have the delegation Microsoft.App/environments

Private DNS Zones (Bicep template)

privatelink.azurecr.io

privatelink.blob.core.windows.net

privatelink.file.core.windows.net

privatelink.mongo.cosmos.azure.com

privatelink.queue.core.windows.net

privatelink.servicebus.windows.net

privatelink.table.core.windows.net

privatelink.table.cosmos.azure.com

privatelink.vaultcore.azure.net

privatelink.{regionName}.azurecontainerapps.io

To be able to deploy the app code from an Azure DevOps pipeline you require a self hosted agent running on the same VNET with the following software installed:

PowerShell

Azure PowerShell

Bicep CLI

Required role assignment
If the Invictus resources and the VNET are on different resource groups, then you need to assign the role of Network Contributor to the Invictus resource group onto the VNET resource group.

Download

Include the Dashboard in your release package to deploy the Invictus Dashboard together with your customer solution.

Save installation script to your repository Shared

The Invictus-GetSources.ps1 script pulls the latest Invictus resources needed to deploy the Dashboard.

Add variables to variable group Shared

Invictus installation requires secrets for authentication. Codit Software provides these for you. Create a variable group for them:

{'{prefix}'}.Invictus.Installation
- Invictus.Installation.StorageAccount.Name: invictusreleases
- Invictus.Installation.StorageAccount.Dashboard.SasToken: value provided by Codit Software
- Invictus.Installation.StorageAccount.Framework.SasToken: value provided by Codit Software (if you're also deploying the Framework)
- Infra.Environment.ACRUsername: value provided by Codit Software
- Infra.Environment.ACRPassword: value provided by Codit Software

Add YAML build pipeline

Add a YAML pipeline to build the Invictus for Azure Dashboard. Change the following example file according to your needs, for example change the trigger path:

  paths:
    include:
    - /src/customer.azure.invictus

Full YAML build pipeline example

pr: none
trigger:
  branches:
    include:
    - main
    - feature/*
  paths:
    include:
    - /src/customer.azure.invictus

parameters:
- name: Version
  displayName: Invictus Version
  type: string
  default: '*'
- name: useBeta
  displayName: Use Beta
  type: string
  default: $False

pool:
  vmImage: 'windows-latest'

stages:
- stage: Package
  displayName: Package
  dependsOn: []
  variables:
  - group: prefix.invictus.installation
  jobs:
  - job: publish
    displayName: Build and Publish Dashboard
    steps:
    - checkout: self
      clean: true
      persistCredentials: true

    - task: PowerShell@2
      displayName: 'Pull Invictus sources'
      inputs:
        targetType: filePath
        filePath: './scripts/Invictus-GetSources.ps1'
        arguments: >
          -StorageAccountName '$(Invictus.Installation.StorageAccount.Name)'
          -StorageSasToken '$(Invictus.Installation.StorageAccount.Dashboard.SasToken)'
          -StorageContainerName 'dashboard-v2'
          -SaveLocation '$(Build.ArtifactStagingDirectory)'
          -UseBeta ${{parameters.useBeta}}
          -Version ${{ parameters.version }}
              
    - task: PublishPipelineArtifact@1
      inputs:
        TargetPath: $(Build.ArtifactStagingDirectory)
        ArtifactName: dashboard-v2
        publishLocation: 'pipeline'

Deploy

Create variable group Shared

Create a variable group (recommended: {prefix}.Invictus.{env}) for each the environments. The deployment uses this variable group and edits/adds variables based on the Bicep deployment output.

permit build service access to variable groups

Make sure the Project Collection Build Service has Administrator access to these variable groups (Pipelines > Library > Security)

Use `Deploy.ps1` script for deployment

The Deploy.ps1 PowerShell script is available in the downloaded Invictus sources. This should be the main point of contact for deploying Invictus products.

Least-privileged Azure role assignments for the deploying identity

The identity running the Bicep deployment (the service principal used by your Azure DevOps service connection) needs the following least-privileged roles assigned on the target resource group or subscription:

Role	Why It's Needed
`Container Apps Contributor`	Create/update Container Apps environments, apps, authentication configurations and job definitions.
`Azure Event Hubs Owner`	Create/update Event Hubs namespaces, hubs and network rule sets.
`Container Registry Contributor`	Create/update Azure Container Registry instances, locks, and network settings.
`DocumentDB Account Contributor`	Create/update Cosmos DB accounts, MongoDB databases and collections.
`Managed Identity Contributor`	Create/update user-assigned managed identities for Container Apps and functions.
`Key Vault Administrator`	Create/update Key Vaults, access policies and network ACLs.
`Log Analytics Contributor`	Create/update Log Analytics workspaces and list workspace keys.
`Monitoring Contributor`	Create/update Application Insights components and associated locks.
`Network Contributor`	Create/update private endpoints, VNET subnets and private DNS zone groups.
`Reader`	Read existing Private DNS zones when linking DNS zone groups for private endpoints.
`Service Bus Data Owner`	Create/update Service Bus namespaces, queues and network rule sets.
`Storage Account Contributor`	Create/update storage accounts, file shares, blob, and table services.
`User Access Administrator`	Create role assignments (`Microsoft.Authorization/roleAssignments`) and resource locks.

heavy load deployment

Carefully consider the Bicep scaling parameters on Azure Container Apps and Cosmos DB for heavy load scenarios that require many diagnostic trace imports.

Mandatory Parameters

Argument name	Description
`arcName`	The name of the Azure Container Registry name to deploy the container images to. (Make sure to override also the `containerRegistryName` Bicep parameter if you want a custom name.)
`arcPath`	The Azure Container App registry base path to form the source image location of the container images.
`arcUsername`	The username credential to authenticate the Docker CLI.
`arcPassword`	The password credential to authenticate into the Docker CLI.
`resourcePrefix`	Prefix used for deployed Azure resources (ex. `invictus-{prefix}-vlt`)
`resourceGroupName`	Name of Azure resource group where Invictus deploys to.
`variableGroupName`	DevOps variable group to write the Bicep outputs to (ex. `Invictus_CosmosDb_DbName`)
`azureActiveDirectoryClientId`	See Microsoft Entra ID Setup if enabled.
`azureActiveDirectoryTenantId`	See Microsoft Entra ID Setup if enabled.
`azureActiveDirectoryClientSecret`	See Microsoft Entra ID Setup if enabled.
`azureActiveDirectoryAudience`	See Microsoft Entra ID Setup if enabled.
`performSqlDataMigration`	If value is 1 the data migration process runs during installation, migrating SQL data to Cosmos DB. If the value is `0`, the installation skips this process. See the migration guide for more details. Once the installation performed the data migration and you verified the outcome, set this value to `0` so the installation skips the migration process for all future deployments.
`flowDataTTLInDays`	Amount of days flow traces can live in the database See import flow traces.
`isProvisionedCosmos`	If the value is 1, the installation deploys a Cosmos DB with provisioned throughput. Otherwise, a serverless Cosmos DB. How to choose between provisioned and serverless.
`identityProviderApplicationId`	See Container Authentication.
`identityProviderClientSecret`	See Container Authentication.

Optional Parameters

Argument name	Default value	Description
`acrEnvironment`	`prod`	The environment from where the script pulls the Invictus artifacts. (`prod`, `beta` or `staging`). New since v6.3
`additionalTemplateParameters`	[]	Optional named parameters for the Bicep template you wish to override. More on this below.
`artifactsPath`	`$PSScriptRoot`	Path on the DevOps agent where you downloaded the Invictus artifacts (publish and download build artifacts)
`enableVnetSupport`	`False`	Deploys Invictus into a VNET.
`isAdDisabled`	`False`	Boolean flag to activate Entra ID authentication in the Dashboard.
`resourceGroupLocation`	`West Europe`	Azure location where you want the Invictus resources deployed.
`sqlToMigrateServerName`	`invictus-{$resourcePrefix}-sqlsvr`	The name of the SQL Server to migrate from. Only used when `performSqlDataMigration=1`.
`sqlToMigrateDBName`	`coditcip`	The name of the SQL Database to migrate from. Only used when `performSqlDataMigration=1`.
`sqlToMigrateUserName`	`InvictusFrameworkAdmin`	The username of the SQL Database to migrate from. Only used when `performSqlDataMigration=1`.
`translateBicepOutput`	`False`	If set to `True`, translates the Bicep outputs (`_` becomes `.`) before placing them in an Azure DevOps variable group.
`validateOnly`	`False`	If set to `True`, the Bicep deployment only validates the template and doesn't deploy any resources.
`version`	`latest`	Version of the published Invictus artifacts that the deployment should download and deploy on the client environment.
`useBeta`	`$null`	Indicates the environment of the Azure Container App registry where the deployment gets its container images. Deprecated since v6.3

Full YAML task example

- task: AzureCLI@2
  displayName: 'Azure CLI'
  env:
    SYSTEM_ACCESSTOKEN: $(System.AccessToken)
  inputs:
    azureSubscription: '[YOUR_SERVICE_CONNECTION]'
    scriptType: 'pscore'
    scriptLocation: 'inlineScript'
    inlineScript: |

      # Determine where the the provided Invictus 'Deploy.ps1' script is located
      $artifactsPath = ${{ variables['Pipeline.Workspace'] }} + '/_build/dashboard' 
      $scriptPath = $artifactsPath + '/Deploy.ps1'

      & $scriptPath `
        -artifactsPath $artifactsPath `
        -acrPath 'invictusreleases.azurecr.io' `
        -useBeta false `
        -acrUsername 'admin' `
        -acrPassword '<pass>' `
        -resourcePrefix 'dev' `
        -resourceGroupName 'my-client-dev-rg' `
        -variableGroupName 'My.Client.Dev' `
        -performSqlDataMigration 0 `
        -isProvisionedCosmos 0 `
        -azureActiveDirectoryClientId '4b559bfb-871a-4013-bce9-829e3aeb6bdd' `
        -azureActiveDirectoryTenantId '97a944a1-04a0-45d2-b2f3-c424755c4167' `
        -azureActiveDirectoryClientSecret '<pass>' `
        -azureActiveDirectoryAudience 'https://contoso.com' `
        -identityProviderApplicationId 'c84d34ea-f169-4787-a4af-81750debda0b' `
        -identityProviderClientSecret '<pass>' `
        -isProvisionedCosmos 1 `
        -flowDataTTLInDays 90

Full YAML release pipeline example

pr: none
trigger: none

resources:
  pipelines:
    # Name of the pipeline resource inside this workflow. Used to reference the pipeline resources later on (e.g. download artifacts).
  - pipeline: _build
    # Name of the pipeline in Azure Pipelines
    source: 'customer.azure.invictus.dashboard.build' 
    trigger: true

parameters:
  - name: "Version"
    type: string
    default: "latest"
  - name: "UseBeta"
    type: string
    default: "$false"

pool:
  vmImage: 'ubuntu-latest'

stages: 
- stage: deploy_dev
  displayName: 'Deploy to Development'
  variables:
  - group: infra.dev
  - group: prefix.invictus.dev
  - group: prefix.invictus.installation
  jobs:
  - deployment: deploy_development
    displayName: 'Deploy to Development'
    environment: Development
    strategy:
      runOnce:
        deploy:
          steps:
          - download: '_build'
            displayName: Download Artifact
          - task: AzureCLI@2
            env:
              SYSTEM_ACCESSTOKEN: $(System.AccessToken)
            inputs:
              azureSubscription: 'NameOfYourServiceConnection'
              scriptType: 'pscore'
              scriptLocation: 'scriptPath'
              ScriptPath: '$(Pipeline.Workspace)/_build/dashboard-v2/Deploy.ps1'
              ScriptArguments: '-version ${{parameters.Version}} -useBeta ${{parameters.UseBeta}} -acrPath "invictusreleases.azurecr.io" -acrUsername $(Infra.Environment.ACRUsername) -acrPassword $(Infra.Environment.ACRPassword) -resourcePrefix $(Infra.Environment.ResourcePrefix) -artifactsPath $(Pipeline.Workspace)/_build/dashboard-v2 -resourceGroupName $(Infra.Environment.ResourceGroup) -variableGroupName invictus.$(Infra.Environment.ShortName) -devOpsObjectId "$(Infra.DevOps.Object.Id)" -azureActiveDirectoryClientId "$(Infra.AzAD.Client.Id)" -azureActiveDirectoryTenantId "$(Infra.DevOps.Tenant.Id)" -azureActiveDirectoryClientSecret "$(Infra.AzAD.Client.Secret)" -azureActiveDirectoryAudience "$(Infra.AzAd.Audience)" -identityProviderApplicationId "$(Infra.AzAD.Client.IdentityProviderApplicationId)"  -identityProviderClientSecret "$(Infra.AzAD.Client.IdentityProviderClientSecret)" -performSqlDataMigration 0 -isProvisionedCosmos 0 -flowDataTTLInDays 90 -containerAppsEnvironmentLocation "$(Infra.Environment.ContainerAppsEnvironmentLocation)"'

- stage: deploy_prd
  displayName: 'Deploy to Production'
  dependsOn: deploy_acc
  variables:
  - group: infra.prd
  - group: prefix.invictus.prd
  - group: prefix.invictus.installation
  jobs:
  - deployment: deploy_prd
    displayName: 'Deploy to Production'
    environment: Production
    strategy:
      runOnce:
        deploy:
          steps:
          - download: '_build'
            displayName: Download Artifact
          - task: AzureCLI@2
            env:
              SYSTEM_ACCESSTOKEN: $(System.AccessToken)
            inputs:
              azureSubscription: 'NameOfYourServiceConnection'
              scriptType: 'pscore'
              scriptLocation: 'scriptPath'
              ScriptPath: '$(Pipeline.Workspace)/_build/dashboard-v2/Deploy.ps1'
              ScriptArguments: '-version ${{parameters.Version}} -useBeta ${{parameters.UseBeta}} -acrPath "invictusreleases.azurecr.io" -acrUsername $(Infra.Environment.ACRUsername) -acrPassword $(Infra.Environment.ACRPassword) -resourcePrefix $(Infra.Environment.ResourcePrefix) -artifactsPath $(Pipeline.Workspace)/_build/dashboard-v2 -resourceGroupName $(Infra.Environment.ResourceGroup) -variableGroupName invictus.$(Infra.Environment.ShortName) -devOpsObjectId "$(Infra.DevOps.Object.Id)" -azureActiveDirectoryClientId "$(Infra.AzAD.Client.Id)" -azureActiveDirectoryTenantId "$(Infra.DevOps.Tenant.Id)" -azureActiveDirectoryClientSecret "$(Infra.AzAD.Client.Secret)" -azureActiveDirectoryAudience "$(Infra.AzAd.Audience)" -identityProviderApplicationId "$(Infra.AzAD.Client.IdentityProviderApplicationId)"  -identityProviderClientSecret "$(Infra.AzAD.Client.IdentityProviderClientSecret)" -performSqlDataMigration 0 -isProvisionedCosmos 0 -flowDataTTLInDays 90 -containerAppsEnvironmentLocation "$(Infra.Environment.ContainerAppsEnvironmentLocation)"'

Bicep Template Parameters

Use arrow keys to navigate rows. Press Enter or Space to expand a row with sub-properties. Press / to focus the search field.

Press / to filter

First-time sign-in
The Invictus installation generates an administrator account for your initial login to the Dashboard.
recommended
Create a new System Admin user with your own email address after signing in for the first time. This will help during the Forgot Password procedure.
Follow the steps below to sign in to the Dashboard:
1. Navigate to the Dashboard by visiting https://{yourdashboardurl} in your web browser.
2. Enter the following credentials:
  - Username: admin
  - Password: (the tempAdminPassword available as an Azure Key vault secret in the accompanied deployed vault)
3. After successfully signing in, the Dashboard prompts you to reset your password to one of your choice.
4. You have now signed in to the Invictus Dashboard for the first time.
Further customer-specific setups related to authentication and authorization:
- Give access to your Microsoft Entra ID
- Give access to your Logic Apps

Prerequisites

Required deployment​

Required role assignment​

Download

Save installation script to your repository Shared​

Add variables to variable group Shared​

Add YAML build pipeline​

Deploy

Create variable group Shared​

Use Deploy.ps1 script for deployment​

Mandatory Parameters​

Optional Parameters​

Bicep Template Parameters​

First-time sign-in

Required deployment

Required role assignment