From 637b77e1cb2888ae7c19b7cfc8d32d4e2245cdd9 Mon Sep 17 00:00:00 2001 From: Ajit Padhi Date: Tue, 2 Dec 2025 19:42:56 +0530 Subject: [PATCH 1/7] Refactor deployment guide Readme --- docs/DeploymentGuideNew.md | 460 +++++++++++++++++++++++++++++++++++++ 1 file changed, 460 insertions(+) create mode 100644 docs/DeploymentGuideNew.md diff --git a/docs/DeploymentGuideNew.md b/docs/DeploymentGuideNew.md new file mode 100644 index 00000000..8c19a67c --- /dev/null +++ b/docs/DeploymentGuideNew.md @@ -0,0 +1,460 @@ +# Deployment Guide + +## Overview + +This guide walks you through deploying the Document Generation Solution Accelerator to Azure. The deployment process takes approximately 10-15 minutes for the default Development/Testing configuration and includes both infrastructure provisioning and application setup. + +πŸ†˜ **Need Help?** If you encounter any issues during deployment, check our [Troubleshooting Guide](./TroubleShootingSteps.md) for solutions to common problems. + +## Step 1: Prerequisites & Setup + +### 1.1 Azure Account Requirements + +Ensure you have access to an [Azure subscription](https://azure.microsoft.com/free/) with the following permissions: + +| **Required Permission/Role** | **Scope** | **Purpose** | +|------------------------------|-----------|-------------| +| **Contributor** | Subscription level | Create and manage Azure resources | +| **User Access Administrator** | Subscription level | Manage user access and role assignments | +| **Role Based Access Control** | Subscription/Resource Group level | Configure RBAC permissions | +| **App Registration Creation** | Azure Active Directory | Create and configure authentication | + +**πŸ” How to Check Your Permissions:** + +1. Go to [Azure Portal](https://portal.azure.com/) +2. Navigate to **Subscriptions** (search for "subscriptions" in the top search bar) +3. Click on your target subscription +4. In the left menu, click **Access control (IAM)** +5. Scroll down to see the table with your assigned roles - you should see: + - **Contributor** + - **User Access Administrator** + - **Role Based Access Control Administrator** (or similar RBAC role) + +**For App Registration permissions:** +1. Go to **Microsoft Entra ID** β†’ **Manage** β†’ **App registrations** +2. Try clicking **New registration** +3. If you can access this page, you have the required permissions +4. Cancel without creating an app registration + +πŸ“– **Detailed Setup:** Follow [Azure Account Set Up](./AzureAccountSetup.md) for complete configuration. + +### 1.2 Check Service Availability & Quota + +⚠️ **CRITICAL:** Before proceeding, ensure your chosen region has all required services available: + +**Required Azure Services:** +- [Azure AI Foundry](https://learn.microsoft.com/en-us/azure/ai-foundry/) +- [Azure OpenAI Service](https://learn.microsoft.com/en-us/azure/ai-services/openai/) +- [Azure Blob Storage](https://learn.microsoft.com/en-us/azure/storage/blobs/) +- [Azure Container Apps](https://learn.microsoft.com/en-us/azure/container-apps/) +- [Azure Container Registry](https://learn.microsoft.com/en-us/azure/container-registry/) +- [Azure App Configuration](https://learn.microsoft.com/en-us/azure/azure-app-configuration/) +- [Azure Cosmos DB](https://learn.microsoft.com/en-us/azure/cosmos-db/) +- [Azure Queue Storage](https://learn.microsoft.com/en-us/azure/storage/queues/) +- [o3 Model Capacity](https://learn.microsoft.com/en-us/azure/ai-foundry/foundry-models/concepts/models-sold-directly-by-azure) + +**Recommended Regions:** East US, East US2, Australia East, UK South, France Central. + +πŸ” **Check Availability:** Use [Azure Products by Region](https://azure.microsoft.com/en-us/explore/global-infrastructure/products-by-region/) to verify service availability. + +### 1.3 Quota Check (Optional) + +πŸ’‘ **RECOMMENDED:** Check your Azure OpenAI quota availability before deployment for optimal planning. + +πŸ“– **Follow:** [Quota Check Instructions](./QuotaCheck.md) to ensure sufficient capacity. + +By default, the _Gpt-4.1 model capacity_ in deployment is set to _30k tokens_, so we recommend: +- **For Global Standard | GPT-4.1** - the capacity to at least 150k tokens post-deployment for optimal performance. + +- **For Standard | GPT-4** - ensure a minimum of 30k–40k tokens for best results. + +> **Note:** When you run `azd up`, the deployment will automatically show you regions with available quota, so this pre-check is optional but helpful for planning purposes. You can customize these settings later in [Step 3.3: Advanced Configuration](#33-advanced-configuration-optional). + +πŸ“– **Adjust Quota:** Follow [Azure AI Model Quota Settings](./AzureAIModelQuotaSettings.md) if needed. + +## Step 2: Choose Your Deployment Environment + +Select one of the following options to deploy the Document Generation Solution Accelerator: + +### Environment Comparison + +| **Option** | **Best For** | **Prerequisites** | **Setup Time** | +|------------|--------------|-------------------|----------------| +| **GitHub Codespaces** | Quick deployment, no local setup required | GitHub account | ~3-5 minutes | +| **VS Code Dev Containers** | Fast deployment with local tools | Docker Desktop, VS Code | ~5-10 minutes | +| **VS Code Web** | Quick deployment, no local setup required | Azure account | ~2-4 minutes | +| **Local Environment** | Enterprise environments, full control | All tools individually | ~15-30 minutes | + +**πŸ’‘ Recommendation:** For fastest deployment, start with **GitHub Codespaces** - no local installation required. + +--- + +
+Option A: GitHub Codespaces (Easiest) + +[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/microsoft/document-generation-solution-accelerator) + +1. Click the badge above (may take several minutes to load) +2. Accept default values on the Codespaces creation page +3. Wait for the environment to initialize (includes all deployment tools) +4. Proceed to [Step 3: Configure Deployment Settings](#step-3-configure-deployment-settings) + +
+ +
+Option B: VS Code Dev Containers + +[![Open in Dev Containers](https://img.shields.io/static/v1?style=for-the-badge&label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/microsoft/document-generation-solution-accelerator) + +**Prerequisites:** +- [Docker Desktop](https://www.docker.com/products/docker-desktop/) installed and running +- [VS Code](https://code.visualstudio.com/) with [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) + +**Steps:** +1. Start Docker Desktop +2. Click the badge above to open in Dev Containers +3. Wait for the container to build and start (includes all deployment tools) +4. Proceed to [Step 3: Configure Deployment Settings](#step-3-configure-deployment-settings) + +
+ +
+Option C: Visual Studio Code Web + + [![Open in Visual Studio Code Web](https://img.shields.io/static/v1?style=for-the-badge&label=Visual%20Studio%20Code%20(Web)&message=Open&color=blue&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/azure/?vscode-azure-exp=foundry&agentPayload=eyJiYXNlVXJsIjogImh0dHBzOi8vcmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbS9taWNyb3NvZnQvQ29udGFpbmVyLU1pZ3JhdGlvbi1Tb2x1dGlvbi1BY2NlbGVyYXRvci9yZWZzL2hlYWRzL21haW4vaW5mcmEvdnNjb2RlX3dlYiIsICJpbmRleFVybCI6ICIvaW5kZXguanNvbiIsICJ2YXJpYWJsZXMiOiB7ImFnZW50SWQiOiAiIiwgImNvbm5lY3Rpb25TdHJpbmciOiAiIiwgInRocmVhZElkIjogIiIsICJ1c2VyTWVzc2FnZSI6ICIiLCAicGxheWdyb3VuZE5hbWUiOiAiIiwgImxvY2F0aW9uIjogIiIsICJzdWJzY3JpcHRpb25JZCI6ICIiLCAicmVzb3VyY2VJZCI6ICIiLCAicHJvamVjdFJlc291cmNlSWQiOiAiIiwgImVuZHBvaW50IjogIiJ9LCAiY29kZVJvdXRlIjogWyJhaS1wcm9qZWN0cy1zZGsiLCAicHl0aG9uIiwgImRlZmF1bHQtYXp1cmUtYXV0aCIsICJlbmRwb2ludCJdfQ==) + +1. Click the badge above (may take a few minutes to load) +2. Sign in with your Azure account when prompted +3. Select the subscription where you want to deploy the solution +4. Wait for the environment to initialize (includes all deployment tools) +5. When prompted in the VS Code Web terminal, choose one of the available options shown below: + + ![VS Code Initial Prompt](./images/vscodeweb_intialize.png) +6. Proceed to [Step 3: Configure Deployment Settings](#step-3-configure-deployment-settings) + +
+ +
+Option D: Local Environment + +**Required Tools:** +- [PowerShell 7.0+](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell) +- [Azure Developer CLI (azd) 1.18.0+](https://aka.ms/install-azd) +- [Python 3.9+](https://www.python.org/downloads/) +- [Docker Desktop](https://www.docker.com/products/docker-desktop/) +- [Git](https://git-scm.com/downloads) + +**Setup Steps:** +1. Install all required deployment tools listed above +2. Clone the repository: + ```shell + azd init -t microsoft/document-generation-solution-accelerator/ + ``` +3. Open the project folder in your terminal +4. Proceed to [Step 3: Configure Deployment Settings](#step-3-configure-deployment-settings) + +**PowerShell Users:** If you encounter script execution issues, run: +```powershell +Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass +``` + +
+ +## Step 3: Configure Deployment Settings + +Review the configuration options below. You can customize any settings that meet your needs, or leave them as defaults to proceed with a standard deployment. + +### 3.1 Choose Deployment Type (Optional) + +| **Aspect** | **Development/Testing (Default)** | **Production** | +|------------|-----------------------------------|----------------| +| **Configuration File** | `main.parameters.json` (sandbox) | Copy `main.waf.parameters.json` to `main.parameters.json` | +| **Security Controls** | Minimal (for rapid iteration) | Enhanced (production best practices) | +| **Cost** | Lower costs | Cost optimized | +| **Use Case** | POCs, development, testing | Production workloads | +| **Framework** | Basic configuration | [Well-Architected Framework](https://learn.microsoft.com/en-us/azure/well-architected/) | +| **Features** | Core functionality | Reliability, security, operational excellence | + +**To use production configuration:** + +Copy the contents from the production configuration file to your main parameters file: + +1. Navigate to the `infra` folder in your project +2. Open `main.waf.parameters.json` in a text editor (like Notepad, VS Code, etc.) +3. Select all content (Ctrl+A) and copy it (Ctrl+C) +4. Open `main.parameters.json` in the same text editor +5. Select all existing content (Ctrl+A) and paste the copied content (Ctrl+V) +6. Save the file (Ctrl+S) + +### 3.2 Set VM Credentials (Optional - Production Deployment Only) + +> **Note:** This section only applies if you selected **Production** deployment type in section 3.1. VMs are not deployed in the default Development/Testing configuration. + +By default, random GUIDs are generated for VM credentials. To set custom credentials: + +```shell +azd env set AZURE_ENV_VM_ADMIN_USERNAME +azd env set AZURE_ENV_VM_ADMIN_PASSWORD +``` + +### 3.3 Advanced Configuration (Optional) + +
+Configurable Parameters + +You can customize various deployment settings before running `azd up`, including Azure regions, AI model configurations (deployment type, version, capacity), container registry settings, and resource names. + +πŸ“– **Complete Guide:** See [Parameter Customization Guide](../docs/CustomizingAzdParameters.md) for the full list of available parameters and their usage. + +
+ +
+Reuse Existing Resources + +To optimize costs and integrate with your existing Azure infrastructure, you can configure the solution to reuse compatible resources already deployed in your subscription. + +**Supported Resources for Reuse:** + +- **Log Analytics Workspace:** Integrate with your existing monitoring infrastructure by reusing an established Log Analytics workspace for centralized logging and monitoring. [Configuration Guide](./re-use-log-analytics.md) + +- **Azure AI Foundry Project:** Leverage your existing AI Foundry project and deployed models to avoid duplication and reduce provisioning time. [Configuration Guide](./re-use-foundry-project.md) + +**Key Benefits:** +- **Cost Optimization:** Eliminate duplicate resource charges +- **Operational Consistency:** Maintain unified monitoring and AI infrastructure +- **Faster Deployment:** Skip resource creation for existing compatible services +- **Simplified Management:** Reduce the number of resources to manage and monitor + +**Important Considerations:** +- Ensure existing resources meet the solution's requirements and are in compatible regions +- Review access permissions and configurations before reusing resources +- Consider the impact on existing workloads when sharing resources + +
+ +## Step 4: Deploy the Solution + +πŸ’‘ **Before You Start:** If you encounter any issues during deployment, check our [Troubleshooting Guide](./TroubleShootingSteps.md) for common solutions. + +### 4.1 Authenticate with Azure + +```shell +azd auth login +``` + +**For specific tenants:** +```shell +azd auth login --tenant-id +``` + +> **Finding Tenant ID:** + > 1. Open the [Azure Portal](https://portal.azure.com/). + > 2. Navigate to **Microsoft Entra ID** from the left-hand menu. + > 3. Under the **Overview** section, locate the **Tenant ID** field. Copy the value displayed. + +### 4.2 Start Deployment + +```shell +azd up +``` + +**During deployment, you'll be prompted for:** +1. **Environment name** (e.g., "conmig") - Must be 3-16 characters long, alphanumeric only +2. **Azure subscription** selection +3. **Azure AI Foundry deployment region** - Select a region with available o3 model quota for AI operations +4. **Primary location** - Select the region where your infrastructure resources will be deployed +5. **Resource group** selection (create new or use existing) + +**Expected Duration:** 4-6 minutes for default configuration + +**⚠️ Deployment Issues:** If you encounter errors or timeouts, try a different region as there may be capacity constraints. For detailed error solutions, see our [Troubleshooting Guide](./TroubleShootingSteps.md). + +### 4.3 Get Application URL + +After successful deployment: +1. Open [Azure Portal](https://portal.azure.com/) +2. Navigate to your resource group +3. Find the Container App with "frontend" in the name +4. Copy the **Application URI** + +⚠️ **Important:** Complete [Post-Deployment Steps](#step-5-post-deployment-configuration) before accessing the application. + +## Step 5: Post-Deployment Configuration + +### 5.1 Sample Data Import + +1. Once the deployment has completed successfully and you would like to use the sample data, please open a **Git Bash** terminal and run the bash command printed below. The bash command will look like the following: + ```shell + bash ./infra/scripts/process_sample_data.sh + ``` + If you don't have azd env then you need to pass parameters along with the command. Then the command will look like the following: + ```shell + bash ./infra/scripts/process_sample_data.sh + ``` + +2. Open the [Azure Portal](https://portal.azure.com/), go to the deployed resource group, find the App Service and get the app URL from `Default domain`. + +### 5.2 Configure Authentication (Optional) + +1. Follow [App Authentication Configuration](./ConfigureAppAuthentication.md) +2. Wait up to 10 minutes for authentication changes to take effect + +### 5.3 Verify Deployment + +1. Access your application using the URL from Step 4.3 +2. Confirm the application loads successfully +3. Verify you can sign in with your authenticated account + +## Step 6: Clean Up (Optional) + +### Remove All Resources +```shell +azd down +``` +> **Note:** If you deployed with `enableRedundancy=true` and Log Analytics workspace replication is enabled, you must first disable replication before running `azd down` else resource group delete will fail. Follow the steps in [Handling Log Analytics Workspace Deletion with Replication Enabled](./LogAnalyticsReplicationDisable.md), wait until replication returns `false`, then run `azd down`. + +### Manual Cleanup (if needed) +If deployment fails or you need to clean up manually: +- Follow [Delete Resource Group Guide](./DeleteResourceGroup.md) + +## Managing Multiple Environments + +### Recover from Failed Deployment + +If your deployment failed or encountered errors, here are the steps to recover: + +
+Recover from Failed Deployment + +**If your deployment failed or encountered errors:** + +1. **Try a different region:** Create a new environment and select a different Azure region during deployment +2. **Clean up and retry:** Use `azd down` to remove failed resources, then `azd up` to redeploy +3. **Check troubleshooting:** Review [Troubleshooting Guide](./TroubleShootingSteps.md) for specific error solutions +4. **Fresh start:** Create a completely new environment with a different name + +**Example Recovery Workflow:** +```shell +# Remove failed deployment (optional) +azd down + +# Create new environment (3-16 chars, alphanumeric only) +azd env new conmigretry + +# Deploy with different settings/region +azd up +``` + +
+ +### Creating a New Environment + +If you need to deploy to a different region, test different configurations, or create additional environments: + +
+Create a New Environment + +**Create Environment Explicitly:** +```shell +# Create a new named environment (3-16 characters, alphanumeric only) +azd env new + +# Select the new environment +azd env select + +# Deploy to the new environment +azd up +``` + +**Example:** +```shell +# Create a new environment for production (valid: 3-16 chars) +azd env new conmigprod + +# Switch to the new environment +azd env select conmigprod + +# Deploy with fresh settings +azd up +``` + +> **Environment Name Requirements:** +> - **Length:** 3-16 characters +> - **Characters:** Alphanumeric only (letters and numbers) +> - **Valid examples:** `conmig`, `test123`, `myappdev`, `prod2024` +> - **Invalid examples:** `co` (too short), `my-very-long-environment-name` (too long), `test_env` (underscore not allowed), `myapp-dev` (hyphen not allowed) + +
+ +
+Switch Between Environments + +**List Available Environments:** +```shell +azd env list +``` + +**Switch to Different Environment:** +```shell +azd env select +``` + +**View Current Environment:** +```shell +azd env get-values +``` + +
+ +### Best Practices for Multiple Environments + +- **Use descriptive names:** `conmigdev`, `conmigprod`, `conmigtest` (remember: 3-16 chars, alphanumeric only) +- **Different regions:** Deploy to multiple regions for testing quota availability +- **Separate configurations:** Each environment can have different parameter settings +- **Clean up unused environments:** Use `azd down` to remove environments you no longer need + +## Next Steps + +Now that your deployment is complete and tested, explore these resources to enhance your experience: + +πŸ“š **Learn More:** +- [Technical Architecture](./TechnicalArchitecture.md) - Understand the system design and components +- [Customize Expert Agents](./CustomizeExpertAgents.md) - Tailor AI agents to your specific needs +- [Extend Platform Support](./ExtendPlatformSupport.md) - Add support for additional container platforms +- [Configure MCP Servers](./ConfigureMCPServers.md) - Set up Model Context Protocol servers +- [Local Development Setup](./LocalDevelopmentSetup.md) - Set up your local development environment + +## Need Help? + +- πŸ› **Issues:** Check [Troubleshooting Guide](./TroubleShootingSteps.md) +- πŸ’¬ **Support:** Review [Support Guidelines](../SUPPORT.md) +- πŸ”§ **Development:** See [Contributing Guide](../CONTRIBUTING.md) + +--- + +## Advanced: Deploy Local Changes + +If you've made local modifications to the code and want to deploy them to Azure, follow these steps to swap the configuration files: + +> **Note:** To set up and run the application locally for development, see the [Local Development Setup Guide](./LocalDevelopmentSetup.md). + +### Step 1: Rename Azure Configuration Files + +**In the root directory:** +1. Rename `azure.yaml` to `azure_custom2.yaml` +2. Rename `azure_custom.yaml` to `azure.yaml` + +### Step 2: Rename Infrastructure Files + +**In the `infra` directory:** +1. Rename `main.bicep` to `main_custom2.bicep` +2. Rename `main_custom.bicep` to `main.bicep` + +### Step 3: Deploy Changes + +Run the deployment command: +```shell +azd up +``` + +> **Note:** These custom files are configured to deploy your local code changes instead of pulling from the GitHub repository. \ No newline at end of file From e8d352e8903be7cfcc2f023bcc12bf60493f7b92 Mon Sep 17 00:00:00 2001 From: Ajit Padhi Date: Wed, 3 Dec 2025 12:14:33 +0530 Subject: [PATCH 2/7] updated readme --- docs/DeploymentGuideNew.md | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/docs/DeploymentGuideNew.md b/docs/DeploymentGuideNew.md index 8c19a67c..8740ee36 100644 --- a/docs/DeploymentGuideNew.md +++ b/docs/DeploymentGuideNew.md @@ -45,13 +45,8 @@ Ensure you have access to an [Azure subscription](https://azure.microsoft.com/fr **Required Azure Services:** - [Azure AI Foundry](https://learn.microsoft.com/en-us/azure/ai-foundry/) - [Azure OpenAI Service](https://learn.microsoft.com/en-us/azure/ai-services/openai/) -- [Azure Blob Storage](https://learn.microsoft.com/en-us/azure/storage/blobs/) -- [Azure Container Apps](https://learn.microsoft.com/en-us/azure/container-apps/) -- [Azure Container Registry](https://learn.microsoft.com/en-us/azure/container-registry/) -- [Azure App Configuration](https://learn.microsoft.com/en-us/azure/azure-app-configuration/) - [Azure Cosmos DB](https://learn.microsoft.com/en-us/azure/cosmos-db/) -- [Azure Queue Storage](https://learn.microsoft.com/en-us/azure/storage/queues/) -- [o3 Model Capacity](https://learn.microsoft.com/en-us/azure/ai-foundry/foundry-models/concepts/models-sold-directly-by-azure) +- [Azure AI Search](https://learn.microsoft.com/en-us/azure/search/) **Recommended Regions:** East US, East US2, Australia East, UK South, France Central. @@ -259,7 +254,7 @@ azd up ``` **During deployment, you'll be prompted for:** -1. **Environment name** (e.g., "conmig") - Must be 3-16 characters long, alphanumeric only +1. **Environment name** (e.g., "docgen") - Must be 3-16 characters long, alphanumeric only 2. **Azure subscription** selection 3. **Azure AI Foundry deployment region** - Select a region with available o3 model quota for AI operations 4. **Primary location** - Select the region where your infrastructure resources will be deployed From df86a6acfbcdea163ec20b4d4d4ac046e5003218 Mon Sep 17 00:00:00 2001 From: Ajit Padhi Date: Wed, 3 Dec 2025 12:17:15 +0530 Subject: [PATCH 3/7] updated deployment readme --- docs/DeploymentGuide.md | 506 ++++++++++++++++++++++++------------- docs/DeploymentGuideNew.md | 455 --------------------------------- 2 files changed, 337 insertions(+), 624 deletions(-) delete mode 100644 docs/DeploymentGuideNew.md diff --git a/docs/DeploymentGuide.md b/docs/DeploymentGuide.md index 458792e2..8740ee36 100644 --- a/docs/DeploymentGuide.md +++ b/docs/DeploymentGuide.md @@ -1,236 +1,284 @@ # Deployment Guide -## **Pre-requisites** +## Overview -To deploy this solution accelerator, ensure you have access to an [Azure subscription](https://azure.microsoft.com/free/) with the necessary permissions to create **resource groups, resources, app registrations, and assign roles at the resource group level**. This should include Contributor role at the subscription level and Role Based Access Control role on the subscription and/or resource group level. Follow the steps in [Azure Account Set Up](./AzureAccountSetUp.md). +This guide walks you through deploying the Document Generation Solution Accelerator to Azure. The deployment process takes approximately 10-15 minutes for the default Development/Testing configuration and includes both infrastructure provisioning and application setup. -Check the [Azure Products by Region](https://azure.microsoft.com/en-us/explore/global-infrastructure/products-by-region/?products=all®ions=all) page and select a **region** where the following services are available: +πŸ†˜ **Need Help?** If you encounter any issues during deployment, check our [Troubleshooting Guide](./TroubleShootingSteps.md) for solutions to common problems. -- Azure OpenAI Service -- Azure AI Search -- [Azure Semantic Search](./AzureSemanticSearchRegion.md) +## Step 1: Prerequisites & Setup -Here are some example regions where the services are available: East US, East US2, Australia East, UK South, France Central. +### 1.1 Azure Account Requirements -### **Important Note for PowerShell Users** +Ensure you have access to an [Azure subscription](https://azure.microsoft.com/free/) with the following permissions: -If you encounter issues running PowerShell scripts due to the policy of not being digitally signed, you can temporarily adjust the `ExecutionPolicy` by running the following command in an elevated PowerShell session: +| **Required Permission/Role** | **Scope** | **Purpose** | +|------------------------------|-----------|-------------| +| **Contributor** | Subscription level | Create and manage Azure resources | +| **User Access Administrator** | Subscription level | Manage user access and role assignments | +| **Role Based Access Control** | Subscription/Resource Group level | Configure RBAC permissions | +| **App Registration Creation** | Azure Active Directory | Create and configure authentication | -```powershell -Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -``` +**πŸ” How to Check Your Permissions:** -This will allow the scripts to run for the current session without permanently changing your system's policy. +1. Go to [Azure Portal](https://portal.azure.com/) +2. Navigate to **Subscriptions** (search for "subscriptions" in the top search bar) +3. Click on your target subscription +4. In the left menu, click **Access control (IAM)** +5. Scroll down to see the table with your assigned roles - you should see: + - **Contributor** + - **User Access Administrator** + - **Role Based Access Control Administrator** (or similar RBAC role) -## Deployment Options & Steps +**For App Registration permissions:** +1. Go to **Microsoft Entra ID** β†’ **Manage** β†’ **App registrations** +2. Try clicking **New registration** +3. If you can access this page, you have the required permissions +4. Cancel without creating an app registration -### Sandbox or WAF Aligned Deployment Options +πŸ“– **Detailed Setup:** Follow [Azure Account Set Up](./AzureAccountSetup.md) for complete configuration. -The [`infra`](../infra) folder of the Multi Agent Solution Accelerator contains the [`main.bicep`](../infra/main.bicep) Bicep script, which defines all Azure infrastructure components for this solution. +### 1.2 Check Service Availability & Quota -By default, the `azd up` command uses the [`main.parameters.json`](../infra/main.parameters.json) file to deploy the solution. This file is pre-configured for a **sandbox environment** β€” ideal for development and proof-of-concept scenarios, with minimal security and cost controls for rapid iteration. +⚠️ **CRITICAL:** Before proceeding, ensure your chosen region has all required services available: -For **production deployments**, the repository also provides [`main.waf.parameters.json`](../infra/main.waf.parameters.json), which applies a [Well-Architected Framework (WAF) aligned](https://learn.microsoft.com/en-us/azure/well-architected/) configuration. This option enables additional Azure best practices for reliability, security, cost optimization, operational excellence, and performance efficiency, such as: +**Required Azure Services:** +- [Azure AI Foundry](https://learn.microsoft.com/en-us/azure/ai-foundry/) +- [Azure OpenAI Service](https://learn.microsoft.com/en-us/azure/ai-services/openai/) +- [Azure Cosmos DB](https://learn.microsoft.com/en-us/azure/cosmos-db/) +- [Azure AI Search](https://learn.microsoft.com/en-us/azure/search/) - - Enhanced network security (e.g., Network protection with private endpoints) - - Stricter access controls and managed identities - - Logging, monitoring, and diagnostics enabled by default - - Resource tagging and cost management recommendations +**Recommended Regions:** East US, East US2, Australia East, UK South, France Central. -**How to choose your deployment configuration:** +πŸ” **Check Availability:** Use [Azure Products by Region](https://azure.microsoft.com/en-us/explore/global-infrastructure/products-by-region/) to verify service availability. -* Use the default `main.parameters.json` file for a **sandbox/dev environment** -* For a **WAF-aligned, production-ready deployment**, copy the contents of `main.waf.parameters.json` into `main.parameters.json` before running `azd up` +### 1.3 Quota Check (Optional) ---- +πŸ’‘ **RECOMMENDED:** Check your Azure OpenAI quota availability before deployment for optimal planning. -### VM Credentials Configuration +πŸ“– **Follow:** [Quota Check Instructions](./QuotaCheck.md) to ensure sufficient capacity. -By default, the solution sets the VM administrator username and password from environment variables. - -To set your own VM credentials before deployment, use: - -```sh -azd env set AZURE_ENV_VM_ADMIN_USERNAME -azd env set AZURE_ENV_VM_ADMIN_PASSWORD -``` +By default, the _Gpt-4.1 model capacity_ in deployment is set to _30k tokens_, so we recommend: +- **For Global Standard | GPT-4.1** - the capacity to at least 150k tokens post-deployment for optimal performance. -> [!TIP] -> Always review and adjust parameter values (such as region, capacity, security settings and log analytics workspace configuration) to match your organization’s requirements before deploying. For production, ensure you have sufficient quota and follow the principle of least privilege for all identities and role assignments. +- **For Standard | GPT-4** - ensure a minimum of 30k–40k tokens for best results. +> **Note:** When you run `azd up`, the deployment will automatically show you regions with available quota, so this pre-check is optional but helpful for planning purposes. You can customize these settings later in [Step 3.3: Advanced Configuration](#33-advanced-configuration-optional). -> [!IMPORTANT] -> The WAF-aligned configuration is under active development. More Azure Well-Architected recommendations will be added in future updates. +πŸ“– **Adjust Quota:** Follow [Azure AI Model Quota Settings](./AzureAIModelQuotaSettings.md) if needed. -## Deployment Options & Steps +## Step 2: Choose Your Deployment Environment -Pick from the options below to see step-by-step instructions for GitHub Codespaces, VS Code Dev Containers, Visual Studio Code (WEB) and Local Environments. +Select one of the following options to deploy the Document Generation Solution Accelerator: -| [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/microsoft/document-generation-solution-accelerator) | [![Open in Dev Containers](https://img.shields.io/static/v1?style=for-the-badge&label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/microsoft/document-generation-solution-accelerator) | [![Open in Visual Studio Code Web](https://img.shields.io/static/v1?style=for-the-badge&label=Visual%20Studio%20Code%20(Web)&message=Open&color=blue&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/azure/?vscode-azure-exp=foundry&agentPayload=eyJiYXNlVXJsIjogImh0dHBzOi8vcmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbS9taWNyb3NvZnQvZG9jdW1lbnQtZ2VuZXJhdGlvbi1zb2x1dGlvbi1hY2NlbGVyYXRvci9yZWZzL2hlYWRzL21haW4vaW5mcmEvdnNjb2RlX3dlYiIsICJpbmRleFVybCI6ICIvaW5kZXguanNvbiIsICJ2YXJpYWJsZXMiOiB7ImFnZW50SWQiOiAiIiwgImNvbm5lY3Rpb25TdHJpbmciOiAiIiwgInRocmVhZElkIjogIiIsICJ1c2VyTWVzc2FnZSI6ICIiLCAicGxheWdyb3VuZE5hbWUiOiAiIiwgImxvY2F0aW9uIjogIiIsICJzdWJzY3JpcHRpb25JZCI6ICIiLCAicmVzb3VyY2VJZCI6ICIiLCAicHJvamVjdFJlc291cmNlSWQiOiAiIiwgImVuZHBvaW50IjogIiJ9LCAiY29kZVJvdXRlIjogWyJhaS1wcm9qZWN0cy1zZGsiLCAicHl0aG9uIiwgImRlZmF1bHQtYXp1cmUtYXV0aCIsICJlbmRwb2ludCJdfQ==) | -|---|---|--| +### Environment Comparison -
- Deploy in GitHub Codespaces +| **Option** | **Best For** | **Prerequisites** | **Setup Time** | +|------------|--------------|-------------------|----------------| +| **GitHub Codespaces** | Quick deployment, no local setup required | GitHub account | ~3-5 minutes | +| **VS Code Dev Containers** | Fast deployment with local tools | Docker Desktop, VS Code | ~5-10 minutes | +| **VS Code Web** | Quick deployment, no local setup required | Azure account | ~2-4 minutes | +| **Local Environment** | Enterprise environments, full control | All tools individually | ~15-30 minutes | -### GitHub Codespaces +**πŸ’‘ Recommendation:** For fastest deployment, start with **GitHub Codespaces** - no local installation required. -You can run this solution using GitHub Codespaces. The button will open a web-based VS Code instance in your browser: +--- -1. Open the solution accelerator (this may take several minutes): +
+Option A: GitHub Codespaces (Easiest) - [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/microsoft/document-generation-solution-accelerator) +[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/microsoft/document-generation-solution-accelerator) -2. Accept the default values on the create Codespaces page. -3. Open a terminal window if it is not already open. -4. Continue with the [deploying steps](#deploying-with-azd). +1. Click the badge above (may take several minutes to load) +2. Accept default values on the Codespaces creation page +3. Wait for the environment to initialize (includes all deployment tools) +4. Proceed to [Step 3: Configure Deployment Settings](#step-3-configure-deployment-settings)
- Deploy in VS Code Dev Containers - -### VS Code Dev Containers +Option B: VS Code Dev Containers -You can run this solution in VS Code Dev Containers, which will open the project in your local VS Code using the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers): +[![Open in Dev Containers](https://img.shields.io/static/v1?style=for-the-badge&label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/microsoft/document-generation-solution-accelerator) -1. Start Docker Desktop (install it if not already installed). -2. Open the project: +**Prerequisites:** +- [Docker Desktop](https://www.docker.com/products/docker-desktop/) installed and running +- [VS Code](https://code.visualstudio.com/) with [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) - [![Open in Dev Containers](https://img.shields.io/static/v1?style=for-the-badge&label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/microsoft/document-generation-solution-accelerator) - -3. In the VS Code window that opens, once the project files show up (this may take several minutes), open a terminal window. -4. Continue with the [deploying steps](#deploying-with-azd). +**Steps:** +1. Start Docker Desktop +2. Click the badge above to open in Dev Containers +3. Wait for the container to build and start (includes all deployment tools) +4. Proceed to [Step 3: Configure Deployment Settings](#step-3-configure-deployment-settings)
- Deploy in Visual Studio Code (WEB) +Option C: Visual Studio Code Web -### Visual Studio Code (WEB) + [![Open in Visual Studio Code Web](https://img.shields.io/static/v1?style=for-the-badge&label=Visual%20Studio%20Code%20(Web)&message=Open&color=blue&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/azure/?vscode-azure-exp=foundry&agentPayload=eyJiYXNlVXJsIjogImh0dHBzOi8vcmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbS9taWNyb3NvZnQvQ29udGFpbmVyLU1pZ3JhdGlvbi1Tb2x1dGlvbi1BY2NlbGVyYXRvci9yZWZzL2hlYWRzL21haW4vaW5mcmEvdnNjb2RlX3dlYiIsICJpbmRleFVybCI6ICIvaW5kZXguanNvbiIsICJ2YXJpYWJsZXMiOiB7ImFnZW50SWQiOiAiIiwgImNvbm5lY3Rpb25TdHJpbmciOiAiIiwgInRocmVhZElkIjogIiIsICJ1c2VyTWVzc2FnZSI6ICIiLCAicGxheWdyb3VuZE5hbWUiOiAiIiwgImxvY2F0aW9uIjogIiIsICJzdWJzY3JpcHRpb25JZCI6ICIiLCAicmVzb3VyY2VJZCI6ICIiLCAicHJvamVjdFJlc291cmNlSWQiOiAiIiwgImVuZHBvaW50IjogIiJ9LCAiY29kZVJvdXRlIjogWyJhaS1wcm9qZWN0cy1zZGsiLCAicHl0aG9uIiwgImRlZmF1bHQtYXp1cmUtYXV0aCIsICJlbmRwb2ludCJdfQ==) -You can run this solution in VS Code Web. The button will open a web-based VS Code instance in your browser: +1. Click the badge above (may take a few minutes to load) +2. Sign in with your Azure account when prompted +3. Select the subscription where you want to deploy the solution +4. Wait for the environment to initialize (includes all deployment tools) +5. When prompted in the VS Code Web terminal, choose one of the available options shown below: -1. Open the solution accelerator (this may take several minutes): + ![VS Code Initial Prompt](./images/vscodeweb_intialize.png) +6. Proceed to [Step 3: Configure Deployment Settings](#step-3-configure-deployment-settings) - [![Open in Visual Studio Code Web](https://img.shields.io/static/v1?style=for-the-badge&label=Visual%20Studio%20Code%20(Web)&message=Open&color=blue&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/azure/?vscode-azure-exp=foundry&agentPayload=eyJiYXNlVXJsIjogImh0dHBzOi8vcmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbS9taWNyb3NvZnQvZG9jdW1lbnQtZ2VuZXJhdGlvbi1zb2x1dGlvbi1hY2NlbGVyYXRvci9yZWZzL2hlYWRzL21haW4vaW5mcmEvdnNjb2RlX3dlYiIsICJpbmRleFVybCI6ICIvaW5kZXguanNvbiIsICJ2YXJpYWJsZXMiOiB7ImFnZW50SWQiOiAiIiwgImNvbm5lY3Rpb25TdHJpbmciOiAiIiwgInRocmVhZElkIjogIiIsICJ1c2VyTWVzc2FnZSI6ICIiLCAicGxheWdyb3VuZE5hbWUiOiAiIiwgImxvY2F0aW9uIjogIiIsICJzdWJzY3JpcHRpb25JZCI6ICIiLCAicmVzb3VyY2VJZCI6ICIiLCAicHJvamVjdFJlc291cmNlSWQiOiAiIiwgImVuZHBvaW50IjogIiJ9LCAiY29kZVJvdXRlIjogWyJhaS1wcm9qZWN0cy1zZGsiLCAicHl0aG9uIiwgImRlZmF1bHQtYXp1cmUtYXV0aCIsICJlbmRwb2ludCJdfQ==) +
-2. When prompted, sign in using your Microsoft account linked to your Azure subscription. - - Select the appropriate subscription to continue. +
+Option D: Local Environment + +**Required Tools:** +- [PowerShell 7.0+](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell) +- [Azure Developer CLI (azd) 1.18.0+](https://aka.ms/install-azd) +- [Python 3.9+](https://www.python.org/downloads/) +- [Docker Desktop](https://www.docker.com/products/docker-desktop/) +- [Git](https://git-scm.com/downloads) + +**Setup Steps:** +1. Install all required deployment tools listed above +2. Clone the repository: + ```shell + azd init -t microsoft/document-generation-solution-accelerator/ + ``` +3. Open the project folder in your terminal +4. Proceed to [Step 3: Configure Deployment Settings](#step-3-configure-deployment-settings) + +**PowerShell Users:** If you encounter script execution issues, run: +```powershell +Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass +``` -3. Once the solution opens, the **AI Foundry terminal** will automatically start running the following command to install the required dependencies: +
- ```shell - sh install.sh - ``` - During this process, you’ll be prompted with the message: - ``` - What would you like to do with these files? - - Overwrite with versions from template - - Keep my existing files unchanged - ``` - Choose β€œ**Overwrite with versions from template**” and provide a unique environment name when prompted. - -4. Continue with the [deploying steps](#deploying-with-azd). +## Step 3: Configure Deployment Settings -
+Review the configuration options below. You can customize any settings that meet your needs, or leave them as defaults to proceed with a standard deployment. -
- Deploy in your local Environment +### 3.1 Choose Deployment Type (Optional) -### Local Environment +| **Aspect** | **Development/Testing (Default)** | **Production** | +|------------|-----------------------------------|----------------| +| **Configuration File** | `main.parameters.json` (sandbox) | Copy `main.waf.parameters.json` to `main.parameters.json` | +| **Security Controls** | Minimal (for rapid iteration) | Enhanced (production best practices) | +| **Cost** | Lower costs | Cost optimized | +| **Use Case** | POCs, development, testing | Production workloads | +| **Framework** | Basic configuration | [Well-Architected Framework](https://learn.microsoft.com/en-us/azure/well-architected/) | +| **Features** | Core functionality | Reliability, security, operational excellence | -If you're not using one of the above options for opening the project, then you'll need to: +**To use production configuration:** -1. Make sure the following tools are installed: - - [PowerShell](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.5) (v7.0+) - available for Windows, macOS, and Linux. (Required for Windows users only. Follow the steps [here](./PowershellSetup.md) to add it to the Windows PATH.) - - [Azure Developer CLI (azd)](https://aka.ms/install-azd) (v1.18.0+) - version - - [Python 3.9+](https://www.python.org/downloads/) - - [Docker Desktop](https://www.docker.com/products/docker-desktop/) - - [Git](https://git-scm.com/downloads) +Copy the contents from the production configuration file to your main parameters file: -2. Clone the repository or download the project code via command-line: +1. Navigate to the `infra` folder in your project +2. Open `main.waf.parameters.json` in a text editor (like Notepad, VS Code, etc.) +3. Select all content (Ctrl+A) and copy it (Ctrl+C) +4. Open `main.parameters.json` in the same text editor +5. Select all existing content (Ctrl+A) and paste the copied content (Ctrl+V) +6. Save the file (Ctrl+S) - ```shell - azd init -t microsoft/document-generation-solution-accelerator/ - ``` +### 3.2 Set VM Credentials (Optional - Production Deployment Only) -3. Open the project folder in your terminal or editor. -4. Continue with the [deploying steps](#deploying-with-azd). +> **Note:** This section only applies if you selected **Production** deployment type in section 3.1. VMs are not deployed in the default Development/Testing configuration. -
+By default, random GUIDs are generated for VM credentials. To set custom credentials: -
+```shell +azd env set AZURE_ENV_VM_ADMIN_USERNAME +azd env set AZURE_ENV_VM_ADMIN_PASSWORD +``` -Consider the following settings during your deployment to modify specific settings: +### 3.3 Advanced Configuration (Optional)
- Configurable Deployment Settings +Configurable Parameters + +You can customize various deployment settings before running `azd up`, including Azure regions, AI model configurations (deployment type, version, capacity), container registry settings, and resource names. -When you start the deployment, most parameters will have **default values**, but you can update the following settings [here](../docs/CustomizingAzdParameters.md) +πŸ“– **Complete Guide:** See [Parameter Customization Guide](../docs/CustomizingAzdParameters.md) for the full list of available parameters and their usage.
- [Optional] Quota Recommendations +Reuse Existing Resources -By default, the _Gpt-4.1 model capacity_ in deployment is set to _30k tokens_, so we recommend: -- **For Global Standard | GPT-4.1** - the capacity to at least 150k tokens post-deployment for optimal performance. +To optimize costs and integrate with your existing Azure infrastructure, you can configure the solution to reuse compatible resources already deployed in your subscription. -- **For Standard | GPT-4** - ensure a minimum of 30k–40k tokens for best results. +**Supported Resources for Reuse:** -To adjust quota settings, follow these [steps](./AzureGPTQuotaSettings.md). +- **Log Analytics Workspace:** Integrate with your existing monitoring infrastructure by reusing an established Log Analytics workspace for centralized logging and monitoring. [Configuration Guide](./re-use-log-analytics.md) -### ⚠️ Important: Check Azure OpenAI Quota Availability +- **Azure AI Foundry Project:** Leverage your existing AI Foundry project and deployed models to avoid duplication and reduce provisioning time. [Configuration Guide](./re-use-foundry-project.md) -➑️ To ensure sufficient quota is available in your subscription, please follow **[Quota check instructions guide](./QuotaCheck.md)** before you deploy the solution. Insufficient quota can cause deployment errors. Please ensure you have the recommended capacity or request additional capacity before deploying this solution. +**Key Benefits:** +- **Cost Optimization:** Eliminate duplicate resource charges +- **Operational Consistency:** Maintain unified monitoring and AI infrastructure +- **Faster Deployment:** Skip resource creation for existing compatible services +- **Simplified Management:** Reduce the number of resources to manage and monitor + +**Important Considerations:** +- Ensure existing resources meet the solution's requirements and are in compatible regions +- Review access permissions and configurations before reusing resources +- Consider the impact on existing workloads when sharing resources
-
+## Step 4: Deploy the Solution - Reusing an Existing Log Analytics Workspace +πŸ’‘ **Before You Start:** If you encounter any issues during deployment, check our [Troubleshooting Guide](./TroubleShootingSteps.md) for common solutions. - Guide to get your [Existing Workspace ID](/docs/re-use-log-analytics.md) +### 4.1 Authenticate with Azure -
-
+```shell +azd auth login +``` - Reusing an Existing Azure AI Foundry Project +**For specific tenants:** +```shell +azd auth login --tenant-id +``` - Guide to get your [Existing Project ID](/docs/re-use-foundry-project.md) +> **Finding Tenant ID:** + > 1. Open the [Azure Portal](https://portal.azure.com/). + > 2. Navigate to **Microsoft Entra ID** from the left-hand menu. + > 3. Under the **Overview** section, locate the **Tenant ID** field. Copy the value displayed. -
+### 4.2 Start Deployment -### Deploying with AZD +```shell +azd up +``` -Once you've opened the project in [Codespaces](#github-codespaces), [Dev Containers](#vs-code-dev-containers), [Visual Studio Code (WEB)](#visual-studio-code-web) or [locally](#local-environment), you can deploy it to Azure by following these steps: +**During deployment, you'll be prompted for:** +1. **Environment name** (e.g., "docgen") - Must be 3-16 characters long, alphanumeric only +2. **Azure subscription** selection +3. **Azure AI Foundry deployment region** - Select a region with available o3 model quota for AI operations +4. **Primary location** - Select the region where your infrastructure resources will be deployed +5. **Resource group** selection (create new or use existing) -1. Login to Azure: +**Expected Duration:** 4-6 minutes for default configuration - ```shell - azd auth login - ``` +**⚠️ Deployment Issues:** If you encounter errors or timeouts, try a different region as there may be capacity constraints. For detailed error solutions, see our [Troubleshooting Guide](./TroubleShootingSteps.md). - #### To authenticate with Azure Developer CLI (`azd`), use the following command with your **Tenant ID**: +### 4.3 Get Application URL - ```sh - azd auth login --tenant-id - ``` +After successful deployment: +1. Open [Azure Portal](https://portal.azure.com/) +2. Navigate to your resource group +3. Find the Container App with "frontend" in the name +4. Copy the **Application URI** -2. Provision and deploy all the resources: +⚠️ **Important:** Complete [Post-Deployment Steps](#step-5-post-deployment-configuration) before accessing the application. - ```shell - azd up - ``` - > **Note:** This solution accelerator requires **Azure Developer CLI (azd) version 1.18.0 or higher**. Please ensure you have the latest version installed before proceeding with deployment. [Download azd here](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd). +## Step 5: Post-Deployment Configuration -3. Provide an `azd` environment name (e.g., "dgapp"). -4. Select a subscription from your Azure account and choose a location that has quota for all the resources. - - This deployment generally takes *7-10 minutes* to provision the resources in your account and set up the solution with sample data. - - If you encounter an error or timeout during deployment, changing the location may help, as there could be availability constraints for the resources. +### 5.1 Sample Data Import -5. Once the deployment has completed successfully and you would like to use the sample data, please open a **Git Bash** terminal and run the bash command printed below. The bash command will look like the following: +1. Once the deployment has completed successfully and you would like to use the sample data, please open a **Git Bash** terminal and run the bash command printed below. The bash command will look like the following: ```shell bash ./infra/scripts/process_sample_data.sh ``` @@ -239,49 +287,169 @@ Once you've opened the project in [Codespaces](#github-codespaces), [Dev Contain bash ./infra/scripts/process_sample_data.sh ``` -6. Open the [Azure Portal](https://portal.azure.com/), go to the deployed resource group, find the App Service and get the app URL from `Default domain`. +2. Open the [Azure Portal](https://portal.azure.com/), go to the deployed resource group, find the App Service and get the app URL from `Default domain`. + +### 5.2 Configure Authentication (Optional) -7. You can now delete the resources by running `azd down`, if you are done trying out the application. - > **Note:** If you deployed with `enableRedundancy=true` and Log Analytics workspace replication is enabled, you must first disable replication before running `azd down` else resource group delete will fail. Follow the steps in [Handling Log Analytics Workspace Deletion with Replication Enabled](./LogAnalyticsReplicationDisable.md), wait until replication returns `false`, then run `azd down`. +1. Follow [App Authentication Configuration](./ConfigureAppAuthentication.md) +2. Wait up to 10 minutes for authentication changes to take effect -### πŸ› οΈ Troubleshooting - If you encounter any issues during the deployment process, please refer [troubleshooting](../docs/TroubleShootingSteps.md) document for detailed steps and solutions +### 5.3 Verify Deployment -## Post Deployment Steps +1. Access your application using the URL from Step 4.3 +2. Confirm the application loads successfully +3. Verify you can sign in with your authenticated account -1. **Add App Authentication** +## Step 6: Clean Up (Optional) - > Note: Authentication changes can take up to 10 minutes +### Remove All Resources +```shell +azd down +``` +> **Note:** If you deployed with `enableRedundancy=true` and Log Analytics workspace replication is enabled, you must first disable replication before running `azd down` else resource group delete will fail. Follow the steps in [Handling Log Analytics Workspace Deletion with Replication Enabled](./LogAnalyticsReplicationDisable.md), wait until replication returns `false`, then run `azd down`. + +### Manual Cleanup (if needed) +If deployment fails or you need to clean up manually: +- Follow [Delete Resource Group Guide](./DeleteResourceGroup.md) - Follow steps in [App Authentication](./AppAuthentication.md) to configure authentication in app service. +## Managing Multiple Environments -2. **Deleting Resources After a Failed Deployment** +### Recover from Failed Deployment - - Follow steps in [Delete Resource Group](./DeleteResourceGroup.md) if your deployment fails and/or you need to clean up the resources. +If your deployment failed or encountered errors, here are the steps to recover: + +
+Recover from Failed Deployment -## Deploy Your Local Changes +**If your deployment failed or encountered errors:** -To deploy your local changes, rename the below files: +1. **Try a different region:** Create a new environment and select a different Azure region during deployment +2. **Clean up and retry:** Use `azd down` to remove failed resources, then `azd up` to redeploy +3. **Check troubleshooting:** Review [Troubleshooting Guide](./TroubleShootingSteps.md) for specific error solutions +4. **Fresh start:** Create a completely new environment with a different name -1. Rename `azure.yaml` to `azure_custom2.yaml` and `azure_custom.yaml` to `azure.yaml`. +**Example Recovery Workflow:** +```shell +# Remove failed deployment (optional) +azd down + +# Create new environment (3-16 chars, alphanumeric only) +azd env new conmigretry + +# Deploy with different settings/region +azd up +``` + +
+ +### Creating a New Environment + +If you need to deploy to a different region, test different configurations, or create additional environments: + +
+Create a New Environment -2. **Go to `infra` directory:** - - Rename `main.bicep` to `main_custom2.bicep` and `main_custom.bicep` to `main.bicep`. +**Create Environment Explicitly:** +```shell +# Create a new named environment (3-16 characters, alphanumeric only) +azd env new -3. Continue with the [deploying steps](#deploying-with-azd). +# Select the new environment +azd env select -## Environment configuration for local development & debugging -> Set APP_ENV in your .env file to control Azure authentication. Set the environment variable to dev to use Azure CLI credentials, or to prod to use Managed Identity for production. **Ensure you're logged in via az login when using dev in local**. -To configure your environment, follow these steps: -1. Navigate to the `src` folder. -2. Create a `.env` file based on the `.env.sample` file. -3. Fill in the `.env` file using the deployment output or by checking the Azure Portal under "Deployments" in your resource group. -4. Alternatively, if resources were - provisioned using `azd provision` or `azd up`, a `.env` file is automatically generated in the `.azure//.env` - file. To get your `` run `azd env list` to see which env is default. -5. Ensure that `APP_ENV` is set to "**dev**" in your `.env` file. +# Deploy to the new environment +azd up +``` + +**Example:** +```shell +# Create a new environment for production (valid: 3-16 chars) +azd env new conmigprod + +# Switch to the new environment +azd env select conmigprod + +# Deploy with fresh settings +azd up +``` + +> **Environment Name Requirements:** +> - **Length:** 3-16 characters +> - **Characters:** Alphanumeric only (letters and numbers) +> - **Valid examples:** `conmig`, `test123`, `myappdev`, `prod2024` +> - **Invalid examples:** `co` (too short), `my-very-long-environment-name` (too long), `test_env` (underscore not allowed), `myapp-dev` (hyphen not allowed) + +
+ +
+Switch Between Environments + +**List Available Environments:** +```shell +azd env list +``` + +**Switch to Different Environment:** +```shell +azd env select +``` + +**View Current Environment:** +```shell +azd env get-values +``` + +
+ +### Best Practices for Multiple Environments + +- **Use descriptive names:** `conmigdev`, `conmigprod`, `conmigtest` (remember: 3-16 chars, alphanumeric only) +- **Different regions:** Deploy to multiple regions for testing quota availability +- **Separate configurations:** Each environment can have different parameter settings +- **Clean up unused environments:** Use `azd down` to remove environments you no longer need ## Next Steps -Now that you've completed your deployment, you can start using the solution. -To help you get started, here are some [Sample Questions](./SampleQuestions.md) you can follow to try it out. +Now that your deployment is complete and tested, explore these resources to enhance your experience: + +πŸ“š **Learn More:** +- [Technical Architecture](./TechnicalArchitecture.md) - Understand the system design and components +- [Customize Expert Agents](./CustomizeExpertAgents.md) - Tailor AI agents to your specific needs +- [Extend Platform Support](./ExtendPlatformSupport.md) - Add support for additional container platforms +- [Configure MCP Servers](./ConfigureMCPServers.md) - Set up Model Context Protocol servers +- [Local Development Setup](./LocalDevelopmentSetup.md) - Set up your local development environment + +## Need Help? + +- πŸ› **Issues:** Check [Troubleshooting Guide](./TroubleShootingSteps.md) +- πŸ’¬ **Support:** Review [Support Guidelines](../SUPPORT.md) +- πŸ”§ **Development:** See [Contributing Guide](../CONTRIBUTING.md) + +--- + +## Advanced: Deploy Local Changes + +If you've made local modifications to the code and want to deploy them to Azure, follow these steps to swap the configuration files: + +> **Note:** To set up and run the application locally for development, see the [Local Development Setup Guide](./LocalDevelopmentSetup.md). + +### Step 1: Rename Azure Configuration Files + +**In the root directory:** +1. Rename `azure.yaml` to `azure_custom2.yaml` +2. Rename `azure_custom.yaml` to `azure.yaml` + +### Step 2: Rename Infrastructure Files + +**In the `infra` directory:** +1. Rename `main.bicep` to `main_custom2.bicep` +2. Rename `main_custom.bicep` to `main.bicep` + +### Step 3: Deploy Changes + +Run the deployment command: +```shell +azd up +``` + +> **Note:** These custom files are configured to deploy your local code changes instead of pulling from the GitHub repository. \ No newline at end of file diff --git a/docs/DeploymentGuideNew.md b/docs/DeploymentGuideNew.md deleted file mode 100644 index 8740ee36..00000000 --- a/docs/DeploymentGuideNew.md +++ /dev/null @@ -1,455 +0,0 @@ -# Deployment Guide - -## Overview - -This guide walks you through deploying the Document Generation Solution Accelerator to Azure. The deployment process takes approximately 10-15 minutes for the default Development/Testing configuration and includes both infrastructure provisioning and application setup. - -πŸ†˜ **Need Help?** If you encounter any issues during deployment, check our [Troubleshooting Guide](./TroubleShootingSteps.md) for solutions to common problems. - -## Step 1: Prerequisites & Setup - -### 1.1 Azure Account Requirements - -Ensure you have access to an [Azure subscription](https://azure.microsoft.com/free/) with the following permissions: - -| **Required Permission/Role** | **Scope** | **Purpose** | -|------------------------------|-----------|-------------| -| **Contributor** | Subscription level | Create and manage Azure resources | -| **User Access Administrator** | Subscription level | Manage user access and role assignments | -| **Role Based Access Control** | Subscription/Resource Group level | Configure RBAC permissions | -| **App Registration Creation** | Azure Active Directory | Create and configure authentication | - -**πŸ” How to Check Your Permissions:** - -1. Go to [Azure Portal](https://portal.azure.com/) -2. Navigate to **Subscriptions** (search for "subscriptions" in the top search bar) -3. Click on your target subscription -4. In the left menu, click **Access control (IAM)** -5. Scroll down to see the table with your assigned roles - you should see: - - **Contributor** - - **User Access Administrator** - - **Role Based Access Control Administrator** (or similar RBAC role) - -**For App Registration permissions:** -1. Go to **Microsoft Entra ID** β†’ **Manage** β†’ **App registrations** -2. Try clicking **New registration** -3. If you can access this page, you have the required permissions -4. Cancel without creating an app registration - -πŸ“– **Detailed Setup:** Follow [Azure Account Set Up](./AzureAccountSetup.md) for complete configuration. - -### 1.2 Check Service Availability & Quota - -⚠️ **CRITICAL:** Before proceeding, ensure your chosen region has all required services available: - -**Required Azure Services:** -- [Azure AI Foundry](https://learn.microsoft.com/en-us/azure/ai-foundry/) -- [Azure OpenAI Service](https://learn.microsoft.com/en-us/azure/ai-services/openai/) -- [Azure Cosmos DB](https://learn.microsoft.com/en-us/azure/cosmos-db/) -- [Azure AI Search](https://learn.microsoft.com/en-us/azure/search/) - -**Recommended Regions:** East US, East US2, Australia East, UK South, France Central. - -πŸ” **Check Availability:** Use [Azure Products by Region](https://azure.microsoft.com/en-us/explore/global-infrastructure/products-by-region/) to verify service availability. - -### 1.3 Quota Check (Optional) - -πŸ’‘ **RECOMMENDED:** Check your Azure OpenAI quota availability before deployment for optimal planning. - -πŸ“– **Follow:** [Quota Check Instructions](./QuotaCheck.md) to ensure sufficient capacity. - -By default, the _Gpt-4.1 model capacity_ in deployment is set to _30k tokens_, so we recommend: -- **For Global Standard | GPT-4.1** - the capacity to at least 150k tokens post-deployment for optimal performance. - -- **For Standard | GPT-4** - ensure a minimum of 30k–40k tokens for best results. - -> **Note:** When you run `azd up`, the deployment will automatically show you regions with available quota, so this pre-check is optional but helpful for planning purposes. You can customize these settings later in [Step 3.3: Advanced Configuration](#33-advanced-configuration-optional). - -πŸ“– **Adjust Quota:** Follow [Azure AI Model Quota Settings](./AzureAIModelQuotaSettings.md) if needed. - -## Step 2: Choose Your Deployment Environment - -Select one of the following options to deploy the Document Generation Solution Accelerator: - -### Environment Comparison - -| **Option** | **Best For** | **Prerequisites** | **Setup Time** | -|------------|--------------|-------------------|----------------| -| **GitHub Codespaces** | Quick deployment, no local setup required | GitHub account | ~3-5 minutes | -| **VS Code Dev Containers** | Fast deployment with local tools | Docker Desktop, VS Code | ~5-10 minutes | -| **VS Code Web** | Quick deployment, no local setup required | Azure account | ~2-4 minutes | -| **Local Environment** | Enterprise environments, full control | All tools individually | ~15-30 minutes | - -**πŸ’‘ Recommendation:** For fastest deployment, start with **GitHub Codespaces** - no local installation required. - ---- - -
-Option A: GitHub Codespaces (Easiest) - -[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/microsoft/document-generation-solution-accelerator) - -1. Click the badge above (may take several minutes to load) -2. Accept default values on the Codespaces creation page -3. Wait for the environment to initialize (includes all deployment tools) -4. Proceed to [Step 3: Configure Deployment Settings](#step-3-configure-deployment-settings) - -
- -
-Option B: VS Code Dev Containers - -[![Open in Dev Containers](https://img.shields.io/static/v1?style=for-the-badge&label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/microsoft/document-generation-solution-accelerator) - -**Prerequisites:** -- [Docker Desktop](https://www.docker.com/products/docker-desktop/) installed and running -- [VS Code](https://code.visualstudio.com/) with [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) - -**Steps:** -1. Start Docker Desktop -2. Click the badge above to open in Dev Containers -3. Wait for the container to build and start (includes all deployment tools) -4. Proceed to [Step 3: Configure Deployment Settings](#step-3-configure-deployment-settings) - -
- -
-Option C: Visual Studio Code Web - - [![Open in Visual Studio Code Web](https://img.shields.io/static/v1?style=for-the-badge&label=Visual%20Studio%20Code%20(Web)&message=Open&color=blue&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/azure/?vscode-azure-exp=foundry&agentPayload=eyJiYXNlVXJsIjogImh0dHBzOi8vcmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbS9taWNyb3NvZnQvQ29udGFpbmVyLU1pZ3JhdGlvbi1Tb2x1dGlvbi1BY2NlbGVyYXRvci9yZWZzL2hlYWRzL21haW4vaW5mcmEvdnNjb2RlX3dlYiIsICJpbmRleFVybCI6ICIvaW5kZXguanNvbiIsICJ2YXJpYWJsZXMiOiB7ImFnZW50SWQiOiAiIiwgImNvbm5lY3Rpb25TdHJpbmciOiAiIiwgInRocmVhZElkIjogIiIsICJ1c2VyTWVzc2FnZSI6ICIiLCAicGxheWdyb3VuZE5hbWUiOiAiIiwgImxvY2F0aW9uIjogIiIsICJzdWJzY3JpcHRpb25JZCI6ICIiLCAicmVzb3VyY2VJZCI6ICIiLCAicHJvamVjdFJlc291cmNlSWQiOiAiIiwgImVuZHBvaW50IjogIiJ9LCAiY29kZVJvdXRlIjogWyJhaS1wcm9qZWN0cy1zZGsiLCAicHl0aG9uIiwgImRlZmF1bHQtYXp1cmUtYXV0aCIsICJlbmRwb2ludCJdfQ==) - -1. Click the badge above (may take a few minutes to load) -2. Sign in with your Azure account when prompted -3. Select the subscription where you want to deploy the solution -4. Wait for the environment to initialize (includes all deployment tools) -5. When prompted in the VS Code Web terminal, choose one of the available options shown below: - - ![VS Code Initial Prompt](./images/vscodeweb_intialize.png) -6. Proceed to [Step 3: Configure Deployment Settings](#step-3-configure-deployment-settings) - -
- -
-Option D: Local Environment - -**Required Tools:** -- [PowerShell 7.0+](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell) -- [Azure Developer CLI (azd) 1.18.0+](https://aka.ms/install-azd) -- [Python 3.9+](https://www.python.org/downloads/) -- [Docker Desktop](https://www.docker.com/products/docker-desktop/) -- [Git](https://git-scm.com/downloads) - -**Setup Steps:** -1. Install all required deployment tools listed above -2. Clone the repository: - ```shell - azd init -t microsoft/document-generation-solution-accelerator/ - ``` -3. Open the project folder in your terminal -4. Proceed to [Step 3: Configure Deployment Settings](#step-3-configure-deployment-settings) - -**PowerShell Users:** If you encounter script execution issues, run: -```powershell -Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -``` - -
- -## Step 3: Configure Deployment Settings - -Review the configuration options below. You can customize any settings that meet your needs, or leave them as defaults to proceed with a standard deployment. - -### 3.1 Choose Deployment Type (Optional) - -| **Aspect** | **Development/Testing (Default)** | **Production** | -|------------|-----------------------------------|----------------| -| **Configuration File** | `main.parameters.json` (sandbox) | Copy `main.waf.parameters.json` to `main.parameters.json` | -| **Security Controls** | Minimal (for rapid iteration) | Enhanced (production best practices) | -| **Cost** | Lower costs | Cost optimized | -| **Use Case** | POCs, development, testing | Production workloads | -| **Framework** | Basic configuration | [Well-Architected Framework](https://learn.microsoft.com/en-us/azure/well-architected/) | -| **Features** | Core functionality | Reliability, security, operational excellence | - -**To use production configuration:** - -Copy the contents from the production configuration file to your main parameters file: - -1. Navigate to the `infra` folder in your project -2. Open `main.waf.parameters.json` in a text editor (like Notepad, VS Code, etc.) -3. Select all content (Ctrl+A) and copy it (Ctrl+C) -4. Open `main.parameters.json` in the same text editor -5. Select all existing content (Ctrl+A) and paste the copied content (Ctrl+V) -6. Save the file (Ctrl+S) - -### 3.2 Set VM Credentials (Optional - Production Deployment Only) - -> **Note:** This section only applies if you selected **Production** deployment type in section 3.1. VMs are not deployed in the default Development/Testing configuration. - -By default, random GUIDs are generated for VM credentials. To set custom credentials: - -```shell -azd env set AZURE_ENV_VM_ADMIN_USERNAME -azd env set AZURE_ENV_VM_ADMIN_PASSWORD -``` - -### 3.3 Advanced Configuration (Optional) - -
-Configurable Parameters - -You can customize various deployment settings before running `azd up`, including Azure regions, AI model configurations (deployment type, version, capacity), container registry settings, and resource names. - -πŸ“– **Complete Guide:** See [Parameter Customization Guide](../docs/CustomizingAzdParameters.md) for the full list of available parameters and their usage. - -
- -
-Reuse Existing Resources - -To optimize costs and integrate with your existing Azure infrastructure, you can configure the solution to reuse compatible resources already deployed in your subscription. - -**Supported Resources for Reuse:** - -- **Log Analytics Workspace:** Integrate with your existing monitoring infrastructure by reusing an established Log Analytics workspace for centralized logging and monitoring. [Configuration Guide](./re-use-log-analytics.md) - -- **Azure AI Foundry Project:** Leverage your existing AI Foundry project and deployed models to avoid duplication and reduce provisioning time. [Configuration Guide](./re-use-foundry-project.md) - -**Key Benefits:** -- **Cost Optimization:** Eliminate duplicate resource charges -- **Operational Consistency:** Maintain unified monitoring and AI infrastructure -- **Faster Deployment:** Skip resource creation for existing compatible services -- **Simplified Management:** Reduce the number of resources to manage and monitor - -**Important Considerations:** -- Ensure existing resources meet the solution's requirements and are in compatible regions -- Review access permissions and configurations before reusing resources -- Consider the impact on existing workloads when sharing resources - -
- -## Step 4: Deploy the Solution - -πŸ’‘ **Before You Start:** If you encounter any issues during deployment, check our [Troubleshooting Guide](./TroubleShootingSteps.md) for common solutions. - -### 4.1 Authenticate with Azure - -```shell -azd auth login -``` - -**For specific tenants:** -```shell -azd auth login --tenant-id -``` - -> **Finding Tenant ID:** - > 1. Open the [Azure Portal](https://portal.azure.com/). - > 2. Navigate to **Microsoft Entra ID** from the left-hand menu. - > 3. Under the **Overview** section, locate the **Tenant ID** field. Copy the value displayed. - -### 4.2 Start Deployment - -```shell -azd up -``` - -**During deployment, you'll be prompted for:** -1. **Environment name** (e.g., "docgen") - Must be 3-16 characters long, alphanumeric only -2. **Azure subscription** selection -3. **Azure AI Foundry deployment region** - Select a region with available o3 model quota for AI operations -4. **Primary location** - Select the region where your infrastructure resources will be deployed -5. **Resource group** selection (create new or use existing) - -**Expected Duration:** 4-6 minutes for default configuration - -**⚠️ Deployment Issues:** If you encounter errors or timeouts, try a different region as there may be capacity constraints. For detailed error solutions, see our [Troubleshooting Guide](./TroubleShootingSteps.md). - -### 4.3 Get Application URL - -After successful deployment: -1. Open [Azure Portal](https://portal.azure.com/) -2. Navigate to your resource group -3. Find the Container App with "frontend" in the name -4. Copy the **Application URI** - -⚠️ **Important:** Complete [Post-Deployment Steps](#step-5-post-deployment-configuration) before accessing the application. - -## Step 5: Post-Deployment Configuration - -### 5.1 Sample Data Import - -1. Once the deployment has completed successfully and you would like to use the sample data, please open a **Git Bash** terminal and run the bash command printed below. The bash command will look like the following: - ```shell - bash ./infra/scripts/process_sample_data.sh - ``` - If you don't have azd env then you need to pass parameters along with the command. Then the command will look like the following: - ```shell - bash ./infra/scripts/process_sample_data.sh - ``` - -2. Open the [Azure Portal](https://portal.azure.com/), go to the deployed resource group, find the App Service and get the app URL from `Default domain`. - -### 5.2 Configure Authentication (Optional) - -1. Follow [App Authentication Configuration](./ConfigureAppAuthentication.md) -2. Wait up to 10 minutes for authentication changes to take effect - -### 5.3 Verify Deployment - -1. Access your application using the URL from Step 4.3 -2. Confirm the application loads successfully -3. Verify you can sign in with your authenticated account - -## Step 6: Clean Up (Optional) - -### Remove All Resources -```shell -azd down -``` -> **Note:** If you deployed with `enableRedundancy=true` and Log Analytics workspace replication is enabled, you must first disable replication before running `azd down` else resource group delete will fail. Follow the steps in [Handling Log Analytics Workspace Deletion with Replication Enabled](./LogAnalyticsReplicationDisable.md), wait until replication returns `false`, then run `azd down`. - -### Manual Cleanup (if needed) -If deployment fails or you need to clean up manually: -- Follow [Delete Resource Group Guide](./DeleteResourceGroup.md) - -## Managing Multiple Environments - -### Recover from Failed Deployment - -If your deployment failed or encountered errors, here are the steps to recover: - -
-Recover from Failed Deployment - -**If your deployment failed or encountered errors:** - -1. **Try a different region:** Create a new environment and select a different Azure region during deployment -2. **Clean up and retry:** Use `azd down` to remove failed resources, then `azd up` to redeploy -3. **Check troubleshooting:** Review [Troubleshooting Guide](./TroubleShootingSteps.md) for specific error solutions -4. **Fresh start:** Create a completely new environment with a different name - -**Example Recovery Workflow:** -```shell -# Remove failed deployment (optional) -azd down - -# Create new environment (3-16 chars, alphanumeric only) -azd env new conmigretry - -# Deploy with different settings/region -azd up -``` - -
- -### Creating a New Environment - -If you need to deploy to a different region, test different configurations, or create additional environments: - -
-Create a New Environment - -**Create Environment Explicitly:** -```shell -# Create a new named environment (3-16 characters, alphanumeric only) -azd env new - -# Select the new environment -azd env select - -# Deploy to the new environment -azd up -``` - -**Example:** -```shell -# Create a new environment for production (valid: 3-16 chars) -azd env new conmigprod - -# Switch to the new environment -azd env select conmigprod - -# Deploy with fresh settings -azd up -``` - -> **Environment Name Requirements:** -> - **Length:** 3-16 characters -> - **Characters:** Alphanumeric only (letters and numbers) -> - **Valid examples:** `conmig`, `test123`, `myappdev`, `prod2024` -> - **Invalid examples:** `co` (too short), `my-very-long-environment-name` (too long), `test_env` (underscore not allowed), `myapp-dev` (hyphen not allowed) - -
- -
-Switch Between Environments - -**List Available Environments:** -```shell -azd env list -``` - -**Switch to Different Environment:** -```shell -azd env select -``` - -**View Current Environment:** -```shell -azd env get-values -``` - -
- -### Best Practices for Multiple Environments - -- **Use descriptive names:** `conmigdev`, `conmigprod`, `conmigtest` (remember: 3-16 chars, alphanumeric only) -- **Different regions:** Deploy to multiple regions for testing quota availability -- **Separate configurations:** Each environment can have different parameter settings -- **Clean up unused environments:** Use `azd down` to remove environments you no longer need - -## Next Steps - -Now that your deployment is complete and tested, explore these resources to enhance your experience: - -πŸ“š **Learn More:** -- [Technical Architecture](./TechnicalArchitecture.md) - Understand the system design and components -- [Customize Expert Agents](./CustomizeExpertAgents.md) - Tailor AI agents to your specific needs -- [Extend Platform Support](./ExtendPlatformSupport.md) - Add support for additional container platforms -- [Configure MCP Servers](./ConfigureMCPServers.md) - Set up Model Context Protocol servers -- [Local Development Setup](./LocalDevelopmentSetup.md) - Set up your local development environment - -## Need Help? - -- πŸ› **Issues:** Check [Troubleshooting Guide](./TroubleShootingSteps.md) -- πŸ’¬ **Support:** Review [Support Guidelines](../SUPPORT.md) -- πŸ”§ **Development:** See [Contributing Guide](../CONTRIBUTING.md) - ---- - -## Advanced: Deploy Local Changes - -If you've made local modifications to the code and want to deploy them to Azure, follow these steps to swap the configuration files: - -> **Note:** To set up and run the application locally for development, see the [Local Development Setup Guide](./LocalDevelopmentSetup.md). - -### Step 1: Rename Azure Configuration Files - -**In the root directory:** -1. Rename `azure.yaml` to `azure_custom2.yaml` -2. Rename `azure_custom.yaml` to `azure.yaml` - -### Step 2: Rename Infrastructure Files - -**In the `infra` directory:** -1. Rename `main.bicep` to `main_custom2.bicep` -2. Rename `main_custom.bicep` to `main.bicep` - -### Step 3: Deploy Changes - -Run the deployment command: -```shell -azd up -``` - -> **Note:** These custom files are configured to deploy your local code changes instead of pulling from the GitHub repository. \ No newline at end of file From 4e65c3f54dc5e186612e9f814b3f4dc9bed24aa0 Mon Sep 17 00:00:00 2001 From: Ajit Padhi Date: Wed, 3 Dec 2025 13:24:31 +0530 Subject: [PATCH 4/7] updated deployement readme --- docs/DeploymentGuide.md | 26 ++++++++++++-------------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/docs/DeploymentGuide.md b/docs/DeploymentGuide.md index 8740ee36..7d1ab558 100644 --- a/docs/DeploymentGuide.md +++ b/docs/DeploymentGuide.md @@ -75,10 +75,10 @@ Select one of the following options to deploy the Document Generation Solution A | **Option** | **Best For** | **Prerequisites** | **Setup Time** | |------------|--------------|-------------------|----------------| -| **GitHub Codespaces** | Quick deployment, no local setup required | GitHub account | ~3-5 minutes | -| **VS Code Dev Containers** | Fast deployment with local tools | Docker Desktop, VS Code | ~5-10 minutes | -| **VS Code Web** | Quick deployment, no local setup required | Azure account | ~2-4 minutes | -| **Local Environment** | Enterprise environments, full control | All tools individually | ~15-30 minutes | +| **GitHub Codespaces** | Quick deployment, no local setup required | GitHub account | ~5-7 minutes | +| **VS Code Dev Containers** | Fast deployment with local tools | Docker Desktop, VS Code | ~6-10 minutes | +| **VS Code Web** | Quick deployment, no local setup required | Azure account | ~6-8 minutes | +| **Local Environment** | Enterprise environments, full control | All tools individually | ~7-10 minutes | **πŸ’‘ Recommendation:** For fastest deployment, start with **GitHub Codespaces** - no local installation required. @@ -256,11 +256,11 @@ azd up **During deployment, you'll be prompted for:** 1. **Environment name** (e.g., "docgen") - Must be 3-16 characters long, alphanumeric only 2. **Azure subscription** selection -3. **Azure AI Foundry deployment region** - Select a region with available o3 model quota for AI operations +3. **Azure AI Foundry deployment region** - Select a region with available OpenAI model quota for AI operations 4. **Primary location** - Select the region where your infrastructure resources will be deployed 5. **Resource group** selection (create new or use existing) -**Expected Duration:** 4-6 minutes for default configuration +**Expected Duration:** 6-8 minutes for default configuration **⚠️ Deployment Issues:** If you encounter errors or timeouts, try a different region as there may be capacity constraints. For detailed error solutions, see our [Troubleshooting Guide](./TroubleShootingSteps.md). @@ -269,7 +269,7 @@ azd up After successful deployment: 1. Open [Azure Portal](https://portal.azure.com/) 2. Navigate to your resource group -3. Find the Container App with "frontend" in the name +3. Find the App Service with "app" in the name 4. Copy the **Application URI** ⚠️ **Important:** Complete [Post-Deployment Steps](#step-5-post-deployment-configuration) before accessing the application. @@ -278,7 +278,7 @@ After successful deployment: ### 5.1 Sample Data Import -1. Once the deployment has completed successfully and you would like to use the sample data, please open a **Git Bash** terminal and run the bash command printed below. The bash command will look like the following: + Once the deployment has completed successfully and you would like to use the sample data, please open a **Git Bash** terminal and run the bash command printed below. The bash command will look like the following: ```shell bash ./infra/scripts/process_sample_data.sh ``` @@ -287,8 +287,6 @@ After successful deployment: bash ./infra/scripts/process_sample_data.sh ``` -2. Open the [Azure Portal](https://portal.azure.com/), go to the deployed resource group, find the App Service and get the app URL from `Default domain`. - ### 5.2 Configure Authentication (Optional) 1. Follow [App Authentication Configuration](./ConfigureAppAuthentication.md) @@ -334,7 +332,7 @@ If your deployment failed or encountered errors, here are the steps to recover: azd down # Create new environment (3-16 chars, alphanumeric only) -azd env new conmigretry +azd env new docgenretry # Deploy with different settings/region azd up @@ -364,10 +362,10 @@ azd up **Example:** ```shell # Create a new environment for production (valid: 3-16 chars) -azd env new conmigprod +azd env new docgenprod # Switch to the new environment -azd env select conmigprod +azd env select docgenprod # Deploy with fresh settings azd up @@ -376,7 +374,7 @@ azd up > **Environment Name Requirements:** > - **Length:** 3-16 characters > - **Characters:** Alphanumeric only (letters and numbers) -> - **Valid examples:** `conmig`, `test123`, `myappdev`, `prod2024` +> - **Valid examples:** `docgen`, `test123`, `myappdev`, `prod2024` > - **Invalid examples:** `co` (too short), `my-very-long-environment-name` (too long), `test_env` (underscore not allowed), `myapp-dev` (hyphen not allowed) From 965ca2fd3558c3af17089b5c1d3be955566f2dfa Mon Sep 17 00:00:00 2001 From: Ajit Padhi Date: Wed, 3 Dec 2025 13:35:09 +0530 Subject: [PATCH 5/7] Improved deployment guide --- docs/DeploymentGuide.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/DeploymentGuide.md b/docs/DeploymentGuide.md index 7d1ab558..21b17e4c 100644 --- a/docs/DeploymentGuide.md +++ b/docs/DeploymentGuide.md @@ -2,7 +2,7 @@ ## Overview -This guide walks you through deploying the Document Generation Solution Accelerator to Azure. The deployment process takes approximately 10-15 minutes for the default Development/Testing configuration and includes both infrastructure provisioning and application setup. +This guide walks you through deploying the Document Generation Solution Accelerator to Azure. The deployment process takes approximately 7-10 minutes for the default Development/Testing configuration and includes both infrastructure provisioning and application setup. πŸ†˜ **Need Help?** If you encounter any issues during deployment, check our [Troubleshooting Guide](./TroubleShootingSteps.md) for solutions to common problems. @@ -58,10 +58,9 @@ Ensure you have access to an [Azure subscription](https://azure.microsoft.com/fr πŸ“– **Follow:** [Quota Check Instructions](./QuotaCheck.md) to ensure sufficient capacity. -By default, the _Gpt-4.1 model capacity_ in deployment is set to _30k tokens_, so we recommend: -- **For Global Standard | GPT-4.1** - the capacity to at least 150k tokens post-deployment for optimal performance. - -- **For Standard | GPT-4** - ensure a minimum of 30k–40k tokens for best results. +**Recommended Configuration:** +- **Default:** 150k tokens (minimum) +- **Optimal:** More than 150k tokens (for best performance) > **Note:** When you run `azd up`, the deployment will automatically show you regions with available quota, so this pre-check is optional but helpful for planning purposes. You can customize these settings later in [Step 3.3: Advanced Configuration](#33-advanced-configuration-optional). From 1fbd6126e58157ff8ea2db2ea390455dc33435d6 Mon Sep 17 00:00:00 2001 From: Ajit Padhi Date: Wed, 3 Dec 2025 14:24:33 +0530 Subject: [PATCH 6/7] link error fixed --- docs/DeploymentGuide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/DeploymentGuide.md b/docs/DeploymentGuide.md index 21b17e4c..27063ec5 100644 --- a/docs/DeploymentGuide.md +++ b/docs/DeploymentGuide.md @@ -36,7 +36,7 @@ Ensure you have access to an [Azure subscription](https://azure.microsoft.com/fr 3. If you can access this page, you have the required permissions 4. Cancel without creating an app registration -πŸ“– **Detailed Setup:** Follow [Azure Account Set Up](./AzureAccountSetup.md) for complete configuration. +πŸ“– **Detailed Setup:** Follow [Azure Account Set Up](./AzureAccountSetUp.md) for complete configuration. ### 1.2 Check Service Availability & Quota @@ -64,7 +64,7 @@ Ensure you have access to an [Azure subscription](https://azure.microsoft.com/fr > **Note:** When you run `azd up`, the deployment will automatically show you regions with available quota, so this pre-check is optional but helpful for planning purposes. You can customize these settings later in [Step 3.3: Advanced Configuration](#33-advanced-configuration-optional). -πŸ“– **Adjust Quota:** Follow [Azure AI Model Quota Settings](./AzureAIModelQuotaSettings.md) if needed. +πŸ“– **Adjust Quota:** Follow [Azure AI Model Quota Settings](./AzureGPTQuotaSettings.md) if needed. ## Step 2: Choose Your Deployment Environment From 43dc8d6c2795566ac91419a23cfdb1e862e7a6e0 Mon Sep 17 00:00:00 2001 From: Ajit Padhi Date: Wed, 3 Dec 2025 15:38:33 +0530 Subject: [PATCH 7/7] fixed link check issue --- SUPPORT.md | 13 +++++++++++++ docs/DeploymentGuide.md | 21 +++++++++++++-------- docs/LocalDevelopmentSetup.md | 0 3 files changed, 26 insertions(+), 8 deletions(-) create mode 100644 SUPPORT.md create mode 100644 docs/LocalDevelopmentSetup.md diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 00000000..2c42db0f --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,13 @@ +# Support + +## How to file issues and get help + +This project uses GitHub Issues to track bugs and feature requests. Please search the existing +issues before filing new issues to avoid duplicates. For new issues, file your bug or +feature request as a new Issue. + +For help and questions about using this project, please submit an issue on this repository. + +## Microsoft Support Policy + +Support for this repository is limited to the resources listed above. \ No newline at end of file diff --git a/docs/DeploymentGuide.md b/docs/DeploymentGuide.md index 27063ec5..ffc5bccd 100644 --- a/docs/DeploymentGuide.md +++ b/docs/DeploymentGuide.md @@ -121,9 +121,18 @@ Select one of the following options to deploy the Document Generation Solution A 2. Sign in with your Azure account when prompted 3. Select the subscription where you want to deploy the solution 4. Wait for the environment to initialize (includes all deployment tools) -5. When prompted in the VS Code Web terminal, choose one of the available options shown below: +5. Once the solution opens, the **AI Foundry terminal** will automatically start running the following command to install the required dependencies: - ![VS Code Initial Prompt](./images/vscodeweb_intialize.png) + ```shell + sh install.sh + ``` + During this process, you’ll be prompted with the message: + ``` + What would you like to do with these files? + - Overwrite with versions from template + - Keep my existing files unchanged + ``` + Choose β€œ**Overwrite with versions from template**” and provide a unique environment name when prompted. 6. Proceed to [Step 3: Configure Deployment Settings](#step-3-configure-deployment-settings) @@ -277,7 +286,7 @@ After successful deployment: ### 5.1 Sample Data Import - Once the deployment has completed successfully and you would like to use the sample data, please open a **Git Bash** terminal and run the bash command printed below. The bash command will look like the following: +1. Once the deployment has completed successfully and you would like to use the sample data, please open a **Git Bash** terminal and run the bash command printed below. The bash command will look like the following: ```shell bash ./infra/scripts/process_sample_data.sh ``` @@ -288,7 +297,7 @@ After successful deployment: ### 5.2 Configure Authentication (Optional) -1. Follow [App Authentication Configuration](./ConfigureAppAuthentication.md) +1. Follow [App Authentication Configuration](./AppAuthentication.md) 2. Wait up to 10 minutes for authentication changes to take effect ### 5.3 Verify Deployment @@ -410,10 +419,6 @@ azd env get-values Now that your deployment is complete and tested, explore these resources to enhance your experience: πŸ“š **Learn More:** -- [Technical Architecture](./TechnicalArchitecture.md) - Understand the system design and components -- [Customize Expert Agents](./CustomizeExpertAgents.md) - Tailor AI agents to your specific needs -- [Extend Platform Support](./ExtendPlatformSupport.md) - Add support for additional container platforms -- [Configure MCP Servers](./ConfigureMCPServers.md) - Set up Model Context Protocol servers - [Local Development Setup](./LocalDevelopmentSetup.md) - Set up your local development environment ## Need Help? diff --git a/docs/LocalDevelopmentSetup.md b/docs/LocalDevelopmentSetup.md new file mode 100644 index 00000000..e69de29b