Doc Update - #74
Conversation
|
YaminiDhiman please read the following Contributor License Agreement(CLA). If you agree with the CLA, please reply with the following information.
Contributor License AgreementContribution License AgreementThis Contribution License Agreement (“Agreement”) is agreed to by the party signing below (“You”),
|
There was a problem hiding this comment.
Pull request overview
Updates the deployment documentation for the Microsoft IQ Solution Accelerator by rewriting the main deployment guide into a step-based format and introducing a second “v2” guide.
Changes:
- Reworks
docs/DeploymentGuide.mdstructure and content (new “Key Sections”, “Step N” sections, new troubleshooting section, updated command examples). - Adds a second deployment guide document (
docs/DeploymentGuide_v2.md) with largely duplicated content.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 10 comments.
| File | Description |
|---|---|
| docs/DeploymentGuide.md | Major rewrite of the primary deployment guide’s structure, environment setup, commands, and post-deploy guidance. |
| docs/DeploymentGuide_v2.md | Adds a new, near-duplicate deployment guide alongside the primary guide. |
| # Deployment Guide | ||
|
|
||
| Deploy the complete **Microsoft IQ Solution Accelerator** using Azure Developer CLI in minutes. This deployment provisions Fabric IQ (data platform) and Microsoft Foundry (intelligent agents) components. | ||
| Deploy the **Microsoft IQ Solution Accelerator** using Azure Developer CLI (`azd`) and the repo's automated deployment artifacts. This guide walks you through deploying the Fabric IQ, Foundry IQ, and Work IQ components. | ||
|
|
||
| ## Key Sections | ||
|
|
||
| | Section | Description | | ||
| |---|---| | ||
| | [Overview](#overview) | High-level deployment architecture and workflow | | ||
| | [Step 1: Prerequisites & Setup](#step-1-prerequisites--setup) | Azure, Fabric, and software requirements | | ||
| | [Step 2: Choose Your Deployment Environment](#step-2-choose-your-deployment-environment) | Local, Codespaces, Dev Container, Cloud Shell, or GitHub Actions | | ||
| | [Step 3: Configure Deployment Settings (Optional)](#step-3-configure-deployment-settings-optional) | Customize deployment variables and reuse existing resources | | ||
| | [Step 4: Deploy the Solution](#step-4-deploy-the-solution) | Run `azd up` and validate deployment | | ||
| | [Step 5: Post-Deployment Configuration](#step-5-post-deployment-configuration) | Work IQ import and verification steps | | ||
| | [Step 6: Deployment Results](#step-6-deployment-results) | Verify Azure and Fabric resources | | ||
| | [Step 7: Clean Up (Optional)](#step-7-clean-up-optional) | Remove deployed resources safely | | ||
| | [Known Issues and Troubleshooting](#known-issues-and-troubleshooting) | Common errors and resolutions | | ||
| | [Next Steps](#next-steps) | Further guides and resources | | ||
| | [Need Help?](#need-help) | Support and repo guidance | |
| | **Python** | 3.9 or later | [Download from python.org](https://www.python.org/downloads/) | | ||
| | **Azure CLI** | Latest | [Install Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli) | | ||
| | **Azure Developer CLI (azd)** | Latest | [Install azd](https://learn.microsoft.com/azure/developer/azure-developer-cli/install-azd) | | ||
| | **Bicep CLI** | 0.33.0 or later | [Install Bicep](https://learn.microsoft.com/azure/azure-resource-manager/bicep/install) | | ||
| | **Git** | Latest | [Download from git-scm.com](https://git-scm.com/downloads) | |
| |-------------|----------------|-------| | ||
| | **[GitHub Codespaces](#option-a-github-codespaces)** | GitHub account | Cloud development environment | | ||
| | **[Visual Studio Code Dev Container](#option-b-vs-code-dev-container)** | Docker Desktop + VS Code | Containerized consistency | | ||
| | **[Local Machine](#option-c-local-machine)** | Install [software requirements](#14-software-requirements) | Most flexible, requires local setup | |
| 1. Go to the [Microsoft IQ Solution accelerator repository in GitHub Codespaces](https://github.com/codespaces/new/microsoft/microsoft-iq-solution-accelerator) | ||
| 2. Follow the instructions on screen to create a new codespace with default setup. | ||
| 3. Wait for the environment to initialize (2-3 minutes) | ||
| 4.. All tools are pre-installed; proceed to [Step 4: Deploy](#step-4-deploy-the-solution) |
| azd auth login | ||
|
|
||
| # Authenticate with Azure CLI | ||
| az login |
| ## REQUIRED: set `AZURE_AI_DEPLOYMENTS_LOCATION` to your preferred region (no default) | ||
| # Example: azd env set AZURE_AI_DEPLOYMENTS_LOCATION eastus | ||
| azd env set AZURE_AI_DEPLOYMENTS_LOCATION <your-region> | ||
| azd env set FABRIC_WORKSPACE_NAME "My IQ Workspace" |
| ## Known Issues and Troubleshooting | ||
|
|
||
| 1. **Add your documents**: drop PDFs into [`src/foundry/data/documents/`](../src/foundry/data/documents/) and re-run the deployment to refresh the knowledge base: | ||
| ```bash | ||
| azd up | ||
| ``` | ||
| This re-executes `setup_knowledge_base` (Step 1), which re-uploads PDFs to blob storage and re-indexes them. | ||
| 2. **Explore the Fabric workspace**: open notebooks and run the data pipelines. | ||
| 3. **Test the agent**: use the test script above, or chat with `ChatAgent` from the Foundry portal. | ||
| 4. **View dashboards**: access the Power BI reports in the Fabric workspace. | ||
| ### Fabric tenant access issues | ||
|
|
||
| --- | ||
| If the Fabric API returns a 403 or requests are denied by inbound policy, verify: | ||
|
|
||
| ## Environment Cleanup | ||
| - Tenant Fabric settings are enabled | ||
| - Your account has access to the Fabric workspace | ||
| - Network or proxy restrictions are not blocking `api.fabric.microsoft.com` |
| # From the repository root | ||
| python infra/scripts/foundry/test_agent.py | ||
| cd microsoft-iq-solution-accelerator | ||
| azd down --force --purge |
| |---|---| | ||
| | [Overview](#overview) | High-level deployment architecture and workflow | | ||
| | [Step 1: Prerequisites & Setup](#step-1-prerequisites--setup) | Azure, Fabric, and software requirements | | ||
| | [Step 2: Choose Your Deployment Environment](#step-2-choose-your-deployment-environment) | Local, Codespaces, Dev Container, Cloud Shell, or GitHub Actions | |
| # Deployment Guide | ||
|
|
||
| Deploy the **Microsoft IQ Solution Accelerator** using Azure Developer CLI (`azd`) and the repo's automated deployment artifacts. This guide walks you through deploying the Fabric IQ, Foundry IQ, and Work IQ components. | ||
|
|
No description provided.