graphrag-accelerator/frontend/README.md

# Frontend Application Launch Instructions
A small frontend application (a streamlit app) is provided to demonstrate how to build and deploy a UI on top of the solution accelerator API.
This application is optional and not required for the solution accelerator API to function properly.

### 1. Deploy the GraphRAG solution accelerator
Follow instructions from the [deployment guide](../docs/DEPLOYMENT-GUIDE.md) to deploy a full instance of the solution accelerator.

### 2. (optional) Create a `.env` file:
If a `.env` file is not provided, the UI will prompt the user for additional login information.

| Variable Name | Required | Example | Description |
| :--- | --- | :--- | ---: |
DEPLOYMENT_URL        | No | https://<my_apim>.azure-api.net | Base url of the deployed graphrag API. Also referred to as the APIM Gateway URL.
APIM_SUBSCRIPTION_KEY | No | <subscription_key> | A [subscription key](https://learn.microsoft.com/en-us/azure/api-management/api-management-subscriptions) generated by APIM.
DEPLOYER_EMAIL        | No | deployer@email.com | Email address of the person/organization that deployed the solution accelerator.

## Run UI locally

The frontend application can run locally as a docker container.

```
# cd to the root directory of the repo
> docker build -t graphrag:frontend -f docker/Dockerfile-frontend .
> docker run --env-file <env_file> -p 8080:8080 graphrag:frontend
```
To access the app , visit `localhost:8080` in your browser.

## Host UI in Azure
The frontend application can also be hosted in Azure as a Web App using the provided `frontend/deploy.sh` script.

### 1. Create Azure App Registration

To enable authentication and authorization for the frontend application, you need to create an Azure App Registration with ID tokens enabled. You may need Owner level permissions on the subscription for some steps.
This app registration will be used for Authentication and Authorization to the frontend web app (not the backend). Follow the steps below:

1. Go to the [Azure portal](https://portal.azure.com) and sign in with your Azure account.
2. Navigate to the **Microsoft Entra ID** service.
3. Select **App registrations** from the left-hand menu.
4. Click on the **+ New registration** button.
5. Provide a name for your app registration and select the appropriate account type.
6. Under the **Redirect URIs** section, select the `Web` platform from dropdown menu. Add `http://localhost:8080/.auth/login/aad/callback` to the URL text field. The deployment script will update this field later with the actual URL of the webapp.
7. Save the app registration.
8. Under the **Manage** section select **Authentication**. Select **ID tokens** as the supported token type.
9. In the **Overview** section of the registered app, take note of the **Application (client) ID**, **Object ID** and **Directory (tenant) ID**. This information will be used later.

### 2. Populate the deploy parameters

Please fill out `frontend/frontend_deploy.parameters.json` with the required values described below.

1. Replace the placeholder values with actual values for the following required variables, you may also add optional variables in the json file if you wish to override the default values:

| Variable Name        | Required | Example                                | Description                                                     |
| :------------------- | :------- | :------------------------------------- | :-------------------------------------------------------------- |
| LOCATION             | Yes      | eastus                                 | The Azure region where resources will be deployed. |
| RESOURCE_GROUP       | Yes      | my-resource-group                      | The name of the Azure resource group where resources will be created. At this time, the name must follow [Azure Container Registry](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/resource-name-rules#microsoftcontainerregistry) naming guidelines. |
| SUBSCRIPTION_ID      | Yes      | 12345678-1234-1234-1234-1234567890ab   | The ID of the Azure subscription where the resources will be deployed. |
| AAD_CLIENT_ID        | Yes      | 12345678-1234-1234-1234-1234567890ab   | The client ID of the Microsoft Entra ID (AAD) app registration. |
| AAD_OBJECT_ID        | Yes      | 12345678-1234-1234-1234-1234567890ab   | The object ID of the Microsoft Entra ID (AAD) app registration. |
| AAD_TENANT_ID        | Yes      | 12345678-1234-1234-1234-1234567890ab   | The ID of the Microsoft Entra ID (AAD) tenant. |
| AAD_TOKEN_ISSUER_URL | No       | https://login.microsoftonline.com/12345678-1234-1234-1234-1234567890ab/v2.0 | The URL of the Microsoft Entra ID (AAD) token issuer. Defaults to the tenant-specific issuer URL. |
| IMAGE_NAME           | No       | graphrag:frontend                      | The name of the Docker image for the frontend application. Defaults to `graphrag:frontend`. |
| REGISTRY_NAME        | No       | myresourcegroupreg                     | The name of the Azure Container Registry. Defaults to the resource group name with `reg` appended. |
| APP_SERVICE_PLAN     | No       | myresourcegroup-asp                    | The name of the Azure App Service plan. Defaults to the resource group name with `asp` appended. |
| WEB_APP              | No       | myresourcegroup-playground             | The name of the Azure Web App. Defaults to the resource group name with `playground` appended. |
| WEB_APP_IDENTITY     | No       | myresourcegroup-playground-identity    | The name of the managed identity for the Azure Web App. Defaults to the web app name with `identity` appended. |

Save the `frontend/frontend_deploy.parameters.json` file after populating the values. If you would like the webapp to automatically connect
to the solution accelerator backend API, create and populate a `.env` file described in step 2, otherwise the webapp will ask for login credentials to the APIM service that was deployed as part of the backend API.

### 3. Run the deploy script

Prerequisite : Please install az-cli version >=2.64.0
To deploy the frontend application:

1. Open a terminal and navigate to the `<graphrag_repo>/frontend` directory.
2. Run the deploy script:

```
# cd to graphrag-accelerator/frontend directory
> bash deploy.sh -p frontend_deploy.parameters.json
```

One the frontend application has been deployed, please take note of the URL that is displayed at the end of the script. It will have the form `(https://PLACEHOLDER.azurewebsites.net)`. The Web App service will take 2-3 minutes initially to load the first time. This is expected behavior.