Skip to content

Commit 39403db

Browse files
EirikHaughomEirikHaughom
committed
Add one-click-deploy option
1 parent f744dbb commit 39403db

File tree

2 files changed

+162
-39
lines changed

2 files changed

+162
-39
lines changed

‎articles/energy-data-services/how-to-deploy-osdu-admin-ui.md

Lines changed: 162 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -15,18 +15,70 @@ This guide shows you how to deploy the OSDU Admin UI on top of your Azure Data M
1515

1616
The OSDU Admin UI enables platform administrators to manage the Azure Data Manager for Energy data partition you connect it to. The management tasks include entitlements (user and group management), legal tags, schemas, reference data, view, and visualize objects on a map.
1717

18+
## Deployment options
19+
20+
There are two deployment options for the OSDU Admin UI:
21+
22+
1. **[Quick-deploy](#quick-deploy)**: One-select deploy using Azure Container Apps. This deployment is the easiest and quickest way to deploy the OSDU Admin UI. It supports both public and private deployments.
23+
24+
1. **[Custom deployment](#custom-deployment)**: Build and deploy the OSDU Admin UI using Azure Storage Account. This deployment option is more customizable and allows you to configure the deployment to your needs.
25+
1826
## Prerequisites
19-
- Install [Visual Studio Code with Dev Containers](https://code.visualstudio.com/docs/devcontainers/tutorial). It's possible to deploy the OSDU Admin UI from your local computer using either Linux or Windows Subsystem for Linux (WSL), we recommend using a Dev Container to eliminate potential conflicts of tooling versions, environments etc.
27+
2028
- An [Azure Data Manager for Energy instance](quickstart-create-microsoft-energy-data-services-instance.md).
2129
- An [Microsoft Entra ID App Registration](/entra/identity-platform/quickstart-register-app). <br> 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.
2230
- [Application.Read.All](/graph/permissions-reference#applicationreadall)
2331
- [User.Read](/graph/permissions-reference#applicationreadall)
2432
- [User.ReadBasic.All](/graph/permissions-reference#userreadbasicall)
2533

26-
Upon first login to the Admin UI it will request the necessary permissions. You can also grant the required permissions in advance, see [App Registration API Permission documentation](/entra/identity-platform/quickstart-configure-app-access-web-apis#application-permission-to-microsoft-graph).
34+
Upon first sign-in to the Admin UI, it requests the necessary permissions. You can also grant the required permissions in advance. See [App Registration API Permission documentation](/entra/identity-platform/quickstart-configure-app-access-web-apis#application-permission-to-microsoft-graph).
35+
36+
## Quick-deploy
37+
38+
1. Select the `Deploy to Azure` button to deploy the OSDU Admin UI using Azure Container Apps.
39+
40+
[![Deploy to Azure](https://aka.ms/deploytoazurebutton)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2FAzure%2FADME-Solution-Accelerators%2Frefs%2Fheads%2Fmain%2Fartifacts%2Fadminui%2Fazuredeploy.json)
41+
42+
1. Fill in the required parameters in the Azure portal. For more information about the parameters, see the [parameters section](#parameters) for more information.
43+
44+
[![Screenshot that shows the Azure portal deployment form.](./media/how-to-deploy-osdu-admin-ui/quickdeploy.png)](./media/how-to-deploy-osdu-admin-ui/quickdeploy.png#lightbox)
45+
46+
1. Select **Review + create** and then **Create** to deploy the OSDU Admin UI.
47+
48+
1. Check the `Outputs` section for the URL of the deployed OSDU Admin UI.
49+
50+
1. Configure the [ADME CORS policy](#add-cors-policy) and [App Registration SPA redirect URI](#add-redirect-uri-to-app-registration) with the website URL.
51+
52+
1. Open the URL in a browser and validate that it's working correctly and connected to the correct Azure Data Manager for Energy instance.
53+
54+
### Parameters
55+
56+
| Parameter | Description | Required |
57+
| --- | --- | ---: |
58+
| Subscription | The Azure subscription to deploy the OSDU Admin UI to. | Yes |
59+
| Resource group | The resource group to deploy the OSDU Admin UI to. | Yes |
60+
| Region | The Azure region to deploy the OSDU Admin UI to. | Yes |
61+
| Name | The name of the OSDU Admin UI instance. Other resources use this name as the base-name and append a service abbreviation | Yes |
62+
| Container Image | The container image to use for the OSDU Admin UI. See [OSDU Forum Admin UI Container Registry](https://community.opengroup.org/osdu/ui/admin-ui-group/admin-ui-totalenergies/admin-ui-totalenergies/container_registry) for available images. | Yes |
63+
| Osdu Endpoint | The endpoint of the Azure Data Manager for Energy or OSDU instance to connect to. | Yes |
64+
| Data Partition ID | The data partition ID of the Azure Data Manager for Energy or OSDU instance to connect to. | Yes |
65+
| 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 |
66+
| Client ID | The client ID of the App Registration to use for the OSDU Admin UI. | Yes |
67+
| 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 |
68+
| Connector Endpoint | *Optional:* The OSDU Admin UI [Connector API](https://community.opengroup.org/osdu/ui/admin-ui-group/admin-ui-totalenergies/connector-api-totalenergies) endpoint to use for the Admin UI. | No |
69+
| Enable Private Network | *Optional:* Enable private network access to the OSDU Admin UI. | No |
70+
| Enable Logging | *Optional:* Enable logging for the OSDU Admin UI. | No |
71+
72+
## Custom deployment
73+
74+
### Prepare your computer
75+
76+
- Install [Visual Studio Code with Dev Containers](https://code.visualstudio.com/docs/devcontainers/tutorial). It's possible to deploy the OSDU Admin UI from your local computer using either Linux or Windows Subsystem for Linux (WSL), we recommend using a Dev Container to eliminate potential conflicts of tooling versions, environments etc.
77+
78+
### Environment setup
2779

28-
## Environment setup
2980
1. Use the Dev Container in Visual Studio Code to deploy the OSDU Admin UI to eliminate conflicts from your local machine.
81+
3082
1. Select `Remote - Containers | Open` to open a Development Container and clone the OSDU Admin UI repository.
3183

3284
[![Open in Remote - Containers](https://img.shields.io/static/v1?style=for-the-badge&label=Remote%20-%20Containers&message=Open&color=blue&logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://community.opengroup.org/osdu/ui/admin-ui-group/admin-ui-totalenergies/admin-ui-totalenergies)
@@ -57,6 +109,7 @@ The OSDU Admin UI enables platform administrators to manage the Azure Data Manag
57109
nvm install 14.17.3 && \
58110
export NG_CLI_ANALYTICS=false && \
59111
npm install -g @angular/[email protected] && \
112+
apt-get install jq -y && \
60113
curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash
61114
```
62115
[![Screenshot that shows installation.](./media/how-to-deploy-osdu-admin-ui/install-screen.png)](./media/how-to-deploy-osdu-admin-ui/install-screen.png#lightbox)
@@ -80,25 +133,27 @@ The OSDU Admin UI enables platform administrators to manage the Azure Data Manag
80133
az account set --subscription <subscription-id>
81134
```
82135
83-
## Configure environment variables
136+
### Configure environment variables
84137
85138
1. Enter the required environment variables on the terminal.
86-
```bash
87-
export ADMINUI_CLIENT_ID="" ## App Registration to be used by OSDU Admin UI, usually the client ID used to provision ADME
139+
140+
```bash
88141
export WEBSITE_NAME="" ## Unique name of the static web app or storage account that will be generated. Storage account name must be between 3 and 24 characters in length and use numbers and lower-case letters only.
89142
export RESOURCE_GROUP="" ## Name of resource group
90143
export LOCATION="" ## Azure region to deploy to, i.e. "westeurope"
91-
```
144+
```
92145
93146
## Deploy storage account
94147
1. Create resource group. Skip this step if the resource group exists already.
148+
95149
```azurecli
96150
az group create \
97151
--name $RESOURCE_GROUP \
98152
--location $LOCATION
99153
```
100154
101155
1. Create storage account.
156+
102157
```azurecli
103158
az storage account create \
104159
--resource-group $RESOURCE_GROUP \
@@ -110,6 +165,7 @@ The OSDU Admin UI enables platform administrators to manage the Azure Data Manag
110165
```
111166
112167
1. Configure the static website.
168+
113169
```azurecli
114170
az storage blob service-properties update \
115171
--account-name $WEBSITE_NAME \
@@ -119,65 +175,120 @@ The OSDU Admin UI enables platform administrators to manage the Azure Data Manag
119175
```
120176
121177
1. Set $web container permissions to allow anonymous access.
178+
122179
```azurecli
123180
az storage container set-permission \
124181
--name '$web' \
125182
--account-name $WEBSITE_NAME \
126183
--public-access blob
127184
```
128185
129-
1. Add the redirect URI to the App Registration.
130-
```azurecli
131-
export REDIRECT_URI=$(az storage account show --resource-group $RESOURCE_GROUP --name $WEBSITE_NAME --query "primaryEndpoints.web") && \
132-
echo "Redirect URL: $REDIRECT_URI" && \
133-
echo "Add the redirect URI above to the following App Registration's Single-page Application (SPA) section: https://ms.portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationMenuBlade/~/Authentication/appId/$ADMINUI_CLIENT_ID/isMSAApp~/false"
134-
```
135-
136-
[![Screenshot showing redirect URIs of an App Registration.](./media/how-to-deploy-osdu-admin-ui/app-uri-config.png)](./media/how-to-deploy-osdu-admin-ui/app-uri-config.png#lightbox)
137-
138-
## Build and deploy the web app
186+
### Build and deploy the web app
139187
140188
1. Navigate to the `OSDUApp` folder.
189+
141190
```bash
142191
cd OSDUApp/
143192
```
193+
194+
1. Copy Azure routing.ts file.
195+
196+
```bash
197+
cp providers/azure/routing.ts src/app/routing.ts
198+
```
199+
144200
1. Install the dependencies.
201+
145202
```nodejs
146203
npm install
147204
```
205+
148206
1. Modify the parameters in the config file located at `/src/config/config.json`.
207+
208+
[Code snippet](#tab/code)
209+
210+
Replace the values of the environment variables with your values.
211+
212+
```bash
213+
export OSDU_ENDPOINT="" # Endpoint of the Azure Data Manager for Energy or OSDU instance to connect to
214+
export DATA_PARTITION_ID="" # ADME Data Partition ID (i.e. opendes)
215+
export DOMAIN_NAME=".dataservices.energy" # Domain name to use for the entitlements service. Use .dataservices.energy for any ADME deployment.
216+
export TENANT_ID="" # Entra ID tenant ID
217+
export CLIENT_ID="" # App Registration ID to use for the admin UI, usually the same as the ADME App Registration ID
218+
export SCOPE="" # Scope of the ADME instance, i.e. "6ee7e0d6-0641-4b29-a283-541c5d00655a/.default"
219+
export GRAPH_ENDPOINT="https://graph.microsoft.com/v1.0/" # Microsoft Graph API endpoint
220+
export APPINSIGHTS_INSTRUMENTATIONKEY="" # Optional. Application Insights instrumentation key
221+
export OSDU_CONNECTOR_API_ENDPOINT="" # Optional. API endpoint of the OSDU Connector API
222+
223+
224+
jq --arg data "$DATA_PARTITION_ID" \
225+
--arg domain "$DOMAIN_NAME" \
226+
--arg tenant "$TENANT_ID" \
227+
--arg client "$CLIENT_ID" \
228+
--arg redirect "$REDIRECT_URI" \
229+
--arg scope "$SCOPE" \
230+
--arg endpoint "$OSDU_ENDPOINT" \
231+
--arg graph "$GRAPH_ENDPOINT" \
232+
--arg appinnsights "$APPINSIGHTS_INSTRUMENTATIONKEY" \
233+
--arg connectorapi "$OSDU_CONNECTOR_API_ENDPOINT" \
234+
'.settings.appInsights.instrumentationKey = $appinnsights |
235+
.settings.data_partition = $data |
236+
.settings.domain_name = $domain |
237+
.settings.idp.tenant_id = $tenant |
238+
.settings.idp.client_id = $client |
239+
.settings.idp.redirect_uri = $redirect |
240+
.settings.idp.scope = $scope |
241+
.settings.api_endpoints.entitlement_endpoint = $endpoint |
242+
.settings.api_endpoints.storage_endpoint = $endpoint |
243+
.settings.api_endpoints.search_endpoint = $endpoint |
244+
.settings.api_endpoints.legal_endpoint = $endpoint |
245+
.settings.api_endpoints.schema_endpoint = $endpoint |
246+
.settings.api_endpoints.file_endpoint = $endpoint |
247+
.settings.api_endpoints.secrets_endpoint = $connectorapi |
248+
.settings.api_endpoints.graphAPI_endpoint = $graph |
249+
.settings.api_endpoints.workflow_endpoint = $endpoint |
250+
.settings.api_endpoints.secrets_endpoint = $endpoint |
251+
.settings.api_endpoints.wddms_endpoint = $endpoint' \
252+
src/config/config.json > src/config/temp.json
253+
mv src/config/temp.json src/config/config.json
254+
```
255+
256+
[Manual](#tab/manual)
257+
258+
Replace the values according to the explanation.
259+
149260
```json
150261
{
151-
"mapboxKey": "key", // This is optional for the access token from Mapbox.com and used to visualize data on the map feature.
152262
...
263+
"domain_name": ".dataservices.energy", // Domain name to use for the entitlements service. Use .dataservices.energy for any ADME deployment.
153264
"data_partition": "<adme_data_partition>", // ADME Data Partition ID (i.e. opendes)
154-
"idp": {
155-
...
156-
"tenant_id": "<tenant_id>", // Entra ID tenant ID
157-
"client_id": "<client_id>", // App Registration ID to use for the admin UI, usually the same as the ADME App Registration ID, i.e. "6ee7e0d6-0641-4b29-a283-541c5d00655a"
158-
"redirect_uri": "<redirect_uri>", // This is the website URL ($REDIRECT_URI), i.e. "https://contoso.z1.web.core.windows.net"
159-
"scope": "<client_id>/.default" // Scope of the ADME instance, i.e. "6ee7e0d6-0641-4b29-a283-541c5d00655a/.default"
160-
},
161-
"api_endpoints": { // Just replace contoso.energy.azure.com with your ADME_URL after removing https or wwww in all the API endpoints below.
162-
"entitlement_endpoint": "https://contoso.energy.azure.com/api/",
163-
"storage_endpoint": "https://contoso.energy.azure.com/api/",
164-
"search_endpoint": "https://contoso.energy.azure.com/api/",
165-
"legal_endpoint": "https://contoso.energy.azure.com/api/",
166-
"schema_endpoint": "https://contoso.energy.azure.com/api/",
167-
"osdu_connector_api_endpoint":"osdu_connector", // Optional. API endpoint of the OSDU Connector API*
168-
"file_endpoint": "https://contoso.energy.azure.com/api/",
169-
"graphAPI_endpoint": "https://graph.microsoft.com/v1.0/",
170-
"workflow_endpoint": "https://contoso.energy.azure.com/api/"
171-
}
265+
"idp": {
266+
...
267+
"tenant_id": "<tenant_id>", // Entra ID tenant ID
268+
"client_id": "<client_id>", // App Registration ID to use for the admin UI, usually the same as the ADME App Registration ID, i.e. "6ee7e0d6-0641-4b29-a283-541c5d00655a"
269+
"redirect_uri": "<redirect_uri>", // This is the website URL ($REDIRECT_URI), i.e. "https://contoso.z1.web.core.windows.net"
270+
"scope": "<client_id>/.default" // Scope of the ADME instance, i.e. "6ee7e0d6-0641-4b29-a283-541c5d00655a/.default"
271+
},
272+
"api_endpoints": { // Just replace contoso.energy.azure.com with your ADME_URL after removing https or wwww in all the API endpoints below.
273+
"entitlement_endpoint": "https://contoso.energy.azure.com/api/",
274+
"storage_endpoint": "https://contoso.energy.azure.com/api/",
275+
"search_endpoint": "https://contoso.energy.azure.com/api/",
276+
"legal_endpoint": "https://contoso.energy.azure.com/api/",
277+
"schema_endpoint": "https://contoso.energy.azure.com/api/",
278+
"osdu_connector_api_endpoint":"osdu_connector", // Optional. API endpoint of the OSDU Connector API*
279+
"file_endpoint": "https://contoso.energy.azure.com/api/",
280+
"graphAPI_endpoint": "https://graph.microsoft.com/v1.0/",
281+
"workflow_endpoint": "https://contoso.energy.azure.com/api/"
282+
}
172283
...
173284
}
174285
```
175286
287+
---
288+
176289
> [!NOTE]
177290
> [OSDU Connector API](https://community.opengroup.org/osdu/ui/admin-ui-group/admin-ui-totalenergies/connector-api-totalenergies) is built as an interface between consumers and OSDU APIs wrapping some API chain calls and objects. Currently, it manages all operations and actions on project and scenario objects.
178-
179-
1. If you are not able to give access to the app as defined in the prerequisite step, remove `User.Read`, `User.ReadBasic.All` and `Application.Read.All` from the `src/config/environments/environment.ts`. Removing these permissions would disable the Admin UI from converting the OIDs of users and applications into the user names and application names respectively and hence would disable the autocomplete feature of resolving OIDs from names.
180-
291+
181292
1. Build the web UI.
182293
```bash
183294
ng build
@@ -197,8 +308,20 @@ The OSDU Admin UI enables platform administrators to manage the Azure Data Manag
197308
echo $REDIRECT_URI
198309
```
199310
311+
1. Configure the [ADME CORS policy](#add-cors-policy) and [App Registration SPA redirect URI](#add-redirect-uri-to-app-registration) with the website URL.
312+
200313
1. Open the Website URL in the browser and validate that it's working correctly and connected to the correct Azure Data Manager for Energy instance.
201314

315+
## Add CORS policy
316+
317+
For the Admin UI to work correctly, you need to add the redirect URI to the CORS policy on the Azure Data Manager for Energy instance.
318+
Learn how to add a CORS policy to your Azure Data Manager for Energy instance, see the [CORS policy documentation](how-to-enable-cors.md).
319+
320+
## Add redirect URI to App Registration
321+
322+
You need to add the redirect URI as a Single-Page App to the App Registration used by the Admin UI.
323+
To configure the redirect URI, follow the steps in the [Add redirect URI to App Registration](/entra/identity-platform/scenario-spa-app-registration) documentation.
324+
202325
## Next steps
203326
After you have a successful Admin UI working, you can:
204327

‎articles/energy-data-services/media/how-to-deploy-osdu-admin-ui/quickdeploy.png

41.4 KB
Loading

0 commit comments

Comments
 (0)