From 3f5fe9a3bc075a601fa6111d5ba5931c7823a706 Mon Sep 17 00:00:00 2001 From: Harsh-Microsoft Date: Wed, 3 Dec 2025 18:32:16 +0530 Subject: [PATCH 1/4] docs: Revise structure and enhance Deployment Guide --- docs/DeploymentGuide.md | 659 ++++++++++++++++------------------ docs/LocalDevelopmentSetup.md | 0 2 files changed, 313 insertions(+), 346 deletions(-) create mode 100644 docs/LocalDevelopmentSetup.md diff --git a/docs/DeploymentGuide.md b/docs/DeploymentGuide.md index 4ad2ae65..d7ba7752 100644 --- a/docs/DeploymentGuide.md +++ b/docs/DeploymentGuide.md @@ -1,44 +1,48 @@ # Deployment Guide -## **๐Ÿš€ Quick Start** +## Overview -Get your Content Processing Solution up and running in Azure with this streamlined process: +This guide walks you through deploying the Content Processing Solution Accelerator to Azure. The deployment process takes approximately 15-20 minutes for the default Development/Testing configuration and includes both infrastructure provisioning and application setup. -1. **๐Ÿ” Verify Access** - Confirm you have the right Azure permissions and quota -2. **๐Ÿ—๏ธ Set Up Environment** - Create a fresh deployment environment -3. **๐Ÿš€ Deploy to Azure** - Let Azure Developer CLI handle the infrastructure provisioning -4. **โœ… Configure & Validate** - Complete setup and verify everything works +๐Ÿ†˜ **Need Help?** If you encounter any issues during deployment, check our [Troubleshooting Guide](./TroubleShootingSteps.md) for solutions to common problems. -> **๐Ÿ› ๏ธ Having Issues?** Our [Troubleshooting Guide](./TroubleShootingSteps.md) has solutions for common deployment problems. +## Step 1: Prerequisites & Setup ---- - -## **Pre-requisites** +### 1.1 Azure Account Requirements -### Required Permissions & Access +Ensure you have access to an [Azure subscription](https://azure.microsoft.com/free/) with the following permissions: -To deploy this solution accelerator, you need **Azure subscription access** with the following permissions: +| **Required Permission/Role** | **Scope** | **Purpose** | +|------------------------------|-----------|-------------| +| **Contributor** | Subscription or Resource Group | Create and manage Azure resources | +| **User Access Administrator** | Subscription or Resource Group | Manage user access and role assignments | +| **Role Based Access Control** | Subscription/Resource Group level | Configure RBAC permissions | +| **Application Administrator** | Tenant | Create app registrations for authentication | -**โœ… Recommended Permissions:** -- **Owner** role at the subscription or resource group level -- **User Access Administrator** role at the subscription or resource group level +**๐Ÿ” How to Check Your Permissions:** -> **Note:** These elevated permissions are required because the deployment creates Managed Identities and assigns roles to them automatically. +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) -**โš ๏ธ Alternative Least-Privilege Setup:** -If you cannot use Owner + User Access Administrator roles, you'll need the following minimum permissions: +**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 -| Permission | Required For | Scope | -|------------|-------------|-------| -| **Contributor** | Creating and managing Azure resources | Subscription or Resource Group | -| **User Access Administrator** | Assigning roles to Managed Identities | Resource Group | -| **Application Administrator** (Azure AD) | Creating app registrations for authentication | Tenant | -| **Role Based Access Control Administrator** | Managing role assignments | Resource Group | +๐Ÿ“– **Detailed Setup:** Follow [Azure Account Set Up](./AzureAccountSetup.md) for complete configuration. -> **Important:** With least-privilege setup, you may need to perform some manual steps during deployment. Follow the steps in [Azure Account Set Up](./AzureAccountSetup.md) for detailed guidance. +### 1.2 Check Service Availability & Quota -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: +โš ๏ธ **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 AI Content Understanding Service](https://learn.microsoft.com/en-us/azure/ai-services/content-understanding/) @@ -49,48 +53,35 @@ Check the [Azure Products by Region](https://azure.microsoft.com/en-us/explore/g - [Azure Queue Storage](https://learn.microsoft.com/en-us/azure/storage/queues/) - [GPT Model Capacity](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models) -Here are some example regions where the services are available: East US, East US2, Australia East, UK South, France Central. - -### **Important: Note for PowerShell Users** - -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: - -```powershell -Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -``` +**Recommended Regions:** East US, East US2, Australia East, UK South, France Central. -This will allow the scripts to run for the current session without permanently changing your system's policy. +๐Ÿ” **Check Availability:** Use [Azure Products by Region](https://azure.microsoft.com/en-us/explore/global-infrastructure/products-by-region/) to verify service availability. -### **Important: Check Azure OpenAI Quota Availability** +### 1.3 Quota Check (Optional) -โš ๏ธ To ensure sufficient quota is available in your subscription, please follow [quota check instructions guide](./quota_check.md) before you deploy the solution. +๐Ÿ’ก **RECOMMENDED:** Check your Azure OpenAI quota availability before deployment for optimal planning. -### ๐Ÿ› ๏ธ Troubleshooting & Common Issues +๐Ÿ“– **Follow:** [Quota Check Instructions](./quota_check.md) to ensure sufficient capacity. -**Before starting deployment**, be aware of these common issues and solutions: +**Recommended Configuration:** +- **Default:** 100k tokens +- **Optimal:** 100k tokens (recommended for best performance) -| **Common Issue** | **Quick Solution** | **Full Guide Link** | -|-----------------|-------------------|---------------------| -| **ReadOnlyDisabledSubscription** | Check if you have an active subscription | [Troubleshooting Guide](./TroubleShootingSteps.md#readonlydisabledsubscription) | -| **InsufficientQuota** | Verify quota availability | [Quota Check Guide](./quota_check.md) | -| **ResourceGroupNotFound** | Create new environment with `azd env new` | [Troubleshooting Guide](./TroubleShootingSteps.md#resourcegroupnotfound) | -| **InvalidParameter (Workspace Name)** | Use compliant names (3-33 chars, alphanumeric) | [Troubleshooting Guide](./TroubleShootingSteps.md#workspace-name---invalidparameter) | -| **ResourceNameInvalid** | Follow Azure naming conventions | [Troubleshooting Guide](./TroubleShootingSteps.md#resourcenameinvalid) | +> **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). -> **If you encounter deployment errors:** Refer to the [complete troubleshooting guide](./TroubleShootingSteps.md) with comprehensive error solutions. +๐Ÿ“– **Adjust Quota:** Follow [Azure GPT Quota Settings](./AzureGPTQuotaSettings.md) if needed. +## Step 2: Choose Your Deployment Environment -## Choose Your Deployment Environment - -Select one of the following options to deploy the Accelerator: +Select one of the following options to deploy the Content Processing Solution Accelerator: ### Environment Comparison | **Option** | **Best For** | **Prerequisites** | **Setup Time** | |------------|--------------|-------------------|----------------| -| **GitHub Codespaces** | Quick deployment, no local setup required | GitHub account with Codespace enabled | ~3-5 minutes | +| **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 | -| **Visual Studio Code (WEB)** | Quick deployment, no local setup required | Azure account | ~2-4 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. @@ -98,55 +89,44 @@ Select one of the following options to deploy the Accelerator: ---
- Option 1: Deploy in GitHub Codespaces - -### GitHub Codespaces - -You can run this solution using [GitHub Codespaces](https://docs.github.com/en/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/content-processing-solution-accelerator) +[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/microsoft/content-processing-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)
- Option 2: Deploy in VS Code Dev Containers +Option B: VS Code Dev Containers -### 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/content-processing-solution-accelerator) -You can run this solution in [VS Code Dev Containers](https://code.visualstudio.com/docs/devcontainers/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): +**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) -1. Start Docker Desktop (install it if not already installed). -2. Open the project: - - [![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/content-processing-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)
- Option 3:Deploy in Visual Studio Code (WEB) - -### Visual Studio Code (WEB) +Option C: Visual Studio Code Web -You can run this solution in VS Code Web. The button will open a web-based VS Code instance in your browser: + [![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=eyJiYXNlVXJsIjogImh0dHBzOi8vcmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbS9taWNyb3NvZnQvY29udGVudC1wcm9jZXNzaW5nLXNvbHV0aW9uLWFjY2VsZXJhdG9yL3JlZnMvaGVhZHMvbWFpbi9pbmZyYS92c2NvZGVfd2ViIiwgImluZGV4VXJsIjogIi9pbmRleC5qc29uIiwgInZhcmlhYmxlcyI6IHsiYWdlbnRJZCI6ICIiLCAiY29ubmVjdGlvblN0cmluZyI6ICIiLCAidGhyZWFkSWQiOiAiIiwgInVzZXJNZXNzYWdlIjogIiIsICJwbGF5Z3JvdW5kTmFtZSI6ICIiLCAibG9jYXRpb24iOiAiIiwgInN1YnNjcmlwdGlvbklkIjogIiIsICJyZXNvdXJjZUlkIjogIiIsICJwcm9qZWN0UmVzb3VyY2VJZCI6ICIiLCAiZW5kcG9pbnQiOiAiIn0sICJjb2RlUm91dGUiOiBbImFpLXByb2plY3RzLXNkayIsICJweXRob24iLCAiZGVmYXVsdC1henVyZS1hdXRoIiwgImVuZHBvaW50Il19) -1. Open the solution accelerator (this may take several minutes): - - [![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=eyJiYXNlVXJsIjogImh0dHBzOi8vcmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbS9taWNyb3NvZnQvY29udGVudC1wcm9jZXNzaW5nLXNvbHV0aW9uLWFjY2VsZXJhdG9yL3JlZnMvaGVhZHMvbWFpbi9pbmZyYS92c2NvZGVfd2ViIiwgImluZGV4VXJsIjogIi9pbmRleC5qc29uIiwgInZhcmlhYmxlcyI6IHsiYWdlbnRJZCI6ICIiLCAiY29ubmVjdGlvblN0cmluZyI6ICIiLCAidGhyZWFkSWQiOiAiIiwgInVzZXJNZXNzYWdlIjogIiIsICJwbGF5Z3JvdW5kTmFtZSI6ICIiLCAibG9jYXRpb24iOiAiIiwgInN1YnNjcmlwdGlvbklkIjogIiIsICJyZXNvdXJjZUlkIjogIiIsICJwcm9qZWN0UmVzb3VyY2VJZCI6ICIiLCAiZW5kcG9pbnQiOiAiIn0sICJjb2RlUm91dGUiOiBbImFpLXByb2plY3RzLXNkayIsICJweXRob24iLCAiZGVmYXVsdC1henVyZS1hdXRoIiwgImVuZHBvaW50Il19) - -2. When prompted, sign in using your Microsoft account linked to your Azure subscription. - - Select the appropriate subscription to continue. - -3. Once the solution opens, the **AI Foundry terminal** will automatically start running the following command to install the required dependencies: +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. Once the solution opens, the **AI Foundry terminal** will automatically start running the following command to install the required dependencies: ```shell sh install.sh @@ -158,38 +138,41 @@ You can run this solution in VS Code Web. The button will open a web-based VS Co - 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). - +6. Proceed to [Step 3: Configure Deployment Settings](#step-3-configure-deployment-settings)
- Option 4: Deploy in your local Environment - -### Local Environment - -If you're not using one of the above options for opening the project, then you'll need to: - -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. - - [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) - -2. Clone the repository or download the project code via command-line: +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/content-processing-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 +``` - ```shell - azd init -t microsoft/content-processing-solution-accelerator/ - ``` +
-3. Open the project folder in your terminal or editor. -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. -### Choose Deployment Type (Optional) +### 3.1 Choose Deployment Type (Optional) | **Aspect** | **Development/Testing (Default)** | **Production** | |------------|-----------------------------------|----------------| @@ -204,9 +187,6 @@ If you're not using one of the above options for opening the project, then you'l Copy the contents from the production configuration file to your main parameters file: -
-Option 1: Manual Copy (Recommended for beginners) - 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) @@ -214,26 +194,7 @@ Copy the contents from the production configuration file to your main parameters 5. Select all existing content (Ctrl+A) and paste the copied content (Ctrl+V) 6. Save the file (Ctrl+S) -
- -
-Option 2: Using Command Line - -**For Linux/macOS/Git Bash:** -```bash -# Copy contents from production file to main parameters file -cat infra/main.waf.parameters.json > infra/main.parameters.json -``` - -**For Windows PowerShell:** -```powershell -# Copy contents from production file to main parameters file -Get-Content infra/main.waf.parameters.json | Set-Content infra/main.parameters.json -``` - -
- -### Set VM Credentials (Optional - Production Deployment Only) +### 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. @@ -244,330 +205,336 @@ 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: - -
- Configurable Deployment Settings - -When you start the deployment, most parameters will have **default values**, but you can update the following settings by following the steps [here](../docs/CustomizingAzdParameters.md) - -
+### 3.3 Advanced Configuration (Optional)
- [Optional] Quota Recommendations +Configurable Parameters -By default, the **GPT model capacity** in deployment is set to **30k tokens**. -> **We recommend increasing the capacity to 100k tokens, if available, for optimal performance.** +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. -To adjust quota settings, follow these [steps](./AzureGPTQuotaSettings.md). - -**โš ๏ธ Warning:** Insufficient quota can cause deployment errors. Please ensure you have the recommended capacity or request additional capacity before deploying this solution. +๐Ÿ“– **Complete Guide:** See [Parameter Customization Guide](../docs/CustomizingAzdParameters.md) for the full list of available parameters and their usage.
+Reuse Existing Resources - Reusing an Existing Log Analytics Workspace +To optimize costs and integrate with your existing Azure infrastructure, you can configure the solution to reuse compatible resources already deployed in your subscription. - Guide to get your [Existing Workspace ID](/docs/re-use-log-analytics.md) +**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) - Reusing an Existing Azure AI Foundry Project +**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 - Guide to get your [Existing Project ID](/docs/re-use-foundry-project.md) +**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
-### Deploying with AZD - -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: +## Step 4: Deploy the Solution -#### Important: Environment Management for Redeployments +๐Ÿ’ก **Before You Start:** If you encounter any issues during deployment, check our [Troubleshooting Guide](./TroubleShootingSteps.md) for common solutions. -> **โš ๏ธ Critical:** If you're redeploying or have deployed this solution before, you **must** create a fresh environment to avoid conflicts and deployment failures. +### 4.1 Authenticate with Azure -**Choose one of the following before deployment:** +```shell +azd auth login +``` -**Option A: Create a completely new environment (Recommended)** +**For specific tenants:** ```shell -azd env new +azd auth login --tenant-id ``` -**Option B: Reinitialize in a new directory** +> **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 -# Navigate to a new directory -cd ../my-new-deployment -azd init -t microsoft/content-processing-solution-accelerator +azd up ``` -> **๐Ÿ’ก Why is this needed?** Azure resources maintain state information tied to your environment. Reusing an old environment can cause naming conflicts, permission issues, and deployment failures. +**During deployment, you'll be prompted for:** +1. **Environment name** - Must be 3-20 characters, lowercase alphanumeric only (e.g., `cpsapp01`). +2. **Azure subscription** selection. +3. **Azure AI Foundry deployment region** - Select a region with available gpt-4o 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) -#### Environment Naming Requirements +**Expected Duration:** 4-6 minutes for default configuration. -When creating your environment name, follow these rules: -- **Maximum 14 characters** (will be expanded to meet Azure resource naming requirements) -- **Only lowercase letters and numbers** (a-z, 0-9) -- **No special characters** (-, _, spaces, etc.) -- **Examples:** `cpsapp01`, `mycontentapp`, `devtest123` +**โš ๏ธ 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). -> **๐Ÿ’ก Tip:** Use a descriptive prefix + environment + suffix to form a a unique string +### 4.3 Get Application URL -#### Deployment Steps +After successful deployment: +1. The terminal will display the Name, Endpoint (Application URL), and Azure Portal URL for both the Web and API Azure Container Apps. + + ![](./images/cp-post-deployment.png) -> If you encounter any issues during the deployment process, refer to the [troubleshooting guide](../docs/TroubleShootingSteps.md) for detailed steps and solutions. +2. Copy the **Web App Endpoint** to access the application. -1. Login to Azure: +โš ๏ธ **Important:** Complete [Post-Deployment Steps](#step-5-post-deployment-configuration) before accessing the application. - ```shell - azd auth login - ``` +## Step 5: Post-Deployment Configuration - #### To authenticate with Azure Developer CLI (`azd`), use the following command with your **Tenant ID**: +### 5.1 Register Schema Files - ```sh - azd auth login --tenant-id - ``` + > Want to customize the schemas for your own documents? [Learn more about adding your own schemas here.](./CustomizeSchemaData.md) - > **Note:** To retrieve the Tenant ID required for local deployment, you can go to **Tenant Properties** in [Azure Portal](https://portal.azure.com/) from the resource list. Alternatively, follow these steps: - > - > 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. +The below steps will add two sample schemas to the solution: _Invoice_ and _Property Loss Damage Claim Form_: -2. Provision and deploy all the resources: +1. **Get API Service's Endpoint** + - Get API Service Endpoint Url from your container app for API - ```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). + Name is **ca-**<< your environmentName >>-**api** + ![Check API Service Url](./images/CheckAPIService.png) -3. **Provide an `azd` environment name** - Use the naming requirements above (e.g., "cpsapp01"). -4. Select a subscription from your Azure account and choose a location that has quota for all the resources. - - This deployment will take *4-6 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. + - Copy the URL -5. Once the deployment has completed successfully: - > Please check the terminal or console output for details of the successful deployment. It will display the Name, Endpoint (Application URL), and Azure Portal URL for both the Web and API Azure Container Apps. +2. **Execute Script to registering Schemas** + - Move the folder to samples/schemas in ContentProcessorApi - [/src/ContentProcessorApi/samples/schemas](/src/ContentProcessorApi/samples/schemas) - ![](./images/cp-post-deployment.png) + + Git Bash - - You can find the Azure portal link in the screenshot above. Click on it to navigate to the corresponding resource group in the Azure portal. + ```bash + cd src/ContentProcessorAPI/samples/schemas + ``` - > #### Important Note : Before accessing the application, ensure that all **[Post Deployment Steps](#post-deployment-steps)** are fully completed, as they are critical for the proper configuration of **Data Ingestion** and **Authentication** functionalities. + Powershell -> If you encounter any issues during the deployment process, refer to the [troubleshooting guide](../docs/TroubleShootingSteps.md) for detailed steps and solutions. + ```Powershell + cd .\src\ContentProcessorAPI\samples\schemas\ + ``` -## Post Deployment Steps -1. **Register Schema Files** + - Then use below command - > Want to customize the schemas for your own documents? [Learn more about adding your own schemas here.](./CustomizeSchemaData.md) + Git Bash - The below steps will add two sample schemas to the solution: _Invoice_ and _Property Loss Damage Claim Form_: + ```bash + ./register_schema.sh https://<< API Service Endpoint>>/schemavault/ schema_info_sh.json + ``` - - **Get API Service's Endpoint** - - Get API Service Endpoint Url from your container app for API - Name is **ca-**<< your environmentName >>-**api** - ![Check API Service Url](./images/CheckAPIService.png) + Powershell - - Copy the URL - - **Execute Script to registering Schemas** - - Move the folder to samples/schemas in ContentProcessorApi - [/src/ContentProcessorApi/samples/schemas](/src/ContentProcessorApi/samples/schemas) + ```Powershell + ./register_schema.ps1 https://<< API Service Endpoint>>/schemavault/ .\schema_info_ps1.json + ``` - - Git Bash +3. **Verify Results** - ```bash - cd src/ContentProcessorAPI/samples/schemas - ``` + ![schema file registration](./images/SchemaFileRegistration.png) - Powershell +### 5.2 Import Sample Data +1. Grab the Schema IDs for Invoice and Property Damage Claim Form's Schema from first step +2. Move to the folder location to samples in ContentProcessorApi - [/src/ContentProcessorApi/samples/](/src/ContentProcessorApi/samples/) +3. Execute the script with Schema IDs - ```Powershell - cd .\src\ContentProcessorAPI\samples\schemas\ - ``` + Bash - - Then use below command + ```bash + ./upload_files.sh https://<< API Service Endpoint >>/contentprocessor/submit ./invoices <> + ``` - Git Bash + ```bash + ./upload_files.sh https://<< API Service Endpoint >>/contentprocessor/submit ./propertyclaims <> + ``` - ```bash - ./register_schema.sh https://<< API Service Endpoint>>/schemavault/ schema_info_sh.json - ``` + Windows - Powershell + ```powershell + ./upload_files.ps1 https://<< API Service Endpoint >>/contentprocessor/submit .\invoices <> + ``` - ```Powershell - ./register_schema.ps1 https://<< API Service Endpoint>>/schemavault/ .\schema_info_ps1.json - ``` + ```powershell + ./upload_files.ps1 https://<< API Service Endpoint >>/contentprocessor/submit .\propertyclaims <> + ``` - - **Verify Results** - - ![schema file registration](./images/SchemaFileRegistration.png) +### 5.3 Configure Authentication (Required) -3. **Import Sample Data** - - Grab the Schema IDs for Invoice and Property Damage Claim Form's Schema from first step - - Move to the folder location to samples in ContentProcessorApi - [/src/ContentProcessorApi/samples/](/src/ContentProcessorApi/samples/) - - Execute the script with Schema IDs +**This step is mandatory for application access:** - Bash +1. Follow [App Authentication Configuration](./ConfigureAppAuthentication.md). +2. Wait up to 10 minutes for authentication changes to take effect. - ```bash - ./upload_files.sh https://<< API Service Endpoint >>/contentprocessor/submit ./invoices <> - ``` +### 5.4 Verify Deployment - ```bash - ./upload_files.sh https://<< API Service Endpoint >>/contentprocessor/submit ./propertyclaims <> - ``` +**Deployment Validation Checklist:** - Windows +1. Access your application using the URL from [Step 4.3](#43-get-application-url). +2. Confirm the application loads successfully. +3. Verify you can sign in with your authenticated account. - ```powershell - ./upload_files.ps1 https://<< API Service Endpoint >>/contentprocessor/submit .\invoices <> - ``` +### 5.5 Test the Application - ```powershell - ./upload_files.ps1 https://<< API Service Endpoint >>/contentprocessor/submit .\propertyclaims <> - ``` +**Quick Test Steps:** +1. **Download Samples**: Get sample files from the [samples directory](../src/ContentProcessorAPI/samples). +2. **Upload**: In the app, select a **Schema** (e.g., Invoice), click Import Content, and upload a sample file. +3. **Review**: Wait for completion (~1 min), then click the row to verify the extracted data against the source document. -2. **Add Authentication Provider** - - Follow steps in [App Authentication](./ConfigureAppAuthentication.md) to configure authentication in app service. Note that Authentication changes can take up to 10 minutes. +๐Ÿ“– **Detailed Instructions:** See the complete [Sample Workflow](./SampleWorkflow.md) guide for step-by-step testing procedures. -## Deployment Success Validation +## Step 6: Clean Up (Optional) -After deployment completes, use this checklist to verify everything is working correctly: +### 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`. -### Deployment Validation Checklist +### Manual Cleanup (if needed) +If deployment fails or you need to clean up manually: +- Follow [Delete Resource Group Guide](./DeleteResourceGroup.md). -**1. Basic Deployment Verification** -- [ ] `azd up` completed successfully without errors -- [ ] All Azure resources are created in the resource group -- [ ] Both Web and API container apps are running +## Managing Multiple Environments -**2. Container Apps Health Check** -```powershell -# Test Web App (replace with actual URL from deployment output) -curl -I https:/// +### Recover from Failed Deployment -# Test API App (replace with actual URL) -curl -I https:///health -``` -**Expected Result:** Both should return HTTP 200 status +If your deployment failed or encountered errors, here are the steps to recover: +
+Recover from Failed Deployment -### Sample Test Commands +**If your deployment failed or encountered errors:** -**API Health Check:** -```bash -curl https:///health -``` +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 -**Web App Accessibility:** -```bash -curl -I https:/// -``` +**Example Recovery Workflow:** +```shell +# Remove failed deployment (optional) +azd down -**Schema Registration Verification:** -```bash -curl https:///schemavault/schemas +# Create new environment (3-20 chars, alphanumeric only) +azd env new conpro2 + +# Deploy with different settings/region +azd up ``` -## Running the application +
-To help you get started, here's the [Sample Workflow](./SampleWorkflow.md) you can follow to try it out. +### Creating a New Environment -## Clean Up Resources +If you need to deploy to a different region, test different configurations, or create additional environments: -When you're done testing the solution or need to clean up after deployment issues, you have several options: +
+Create a New Environment -### ๐Ÿงน Environment Cleanup +**Create Environment Explicitly:** +```shell +# Create a new named environment (3-20 characters, lowercase alphanumeric only) +azd env new -**To clean up azd environments:** -```powershell -# List all environments -azd env list +# Select the new environment +azd env select -# Clean up a specific environment -azd env select -azd down --force --purge +# Deploy to the new environment +azd up ``` -> **Tip:** If you have old environments that failed deployment or are no longer needed, use the commands above to clean them up before creating new ones. +**Example:** +```shell +# Create a new environment for production (valid: 3-20 chars) +azd env new conproprod -> **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`. +# Switch to the new environment +azd env select conproprod -### ๐Ÿ—‘๏ธ Azure Resource Group Cleanup +# Deploy with fresh settings +azd up +``` -**To clean up Azure resource groups (if needed):** -```powershell -# List resource groups -az group list --output table +> **Environment Naming Requirements:** +> - **Length:** 3-20 characters +> - **Characters:** Lowercase alphanumeric only (a-z, 0-9) +> - **No special characters** (-, _, spaces, etc.) +> - **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) -# Delete a specific resource group -az group delete --name --yes --no-wait -``` +
+ +
+Switch Between Environments -### ๐Ÿ“ Deleting Resources After a Failed Deployment +**List Available Environments:** +```shell +azd env list +``` -- Follow detailed steps in [Delete Resource Group](./DeleteResourceGroup.md) if your deployment fails and/or you need to clean up the resources. +**Switch to Different Environment:** +```shell +azd env select +``` -> **โš ๏ธ Important:** Always ensure you want to permanently delete resources before running cleanup commands. These operations cannot be undone. +
-### Troubleshooting Failed Validation +### Best Practices for Multiple Environments -**If any checks fail:** -1. Check Azure Portal โ†’ Resource Group โ†’ Container Apps for error logs -2. Review deployment logs: `azd show` -3. Verify all post-deployment steps are completed -4. Check [Troubleshooting Guide](./TroubleShootingSteps.md) for specific error solutions +- **Use descriptive names:** `conprodev`, `conproprod`, `conprotest` (remember: 3-20 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 validated your deployment, you can start add your own schema or modify the existing one to meet your requirements: +Now that your deployment is complete and tested, explore these resources: -### Getting Started -* **Create Custom Schemas:** [Learn how to add your own document schemas](./CustomizeSchemaData.md) +- [Create Custom Schemas](./CustomizeSchemaData.md) - Learn how to add your own document schemas +- [API Integration](API.md) - Explore programmatic document processing +- [Local Development Setup](./LocalDevelopmentSetup.md) - Set up your local development environment -* **API Integration:** [Explore programmatic document processing](API.md) +## Need Help? -## Local Development +- ๐Ÿ› **Issues:** Check [Troubleshooting Guide](./TroubleShootingSteps.md) +- ๐Ÿ’ฌ **Support:** Review [Support Guidelines](../SUPPORT.md) +- ๐Ÿ”ง **Development:** See [Contributing Guide](../CONTRIBUTING.md) -If you need to modify the source code and test changes locally, follow these steps: - -### Publishing Local Build Container to Azure Container Registry +--- -To rebuild the source code and push the updated container to the deployed Azure Container Registry: +## Advanced: Deploy Local Code Changes -- **Linux/macOS**: - ```bash - cd ./infra/scripts/ +Use this method to quickly deploy code changes from your local machine to your existing Azure deployment without re-provisioning infrastructure. - ./docker-build.sh - ``` +> **Note:** To set up and run the application locally for development, see the [Local Development Setup Guide](./LocalDevelopmentSetup.md). -- **Windows (PowerShell)**: - ```powershell - cd .\infra\scripts\ +### How it Works +This process will: +1. Rebuild the Docker containers locally using your modified source code. +2. Push the new images to your Azure Container Registry (ACR). +3. Restart the Azure Container Apps to pick up the new images. - .\docker-build.ps1 - ``` +### Prerequisites +- **Docker Desktop** must be installed and running. +- You must have an active deployment environment selected (`azd env select `). -This will rebuild the source code, package it into a container, and push it to the Azure Container Registry created during deployment. +### Deployment Steps -### Environment Configuration for Local Development & Debugging +Run the build and push script for your operating system: -**Creating env file** +**Linux/macOS:** +```bash +./infra/scripts/docker-build.sh +``` -> Navigate to the `src` folder of the project. +**Windows (PowerShell):** +```powershell +./infra/scripts/docker-build.ps1 +``` -1. Locate the `.env` file inside the `src` directory. -2. To fill in the required values, follow these steps: - - Go to the Azure Portal. - - Navigate to your **Resource Group**. - - Open the **Web Container** resource. - - In the left-hand menu, select **Containers**. - - Go to the **Environment Variables** tab. - - Copy the necessary environment variable values and paste them into your local `.env` file. - +> **Note:** These scripts will deploy your local code changes instead of pulling from the GitHub repository. diff --git a/docs/LocalDevelopmentSetup.md b/docs/LocalDevelopmentSetup.md new file mode 100644 index 00000000..e69de29b From 5bfeb56a2836fe5a6643e18d42bde03ed573a8c8 Mon Sep 17 00:00:00 2001 From: Harsh-Microsoft Date: Wed, 3 Dec 2025 18:46:01 +0530 Subject: [PATCH 2/4] docs: Add link to Technical Architecture in Deployment Guide --- docs/DeploymentGuide.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/DeploymentGuide.md b/docs/DeploymentGuide.md index d7ba7752..2e62e919 100644 --- a/docs/DeploymentGuide.md +++ b/docs/DeploymentGuide.md @@ -495,6 +495,7 @@ azd env select Now that your deployment is complete and tested, explore these resources: +- [Technical Architecture](./TechnicalArchitecture.md) - Understand the system design and components - [Create Custom Schemas](./CustomizeSchemaData.md) - Learn how to add your own document schemas - [API Integration](API.md) - Explore programmatic document processing - [Local Development Setup](./LocalDevelopmentSetup.md) - Set up your local development environment From cb1f8578b9232b2c96e6c1ef6329900bf5bea101 Mon Sep 17 00:00:00 2001 From: Harsh-Microsoft Date: Wed, 3 Dec 2025 19:31:30 +0530 Subject: [PATCH 3/4] docs: Update Deployment Guide to include environment variable retrieval --- docs/DeploymentGuide.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/DeploymentGuide.md b/docs/DeploymentGuide.md index 2e62e919..cbc82b48 100644 --- a/docs/DeploymentGuide.md +++ b/docs/DeploymentGuide.md @@ -372,8 +372,6 @@ The below steps will add two sample schemas to the solution: _Invoice_ and _Prop ### 5.4 Verify Deployment -**Deployment Validation Checklist:** - 1. Access your application using the URL from [Step 4.3](#43-get-application-url). 2. Confirm the application loads successfully. 3. Verify you can sign in with your authenticated account. @@ -482,6 +480,11 @@ azd env list azd env select ``` +**View Current Environment Variables:** +```shell +azd env get-values +``` + ### Best Practices for Multiple Environments From 759fb478e2ce87ce444def972b67231213dd8760 Mon Sep 17 00:00:00 2001 From: Harsh-Microsoft Date: Thu, 4 Dec 2025 19:42:50 +0530 Subject: [PATCH 4/4] docs: Update valid examples in Deployment Guide for environment name requirements --- docs/DeploymentGuide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/DeploymentGuide.md b/docs/DeploymentGuide.md index cbc82b48..3f52c900 100644 --- a/docs/DeploymentGuide.md +++ b/docs/DeploymentGuide.md @@ -462,7 +462,7 @@ azd up > - **Length:** 3-20 characters > - **Characters:** Lowercase alphanumeric only (a-z, 0-9) > - **No special characters** (-, _, spaces, etc.) -> - **Valid examples:** `conmig`, `test123`, `myappdev`, `prod2024` +> - **Valid examples:** `conpro`, `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)