Skip to content

Commit 64a0a52

Browse files
Avijit-MicrosoftAvijit-Microsoft
authored
docs: Add LocalDebuggingSetup.md and Update Deployment Guide
2 parents 530ee68 + 2408d1f commit 64a0a52

File tree

6 files changed

+911
-201
lines changed

6 files changed

+911
-201
lines changed

‎documents/DeploymentGuide.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -195,6 +195,10 @@ Once you've opened the project in [Codespaces](#github-codespaces), [Dev Contain
195195
196196
- Follow steps in [Delete Resource Group](./DeleteResourceGroup.md) if your deployment fails and/or you need to clean up the resources.
197197
198+
## For Local Debugging
199+
200+
Follow steps in [Local Debugging Setup](./LocalDebuggingSetup.md) to configure your local development environment for debugging the solution.
201+
198202
## Sample Questions
199203
200204
To help you get started, here are some **Sample Questions** you can ask in the app:

‎documents/LocalDebuggingSetup.md‎

Lines changed: 282 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,282 @@
1+
# Local Debugging Setup
2+
3+
Follow the steps below to set up and run the **Conversation Knowledge Mining Solution Accelerator** locally.
4+
5+
6+
7+
## Prerequisites
8+
9+
Install these tools before you start:
10+
- [Visual Studio Code](https://code.visualstudio.com/) with the following extensions:
11+
- [Azure Tools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.vscode-node-azure-pack)
12+
- [Bicep](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-bicep)
13+
- [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)
14+
- [Python 3.11](https://www.python.org/downloads/). **Important:** Check "Add Python to PATH" during installation.
15+
- [PowerShell 7.0+](https://github.com/PowerShell/PowerShell#get-powershell).
16+
- [Node.js (LTS)](https://nodejs.org/en).
17+
- [Git](https://git-scm.com/downloads).
18+
- [Azure Developer CLI (azd) v1.15.0+](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd).
19+
- [Microsoft ODBC Driver 17](https://learn.microsoft.com/en-us/sql/connect/odbc/download-odbc-driver-for-sql-server?view=sql-server-ver16) for SQL Server.
20+
21+
22+
## Setup Steps
23+
24+
### Clone the Repository
25+
26+
Choose a location on your local machine where you want to store the project files. We recommend creating a dedicated folder for your development projects.
27+
28+
#### Using Command Line/Terminal
29+
30+
1. **Open your terminal or command prompt. Navigate to your desired directory and Clone the repository:**
31+
```bash
32+
git clone https://github.com/microsoft/Conversation-Knowledge-Mining-Solution-Accelerator.git
33+
```
34+
35+
2. **Navigate to the project directory:**
36+
```bash
37+
cd Conversation-Knowledge-Mining-Solution-Accelerator
38+
```
39+
40+
3. **Open the project in Visual Studio Code:**
41+
```bash
42+
code .
43+
```
44+
45+
## Local Debugging
46+
47+
To customize the accelerator or run it locally, you have two options:
48+
49+
### Option 1: Use Existing Environment
50+
51+
If you already have an Azure environment deployed with the necessary resources, ensure you have the required `.env` files with all the necessary environment variables in the appropriate locations:
52+
- **Backend API environment variables**: `src/api/.env` - You can get these from:
53+
- `.azure/<environment-name>/` folder if deployed using `azd up`
54+
- Azure Portal App Service environment variables if deployed using custom deployment methods
55+
- **Frontend environment variables**: `src/App/.env`
56+
57+
> **Note**: For a complete list of required environment variables and any value changes needed for local debugging, refer to the [Environment Variables](#environment-variables) section below.
58+
59+
### Option 2: Deploy New Environment
60+
61+
If you don't have an existing environment, you must first deploy the Azure resources. Follow the complete deployment instructions in the [Local Environment section of the Deployment Guide](https://github.com/microsoft/Conversation-Knowledge-Mining-Solution-Accelerator/blob/main/documents/DeploymentGuide.md#local-environment). This will generate a `.env` file located in the `.azure` folder with all the necessary environment variables.
62+
63+
> **Important**: Regardless of which option you choose, ensure all required environment variables are properly configured before proceeding with local development. Refer to the [Environment Variables](#environment-variables) section below.
64+
65+
## Environment Variables
66+
67+
### Backend API Environment Variables (`src/api/.env`):
68+
69+
| App Setting | Value | Note |
70+
|-------------|-------|------|
71+
| `SOLUTION_NAME` | | Prefix used to uniquely identify resources in the deployment |
72+
| `RESOURCE_GROUP_NAME` | | Name of the Azure Resource Group |
73+
| `APP_ENV` | `dev` | Environment type (dev for local debugging, prod for deployment) |
74+
| `APPINSIGHTS_INSTRUMENTATIONKEY` | | Instrumentation Key for Azure Application Insights |
75+
| `APPLICATIONINSIGHTS_CONNECTION_STRING` | | Connection string for Application Insights |
76+
| `AZURE_AI_PROJECT_CONN_STRING` | | Connection string for the Azure AI project |
77+
| `AZURE_AI_AGENT_API_VERSION` | | API version for the Azure AI Agent |
78+
| `AZURE_AI_PROJECT_NAME` | | Name of the Azure AI project |
79+
| `AZURE_AI_SEARCH_ENDPOINT` | | Endpoint URL for Azure Cognitive Search |
80+
| `AZURE_AI_SEARCH_INDEX` | `call_transcripts_index` | Name of the Azure AI Search index |
81+
| `AZURE_AI_SEARCH_CONNECTION_NAME` | | Connection name for Azure AI Search |
82+
| `AZURE_AI_FOUNDRY_NAME` | | Name of the Azure AI Foundry resource |
83+
| `AZURE_AI_SEARCH_NAME` | | Name of the Azure AI Search service |
84+
| `AZURE_EXISTING_AI_PROJECT_RESOURCE_ID` | | Resource ID of existing AI project (if using existing foundry project) |
85+
| `AZURE_COSMOSDB_ACCOUNT` | | Name of the Azure Cosmos DB account |
86+
| `AZURE_COSMOSDB_CONVERSATIONS_CONTAINER` | `conversations` | Name of the Cosmos DB container for conversation data |
87+
| `AZURE_COSMOSDB_DATABASE` | `db_conversation_history` | Name of the Cosmos DB database |
88+
| `AZURE_OPENAI_DEPLOYMENT_MODEL` | | Name of the OpenAI model deployment |
89+
| `AZURE_OPENAI_ENDPOINT` | | Endpoint for the Azure OpenAI resource |
90+
| `AZURE_OPENAI_MODEL_DEPLOYMENT_TYPE` | | Deployment type for OpenAI model |
91+
| `AZURE_OPENAI_EMBEDDING_MODEL` | | Name of the embedding model used for vector search |
92+
| `AZURE_OPENAI_API_VERSION` | | API version for Azure OpenAI |
93+
| `AZURE_OPENAI_RESOURCE` | | Name of the Azure OpenAI resource |
94+
| `REACT_APP_LAYOUT_CONFIG` | | Layout configuration used by the React frontend |
95+
| `SQLDB_DATABASE` | | Name of the Azure SQL Database |
96+
| `SQLDB_SERVER` | | Name of the Azure SQL Server |
97+
| `AZURE_AI_AGENT_ENDPOINT` | | Endpoint for the Azure AI Agent |
98+
| `AZURE_AI_AGENT_MODEL_DEPLOYMENT_NAME` | | Deployment name for the AI agent model |
99+
100+
### Frontend App Environment Variables (`src/App/.env`):
101+
102+
| App Setting | Value | Note |
103+
|-------------|-------|------|
104+
| `REACT_APP_API_BASE_URL` | `http://127.0.0.1:8000` | Frontend API base URL for local development |
105+
106+
## Running with Automated Script
107+
108+
For convenience, you can use the provided startup scripts that handle environment setup and start both services:
109+
110+
**Windows:**
111+
```cmd
112+
cd src
113+
.\start.cmd
114+
```
115+
116+
**macOS/Linux:**
117+
```bash
118+
cd src
119+
chmod +x start.sh
120+
./start.sh
121+
```
122+
123+
### What the Scripts Do
124+
125+
The startup scripts automate the complete local development setup:
126+
127+
- **Environment & Authentication**: Copies `.env` files from Azure deployment and handles Azure login
128+
- **Role Assignments**: Assigns required Azure permissions (SQL, Cosmos DB, Search, AI services)
129+
- **Dependencies**: Creates virtual environment and installs Python/npm packages
130+
- **Service Launch**: Starts both backend (port 8000) and frontend (port 3000) servers
131+
132+
> **Note**: The script includes a 30-second wait time for the backend to initialize before starting the frontend. However, sometimes it might take more time. If you see connection errors in the frontend initially, please wait a moment for the backend to become fully ready, then reload the frontend once the backend is available.
133+
134+
## Running Backend and Frontend Separately
135+
136+
### Manually Assign Roles
137+
138+
To run the accelerator locally when the solution is secured by RBAC, you need to assign roles to your principal ID. You can get your principal ID from Microsoft Entra ID.
139+
140+
**Assign the following roles to your `PRINCIPALID` (via Azure Portal or Azure CLI):**
141+
142+
| Role | GUID | Azure Service |
143+
|------|------|---------------|
144+
| Azure AI User | `53ca6127-db72-4b80-b1b0-d745d6d5456d` | AI Foundry |
145+
| Cognitive Services OpenAI User | `5e0bd9bd-7b93-4f28-af87-19fc36ad61bd` | AI Foundry Project |
146+
| Key Vault Secrets User | `4633458b-17de-408a-b874-0445c86b69e6` | Azure Key Vault |
147+
| Search Index Data Contributor | `8ebe5a00-799e-43f5-93ac-243d3dce84a7` | Azure AI Search |
148+
| Search Index Data Reader | `1407120a-92aa-4202-b7e9-c0e197c71c8f` | Azure AI Search |
149+
| Search Service Contributor | `7ca78c08-252a-4471-8644-bb5ff32d4ba0` | Azure AI Search |
150+
| Storage Blob Data Contributor | `ba92f5b4-2d11-453d-a403-e96b0029c9fe` | Azure Storage Account |
151+
152+
**Assign Cosmos DB Built-in Data Contributor role (via Azure CLI only):**
153+
154+
```bash
155+
# Get your principal ID (if you don't know it)
156+
az ad signed-in-user show --query id -o tsv
157+
158+
# Assign Cosmos DB Built-in Data Contributor role
159+
az cosmosdb sql role assignment create \
160+
--account-name <YOUR_COSMOS_ACCOUNT_NAME> \
161+
--resource-group <YOUR_RESOURCE_GROUP> \
162+
--scope "/" \
163+
--principal-id <YOUR_PRINCIPAL_ID> \
164+
--role-definition-id "00000000-0000-0000-0000-000000000002"
165+
```
166+
167+
#### Setup Azure SQL Database Access
168+
169+
##### Option 1: Set Yourself as SQL Server Admin (for single user scenarios)
170+
171+
1. Go to your SQL Server resource in Azure Portal
172+
2. Under **"Security"**, click **"Microsoft Entra ID"**
173+
3. Click **"Set admin"** and search for your user account
174+
4. Select your user and click **"Save"**
175+
176+
##### Option 2: Create Database User with Specific Roles (recommended)
177+
178+
1. First, ensure you have admin access to the SQL Server (Option 1 above)
179+
2. Connect to your Azure SQL Database using SQL Server Management Studio or the Query Editor in Azure Portal
180+
3. Run the following SQL script (replace the username with your actual Microsoft Entra ID account):
181+
182+
```sql
183+
DECLARE @username NVARCHAR(MAX) = N'[email protected]';
184+
DECLARE @cmd NVARCHAR(MAX);
185+
186+
-- Create the external user if it does not exist
187+
IF NOT EXISTS (SELECT * FROM sys.database_principals WHERE name = @username)
188+
BEGIN
189+
SET @cmd = N'CREATE USER ' + QUOTENAME(@username) + ' FROM EXTERNAL PROVIDER';
190+
EXEC(@cmd);
191+
END
192+
193+
-- Add user to db_datareader if not already a member
194+
IF NOT EXISTS (
195+
SELECT 1 FROM sys.database_role_members drm
196+
JOIN sys.database_principals r ON drm.role_principal_id = r.principal_id
197+
JOIN sys.database_principals u ON drm.member_principal_id = u.principal_id
198+
WHERE r.name = 'db_datareader' AND u.name = @username
199+
)
200+
BEGIN
201+
EXEC sp_addrolemember N'db_datareader', @username;
202+
END
203+
204+
-- Add user to db_datawriter if not already a member
205+
IF NOT EXISTS (
206+
SELECT 1 FROM sys.database_role_members drm
207+
JOIN sys.database_principals r ON drm.role_principal_id = r.principal_id
208+
JOIN sys.database_principals u ON drm.member_principal_id = u.principal_id
209+
WHERE r.name = 'db_datawriter' AND u.name = @username
210+
)
211+
BEGIN
212+
EXEC sp_addrolemember N'db_datawriter', @username;
213+
END
214+
215+
-- Verify the user roles
216+
SELECT u.name AS [UserName], r.name AS [RoleName]
217+
FROM sys.database_role_members drm
218+
INNER JOIN sys.database_principals r ON drm.role_principal_id = r.principal_id
219+
INNER JOIN sys.database_principals u ON drm.member_principal_id = u.principal_id
220+
WHERE u.name = @username;
221+
```
222+
223+
### Develop & Run the Backend API
224+
225+
#### Step 1: Create Virtual Environment (Recommended)
226+
227+
Open your terminal and navigate to the root folder of the project, then create the virtual environment:
228+
229+
```bash
230+
# Navigate to the project root folder
231+
cd Conversation-Knowledge-Mining-Solution-Accelerator
232+
233+
# Create virtual environment in the root folder
234+
python -m venv .venv
235+
236+
# Activate virtual environment (Windows)
237+
.venv\Scripts\activate
238+
239+
# Activate virtual environment (macOS/Linux)
240+
source .venv/bin/activate
241+
```
242+
243+
> **Note**: After activation, you should see `(.venv)` in your terminal prompt indicating the virtual environment is active.
244+
245+
#### Step 2: Install Dependencies and Run
246+
247+
To develop and run the backend API locally:
248+
249+
```bash
250+
# Navigate to the API folder (while virtual environment is activated)
251+
cd src/api
252+
253+
# Upgrade pip
254+
python -m pip install --upgrade pip
255+
256+
# Install Python dependencies
257+
pip install -r requirements.txt
258+
259+
# Run the backend API
260+
python app.py
261+
```
262+
263+
The backend API will run on `http://127.0.0.1:8000` by default.
264+
265+
> **Note**: Make sure your virtual environment is activated before running these commands. You should see `(.venv)` in your terminal prompt when the virtual environment is active.
266+
267+
### Develop & Run the Frontend Locally
268+
269+
To run the React frontend in development mode:
270+
271+
```bash
272+
cd src/App
273+
npm install
274+
npm start
275+
```
276+
277+
The frontend will run on `http://localhost:3000` and automatically proxy API requests to the backend.
278+
279+
## Access the Application
280+
281+
- **Frontend**: http://localhost:3000
282+
- **Backend API**: http://127.0.0.1:8000

‎infra/main.bicep‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -301,8 +301,9 @@ output AZURE_SECONDARY_LOCATION string = secondaryLocation
301301
output APPINSIGHTS_INSTRUMENTATIONKEY string = backend_docker.outputs.appInsightInstrumentationKey
302302
output AZURE_AI_PROJECT_CONN_STRING string = aifoundry.outputs.projectEndpoint
303303
output AZURE_AI_AGENT_API_VERSION string = azureAiAgentApiVersion
304+
output AZURE_AI_FOUNDRY_NAME string = aifoundry.outputs.aiServicesName
304305
output AZURE_AI_PROJECT_NAME string = aifoundry.outputs.aiProjectName
305-
output AZURE_AI_SEARCH_API_KEY string = ''
306+
output AZURE_AI_SEARCH_NAME string = aifoundry.outputs.aiSearchName
306307
output AZURE_AI_SEARCH_ENDPOINT string = aifoundry.outputs.aiSearchTarget
307308
output AZURE_AI_SEARCH_INDEX string = 'call_transcripts_index'
308309
output AZURE_AI_SEARCH_CONNECTION_NAME string = aifoundry.outputs.aiSearchConnectionName
@@ -329,7 +330,8 @@ output AZURE_AI_AGENT_ENDPOINT string = aifoundry.outputs.projectEndpoint
329330
output AZURE_AI_AGENT_MODEL_DEPLOYMENT_NAME string = gptModelName
330331
output ACR_NAME string = acrName
331332
output AZURE_ENV_IMAGETAG string = imageTag
333+
output AZURE_EXISTING_AI_PROJECT_RESOURCE_ID string = azureExistingAIProjectResourceId
334+
output APPLICATIONINSIGHTS_CONNECTION_STRING string = aifoundry.outputs.applicationInsightsConnectionString
332335

333336
output API_APP_URL string = backend_docker.outputs.appUrl
334337
output WEB_APP_URL string = frontend_docker.outputs.appUrl
335-
output APPLICATIONINSIGHTS_CONNECTION_STRING string = aifoundry.outputs.applicationInsightsConnectionString

0 commit comments

Comments
 (0)