Deploy OSDU Admin UI on top of Azure Data Manager for Energy

This guide shows you how to deploy the OSDU Admin UI on top of your Azure Data Manager for Energy (ADME) instance.

The OSDU Admin UI enables platform administrators to manage the Azure Data Manager for Energy data partition that it connects to. Management tasks include entitlements (user and group management), legal tags, schemas, reference data, and viewing and visualizing objects on a map.

Prerequisites

• An Azure Data Manager for Energy instance.

• A Microsoft Entra ID App Registration.
  This app registration can be the same as the one used for the Azure Data Manager for Energy instance. The following API permissions are required on the app registration for the Admin UI to function properly.

  • Application.Read.All
  • User.Read
  • User.ReadBasic.All

  Upon first sign-in to the Admin UI, the application requests the necessary permissions. You can also grant the required permissions in advance. For more information, see Configure app access to web APIs.

Deployment options

There are two deployment options for the OSDU Admin UI:

1. Quick-deploy using Azure Container Apps: A one-click deployment using Azure Container Apps. This option is the fastest way to deploy the OSDU Admin UI and supports both public and private deployments.
2. Custom deployment using Azure Storage Account Static Website: Build and deploy the OSDU Admin UI by using Azure Storage Account Static Website. This option is more customizable and allows you to tailor the deployment to your requirements.

Quick-deploy with Azure Container Apps

1. Select the Deploy to Azure button to deploy the OSDU Admin UI using Azure Container Apps.

   

2. Fill in the required parameters in the Azure portal. For more information about the parameters, see the parameters section.

   

3. Select Review + create and then Create to deploy the OSDU Admin UI.

4. Check the Outputs section for the URL of the deployed OSDU Admin UI.

5. Configure the ADME CORS policy and App Registration SPA redirect URI with the website URL.

6. Open the URL in a browser and validate that it's working correctly and connected to the correct Azure Data Manager for Energy instance.

Parameters

Parameter	Description	Required
Subscription	The Azure subscription to deploy the OSDU Admin UI to.	Yes
Resource group	The resource group to deploy the OSDU Admin UI to.	Yes
Region	The Azure region to deploy the OSDU Admin UI to.	Yes
Name	The name of the OSDU Admin UI instance. Other resources use this name as the base-name and append a service abbreviation.	Yes
Container Image	The container image to use for the OSDU Admin UI. See OSDU Forum Admin UI Container Registry for available images.	Yes
OSDU Endpoint	The endpoint of the Azure Data Manager for Energy or OSDU instance to connect to. Use the base ADME endpoint. The deployment normalizes it for the container runtime.	Yes
Data Partition IDs	Comma-separated list of data partition IDs of the Azure Data Manager for Energy or OSDU instance to connect to.	Yes
Entitlements Domain Name	The domain name to use for the entitlements service. Keep .dataservices.energy for any ADME deployment, only update if you're using another OSDU implementation.	Yes
Client ID	The client ID of the App Registration to use for the OSDU Admin UI.	Yes
Scope	The scope of the App Registration used by Azure Data Manager for Energy or OSDU. If the Client ID is the ADME App Registration, you can leave this default.	Yes
Connector Endpoint	Optional: The OSDU Admin UI Connector API endpoint to use for the Admin UI.	No
GCZ Endpoint	Optional: Base GCZ endpoint ending with /gcz/. Example: https://contoso.energy.azure.com/api/gcz/. GCZ must already be deployed separately.	No
Enable Private Network	Optional: Enable private network access to the OSDU Admin UI.	No
Enable Logging	Optional: Enable logging for the OSDU Admin UI.	No

Custom deployment using Azure Storage Account Static Website

Prepare your computer

• Install Visual Studio Code with Dev Containers. You can deploy the OSDU Admin UI from your local computer by using either Linux or Windows Subsystem for Linux (WSL). We recommend using a Dev Container to reduce tooling and environment conflicts.

Environment setup

1. Use a Dev Container in Visual Studio Code to reduce conflicts with locally installed tools.

2. Select Remote - Containers | Open to open a Development Container and clone the OSDU Admin UI repository.

   

3. Accept the cloning prompt.

   

