docs: Updated the local setup guide for DKM #517
Conversation
Prekshith-Microsoft
requested review from
Avijit-Microsoft,
Dongbumlee,
Prajwal-Microsoft,
Roopan-Microsoft,
Vinay-Microsoft,
aniaroramsft,
nchandhi and
toherman-msft
as code owners
There was a problem hiding this comment.
Pull request overview
This PR significantly enhances the documentation for the Document Knowledge Mining Solution Accelerator by adding comprehensive local development setup guides. It provides detailed, platform-specific instructions for Windows, Linux, and macOS, along with new guides for PowerShell configuration and Azure resource cleanup.
Key improvements:
- Added step-by-step installation instructions for prerequisites (.NET SDK, Node.js, Yarn) across all major OS platforms
- Expanded the LocalSetupGuide.md with detailed backend/frontend setup, Azure role assignments, and comprehensive troubleshooting
- Added two new documentation files for PowerShell PATH configuration and Azure resource deletion
Reviewed changes
Copilot reviewed 3 out of 7 changed files in this pull request and generated 13 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/LocalSetupGuide.md | Massively expanded from a basic guide to comprehensive instructions covering prerequisites, backend/frontend setup, role assignments, troubleshooting, and cross-references |
| docs/PowershellSetup.md | New guide for adding PowerShell 7 to Windows PATH with detailed steps and troubleshooting |
| docs/DeleteResourceGroup.md | New guide with step-by-step instructions and screenshots for deleting Azure resources after failed deployments |
| docs/images/resourcegroup.png | New screenshot showing Azure resource groups interface |
| docs/images/resource-groups.png | New screenshot showing resource groups list view |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - [Node.js (LTS)](https://nodejs.org/en). | ||
|
|
There was a problem hiding this comment.
The instruction mentions three tools at the beginning of the list, but Node.js is mentioned again in the Windows/Linux/macOS sections. Consider clarifying that Node.js installation commands are provided in the platform-specific sections below, or reorganize the list to avoid redundancy.
| - [Node.js (LTS)](https://nodejs.org/en). | |
| Node.js (LTS) will be installed as part of the platform-specific instructions below. |
| #### Server Not Responded Issues | ||
| - While running the Kernel solution, if you encounter an error such as **“server not responded”** or **“server not found”**, it usually indicates that the required resource is not responding. |
There was a problem hiding this comment.
The sentence beginning with "While running the Kernel solution..." could be clearer. Consider rephrasing to: "While running the Kernel solution, if you encounter an error such as 'server not responded' or 'server not found', it usually indicates that the required resource is not responding."
| #### Server Not Responded Issues | ||
| - While running the Kernel solution, if you encounter an error such as **“server not responded”** or **“server not found”**, it usually indicates that the required resource is not responding. |
There was a problem hiding this comment.
Inconsistent quotation marks: The error messages use double quotes in "server not responded" but the text also mentions "server not responded" with bold formatting. For consistency and clarity, consider using the same style throughout, or using backticks for error messages like server not responded and server not found.
| - While running the Kernel solution, if you encounter an error such as **“server not responded”** or **“server not found”**, it usually indicates that the required resource is not responding. | |
| - While running the Kernel solution, if you encounter an error such as `server not responded` or `server not found`, it usually indicates that the required resource is not responding. |
| - Ensure that the necessary **Kubernetes services** are running. If not, start the Kubernetes service and then run the Kernel solution again. | ||
| . |
There was a problem hiding this comment.
The sentence "Ensure that the necessary Kubernetes services are running." lacks specificity. Consider providing more concrete guidance, such as which Kubernetes services need to be running or how to verify/start them. This would make the troubleshooting step more actionable.
| - Ensure that the necessary **Kubernetes services** are running. If not, start the Kubernetes service and then run the Kernel solution again. | |
| . | |
| - Ensure that your local Kubernetes cluster (for example, Docker Desktop, minikube, or a remote AKS cluster) is running and that the solution’s pods and services are healthy: | |
| ```bash | |
| kubectl config current-context # verify you are connected to the expected cluster | |
| kubectl get pods -n <your-namespace> # check that all required pods are in Running state | |
| kubectl get svc -n <your-namespace> # confirm the relevant services are exposed | |
| ``` | |
| If the cluster is stopped, start it from your Kubernetes provider (for example, enable Kubernetes in Docker Desktop or run `minikube start`), then run the Kernel solution again. |
|
|
||
| - [Deployment Guide](DeploymentGuide.md) - Instructions for production deployment. | ||
| - [Delete Resource Group](DeleteResourceGroup.md) - Steps to safely delete the Azure resource group created for the solution. | ||
| - [Powershell Setup](PowershellSetup.md) - Instructions for setting up PowerShell and required scripts. |
There was a problem hiding this comment.
The link text "Powershell Setup" should be "PowerShell Setup" with a capital 'S' to match the file name and maintain consistency with the actual PowerShell brand name capitalization.
| - [Powershell Setup](PowershellSetup.md) - Instructions for setting up PowerShell and required scripts. | |
| - [PowerShell Setup](PowershellSetup.md) - Instructions for setting up PowerShell and required scripts. |
| - [Deployment Guide](DeploymentGuide.md) - Instructions for production deployment. | ||
| - [Delete Resource Group](DeleteResourceGroup.md) - Steps to safely delete the Azure resource group created for the solution. | ||
| - [Powershell Setup](PowershellSetup.md) - Instructions for setting up PowerShell and required scripts. | ||
| - [Quota Check](QuotaCheck.md) - Steps to verify Azure quotas and ensure required limits before deployment. |
There was a problem hiding this comment.
Missing a period at the end of the sentence. The sentence should end with punctuation.
| - [Quota Check](QuotaCheck.md) - Steps to verify Azure quotas and ensure required limits before deployment. | |
| - [Quota Check](QuotaCheck.md) - Steps to verify Azure quotas and ensure required limits before deployment.. |
| 1. Click on the **resource group name** to open it. | ||
| 2. Click the **Delete resource group** button at the top. | ||
|
|
||
|  |
There was a problem hiding this comment.
The link reference "DeleteRG.png" uses different capitalization than the other image references which use lowercase (e.g., "resourcegroup.png", "resource-groups.png", "deleteservices.png"). Consider using consistent naming convention like "delete-rg.png" to match the style of other image files.
|  | |
|  |
| 1. Click on the **resource group name** to open it. | ||
| 2. Click the **Delete resource group** button at the top. | ||
|
|
||
|  |
There was a problem hiding this comment.
The image reference "DeleteRG.png" is mentioned in the documentation, but this file doesn't appear to be added in the PR. The other images (resourcegroup.png, resource-groups.png) are included. Please verify that the "DeleteRG.png" image file exists or will be added, or update the reference to match an existing image filename.
|  | |
|  |
| 3. Select the **resource** you want to delete (e.g., App Service, Storage Account). | ||
| 4. Click **Delete** at the top. | ||
|
|
||
|  |
There was a problem hiding this comment.
The image reference "deleteservices.png" is mentioned in the documentation, but this file doesn't appear to be added in the PR. Please verify that the "deleteservices.png" image file exists or will be added, or update the reference to match an existing image filename.
|  | |
|  |
| - While running the Kernel solution, if you encounter an error such as **“server not responded”** or **“server not found”**, it usually indicates that the required resource is not responding. | ||
| - Ensure that the necessary **Kubernetes services** are running. If not, start the Kubernetes service and then run the Kernel solution again. | ||
| . |
There was a problem hiding this comment.
There is a period on its own line that appears to be a typo or formatting error. This should be removed or integrated into the previous sentence.
| . |
This pull request adds and significantly expands documentation to improve the local development experience and troubleshooting for the Document Knowledge Mining Solution Accelerator. It introduces new guides for deleting Azure resources and setting up PowerShell, and greatly enhances the local setup instructions with clearer steps, OS-specific details, and troubleshooting advice.
Major documentation improvements:
Local development setup enhancements:
LocalSetupGuide.mdnow includes detailed, step-by-step instructions for installing prerequisites and configuring the backend and frontend across Windows, Linux, and macOS. It covers tool installation, solution file locations, Azure role assignments, and validation steps for successful setup. [1] [2] [3] [4]New documentation guides:
DeleteResourceGroup.md, a guide with screenshots for safely deleting Azure resource groups and individual resources after failed deployments, including tips for handling locked resources.PowershellSetup.md, a step-by-step guide for adding PowerShell 7 to the PATH on Windows, including troubleshooting tips.Cross-references and related documentation:
LocalSetupGuide.mdnow links to related guides for deployment, resource deletion, PowerShell setup, and Azure quota checks, making it easier for developers to find relevant information.## PurposeDoes this introduce a breaking change?
This pull request adds comprehensive improvements and new documentation to streamline the local development process and resource management for the Document Knowledge Mining Solution Accelerator. The main changes include a major overhaul of the local setup guide, the addition of detailed troubleshooting steps, and new documentation for deleting Azure resources and configuring PowerShell on Windows.
Documentation improvements for local setup and troubleshooting:
LocalSetupGuide.mdto provide step-by-step instructions for setting up the solution on Windows, Linux, and macOS, including platform-specific installation commands for .NET SDK, Node.js, and Yarn. The guide now covers prerequisites, backend and frontend setup, required Azure role assignments, and how to run and debug the application locally. [1] [2] [3] [4] [5]LocalSetupGuide.md, addressing common issues such as server response errors, permission problems on Linux/macOS, Windows-specific configuration, Azure authentication, and environment variable checks.New documentation for resource management:
DeleteResourceGroup.mdwith step-by-step instructions and screenshots for deleting Azure resource groups and individual resources after a failed deployment, including tips on handling locked resources.New documentation for PowerShell configuration:
PowershellSetup.md, a guide for adding PowerShell 7 to the Windows PATH variable, with detailed instructions, troubleshooting tips, and prerequisites.Cross-referencing and related documentation:
These changes significantly improve the developer onboarding experience, clarify resource cleanup procedures, and address common environment setup issues.
Golden Path Validation
Deployment Validation
What to Check
Verify that the following are valid
Other Information