4. When prompted for a container configuration template:

   1. Select Ubuntu.
   2. Accept the default version.
   3. Don't add any extra features.

5. After a few minutes, the devcontainer is running.

   

6. Open the terminal.

   

7. Install Angular CLI, Azure CLI, npm, and Node Version Manager (NVM).

   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash && \
   export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")" && \
   [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh" && \
   nvm install 20.19.6 && \
   export NG_CLI_ANALYTICS=false && \
   npm install -g @angular/cli@13.3.9 && \
   sudo apt-get update && \
   sudo apt-get install -y jq && \
   curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash
   

   

8. Log into Azure CLI by executing the command in the terminal.

   az login
   

9. Enter your credentials and verify that sign-in succeeds.

10. Validate that you're using the correct subscription.

    az account show
    

11. If needed, change the subscription.

    az account set --subscription <subscription-id>
    

Configure environment variables

1. Enter the required environment variables in the terminal.

   export WEBSITE_NAME="" ## Unique name of the static website storage account. The storage account name must be between 3 and 24 characters in length and contain only numbers and lower-case letters.
   export RESOURCE_GROUP="" ## Name of the resource group
   export LOCATION="" ## Azure region to deploy to, for example "westeurope"
   

Deploy storage account

1. Create the resource group. Skip this step if the resource group already exists.

   az group create \
       --name $RESOURCE_GROUP \
       --location $LOCATION
   

2. Create the storage account.

   az storage account create \
       --resource-group $RESOURCE_GROUP \
       --location $LOCATION \
       --name $WEBSITE_NAME \
       --sku Standard_LRS \
       --public-network-access Enabled \
       --allow-blob-public-access true
   

3. Configure the static website.

   az storage blob service-properties update \
       --account-name $WEBSITE_NAME \
       --static-website \
       --404-document index.html \
       --index-document index.html
   

4. Set $web container permissions to allow anonymous access.

   az storage container set-permission \
       --name '$web' \
       --account-name $WEBSITE_NAME \
       --public-access blob
   

Configure the website

1. Navigate to the OSDUApp folder.

   cd OSDUApp/
   

2. Copy the Azure routing.ts file.

   cp providers/azure/routing.ts src/app/routing.ts
   

3. Install the dependencies.

   npm install
   

4. Modify the parameters in the config file located at /src/config/config.json.

Code snippet

Replace the environment variable values with values for your deployment.

export OSDU_ENDPOINT="" # Endpoint of the Azure Data Manager for Energy or OSDU instance to connect to, ending with /api/ . Example: https://contoso.energy.azure.com/api/
export DATA_PARTITION_ID="" # ADME Data Partition ID, or comma-separated list if using multiple partitions
export DOMAIN_NAME=".dataservices.energy" # Domain name to use for the entitlements service. Use .dataservices.energy for any ADME deployment.
export TENANT_ID="" # Entra ID tenant ID
export CLIENT_ID="" # App Registration ID to use for the Admin UI, usually the same as the ADME App Registration ID
export SCOPE="" # Scope of the ADME instance, for example "6ee7e0d6-0641-4b29-a283-541c5d00655a/.default"
export GRAPH_ENDPOINT="https://graph.microsoft.com/v1.0/" # Microsoft Graph API endpoint
export APPINSIGHTS_INSTRUMENTATIONKEY="" # Optional. Application Insights instrumentation key
export OSDU_CONNECTOR_API_ENDPOINT="" # Optional. API endpoint of the OSDU Connector API
export REDIRECT_URI="" # This is your static website URL, for example https://<storage-account-name>.z21.web.core.windows.net/
export GCZ_ENDPOINT="" # Optional. Base GCZ service endpoint ending with /gcz/ . Example: https://contoso.energy.azure.com/api/gcz/

jq \
  --arg data "$DATA_PARTITION_ID" \
  --arg domain "$DOMAIN_NAME" \
  --arg tenant "$TENANT_ID" \
  --arg client "$CLIENT_ID" \
  --arg redirect "$REDIRECT_URI" \
  --arg scope "$SCOPE" \
  --arg endpoint "$OSDU_ENDPOINT" \
  --arg graph "$GRAPH_ENDPOINT" \
  --arg appinsights "$APPINSIGHTS_INSTRUMENTATIONKEY" \
  --arg connectorapi "$OSDU_CONNECTOR_API_ENDPOINT" \
  --arg gcz "$GCZ_ENDPOINT" \
'
.settings.appInsights.instrumentationKey = $appinsights |
.settings.data_partition = ($data | split(",")) |
.settings.domain_name = $domain |
.settings.idp.tenant_id = $tenant |
.settings.idp.client_id = $client |
.settings.idp.redirect_uri = $redirect |
.settings.idp.scope = $scope |
.settings.api_endpoints.entitlement_endpoint = $endpoint |
.settings.api_endpoints.storage_endpoint = $endpoint |
.settings.api_endpoints.search_endpoint = $endpoint |
.settings.api_endpoints.legal_endpoint = $endpoint |
.settings.api_endpoints.schema_endpoint = $endpoint |
.settings.api_endpoints.file_endpoint = $endpoint |
.settings.api_endpoints.secrets_endpoint = $connectorapi |
.settings.api_endpoints.graphAPI_endpoint = $graph |
.settings.api_endpoints.workflow_endpoint = $endpoint |
.settings.api_endpoints.wddms_endpoint = $endpoint |
.settings.api_endpoints.gcz_endpoint = $gcz
' \
src/config/config.json > src/config/temp.json && \
mv src/config/temp.json src/config/config.json

Manual

Replace the values according to the explanation.

{
  ...
  "domain_name": ".dataservices.energy",
  "data_partition": ["<adme_data_partition>"],
  "idp": {
    ...
    "tenant_id": "<tenant_id>",
    "client_id": "<client_id>",
    "redirect_uri": "<redirect_uri>",
    "scope": "<client_id>/.default"
  },
  "api_endpoints": {
    "entitlement_endpoint": "https://contoso.energy.azure.com/api/",
    "storage_endpoint": "https://contoso.energy.azure.com/api/",
    "search_endpoint": "https://contoso.energy.azure.com/api/",
    "legal_endpoint": "https://contoso.energy.azure.com/api/",
    "schema_endpoint": "https://contoso.energy.azure.com/api/",
    "osdu_connector_api_endpoint": "osdu_connector",
    "file_endpoint": "https://contoso.energy.azure.com/api/",
    "graphAPI_endpoint": "https://graph.microsoft.com/v1.0/",
    "workflow_endpoint": "https://contoso.energy.azure.com/api/",
    "wddms_endpoint": "https://contoso.energy.azure.com/api/",
    "gcz_endpoint": "https://contoso.energy.azure.com/api/gcz/"
  }
  ...
}

Note

OSDU Connector API provides an interface between consumers and OSDU APIs by wrapping selected API chains and objects. It currently manages operations and actions on project and scenario objects.

If you configure gcz_endpoint, use the base GCZ endpoint ending with /gcz/. You must already have deployed GCZ separately.

1. Build the web UI.

   ng build --configuration=azure-prod
   

2. Upload the build to Storage Account.

   az storage blob upload-batch \
       --account-name $WEBSITE_NAME \
       --source ./dist/OSDUApp/browser/ \
       --destination '$web' \
       --overwrite
   

3. Retrieve the website URL.

   echo $REDIRECT_URI
   

4. Configure the ADME CORS policy and App Registration SPA redirect URI with the website URL.

5. Open the website URL in a browser and verify that it is working correctly and connected to the correct Azure Data Manager for Energy instance.

Add CORS policy

For the Admin UI to work correctly, add the redirect URI to the CORS policy on the Azure Data Manager for Energy instance. For more information, see Enable CORS.

Add redirect URI to App Registration

Add the redirect URI as a Single-Page Application to the app registration used by the Admin UI. To configure the redirect URI, follow the steps in Scenario: Single-page application.

Next steps

After you have a successful Admin UI working, you can:

• Add first set of users.
• Manage legal tags.
• Manage ACLs.

You can also ingest data into your Azure Data Manager for Energy instance:

• Tutorial on CSV parser ingestion.
• Tutorial on manifest ingestion.

References

For information about OSDU Admin UI, see OSDU GitLab.
For other deployment methods (Terraform or Azure DevOps CI/CD pipeline), see OSDU Admin UI DevOps.