diff --git a/docs/DeploymentGuide.md b/docs/DeploymentGuide.md index c3701330..ccaab1e6 100644 --- a/docs/DeploymentGuide.md +++ b/docs/DeploymentGuide.md @@ -1,259 +1,483 @@ -# Deployment Guide +# 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, and assign roles at the resource group level***. Follow the steps in [Azure Account Set Up](AzureAccountSetUp.md) +This guide walks you through deploying the Build Your Own Copilot 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. -Check the [Azure Products by Region](https://azure.microsoft.com/en-us/explore/global-infrastructure/products-by-region/table) 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](https://learn.microsoft.com/en-us/azure/ai-services/openai/) -- [Azure AI Search](https://learn.microsoft.com/en-us/azure/search/) -- [Azure App Service](https://learn.microsoft.com/en-us/azure/app-service/) -- [Azure SQL Database](https://learn.microsoft.com/en-us/azure/azure-sql/) -- [Azure Semantic Search](AzureSemanticSearchRegion.md) +--- -Here are some example regions where the services are available: East US, East US2, Australia East, UK South, France Central. +## Step 1: Prerequisites & Setup -### [Optional] Quota Recommendations -By default, the **Gpt-4o-mini model capacity** in deployment is set to **30k tokens**, so we recommend updating the following: +### 1.1 Azure Account Requirements -> **For Global Standard | GPT-4o-mini - increase the capacity to at least 150k tokens post-deployment for optimal performance.** +Ensure you have access to an [Azure subscription](https://azure.microsoft.com/free/) with the following permissions: -Depending on your subscription quota and capacity, you can [adjust quota settings](AzureGPTQuotaSettings.md) to better meet your specific needs. You can also [adjust the deployment parameters](CustomizingAzdParameters.md) for additional optimization. -Β­ -## Deployment Options +| **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 | Microsoft Entra ID | Create and configure authentication | -### Sandbox or WAF Aligned Deployment Options +πŸ” **How to Check Your Permissions:** -The [`infra`](../infra) folder of the Build-your-own-copilot-Solution-Accelerator contains the [`main.bicep`](../infra/main.bicep) Bicep script, which defines all Azure infrastructure components for this solution. +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) -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. +**For App Registration permissions:** -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: +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 - - 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 +πŸ“– **Detailed Setup:** Follow [Azure Account Set Up](AzureAccountSetUp.md) for complete configuration. -**How to choose your deployment configuration:** +### 1.2 Check Service Availability & Quota -* 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` +⚠️ **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 Search](https://learn.microsoft.com/en-us/azure/search/) +- [Azure App Service](https://learn.microsoft.com/en-us/azure/app-service/) +- [Azure SQL Database](https://learn.microsoft.com/en-us/azure/azure-sql/) +- [Azure Cosmos DB](https://learn.microsoft.com/en-us/azure/cosmos-db/) +- [Azure Blob Storage](https://learn.microsoft.com/en-us/azure/storage/blobs/) +- [Azure Semantic Search](AzureSemanticSearchRegion.md) -### VM Credentials Configuration +**Recommended Regions:** East US, East US2, Australia East, UK South, France Central -By default, the solution sets the VM administrator username and password from environment variables. +πŸ” **Check Availability:** Use [Azure Products by Region](https://azure.microsoft.com/en-us/explore/global-infrastructure/products-by-region/table) to verify service availability. -To set your own VM credentials before deployment, use: +### 1.3 Quota Check (Optional) -```sh -azd env set AZURE_ENV_VM_ADMIN_USERNAME -azd env set AZURE_ENV_VM_ADMIN_PASSWORD -``` +πŸ’‘ **RECOMMENDED:** Check your Azure OpenAI quota availability before deployment for optimal planning. -> [!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. +**Recommended Configuration:** +- **Default:** 30k tokens (minimum) +- **Optimal:** 150k tokens (recommended for best performance) -> [!IMPORTANT] -> The WAF-aligned configuration is under active development. More Azure Well-Architected recommendations will be added in future updates. +> **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. -## Deployment Options & Steps +πŸ“– **Adjust Quota:** Follow [Azure GPT Quota Settings](AzureGPTQuotaSettings.md) if needed. -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. +--- -| [![Open in Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?repo=microsoft/Build-your-own-copilot-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/Build-your-own-copilot-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=eyJiYXNlVXJsIjogImh0dHBzOi8vcmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbS9taWNyb3NvZnQvQnVpbGQteW91ci1vd24tY29waWxvdC1Tb2x1dGlvbi1BY2NlbGVyYXRvci9yZWZzL2hlYWRzL21haW4vaW5mcmEvdnNjb2RlX3dlYiIsICJpbmRleFVybCI6ICIvaW5kZXguanNvbiIsICJ2YXJpYWJsZXMiOiB7ImFnZW50SWQiOiAiIiwgImNvbm5lY3Rpb25TdHJpbmciOiAiIiwgInRocmVhZElkIjogIiIsICJ1c2VyTWVzc2FnZSI6ICIiLCAicGxheWdyb3VuZE5hbWUiOiAiIiwgImxvY2F0aW9uIjogIiIsICJzdWJzY3JpcHRpb25JZCI6ICIiLCAicmVzb3VyY2VJZCI6ICIiLCAicHJvamVjdFJlc291cmNlSWQiOiAiIiwgImVuZHBvaW50IjogIiJ9LCAiY29kZVJvdXRlIjogWyJhaS1wcm9qZWN0cy1zZGsiLCAicHl0aG9uIiwgImRlZmF1bHQtYXp1cmUtYXV0aCIsICJlbmRwb2ludCJdfQ==) | -|---|---|---| +## Step 2: Choose Your Deployment Environment -
- Deploy in GitHub Codespaces +Select one of the following options to deploy the Build Your Own Copilot Solution Accelerator: -### GitHub Codespaces +### Environment Comparison -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: +| **Environment** | **Best For** | **Requirements** | **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 | -1. Open the solution accelerator (this may take several minutes): +πŸ’‘ **Recommendation:** For fastest deployment, start with **GitHub Codespaces** - no local installation required. - [![Open in Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?repo=microsoft/Build-your-own-copilot-Solution-Accelerator) +
+ Option A: GitHub Codespaces (Easiest) -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). +[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?repo=microsoft/Build-your-own-copilot-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)
- Deploy in VS Code Dev Containers + Option B: VS Code Dev Containers -### VS Code Dev Containers +[![DEV CONTAINERS OPEN](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/Build-your-own-copilot-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:** -1. Start Docker Desktop (install it if not already installed). -2. Open the project: +- [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/Build-your-own-copilot-Solution-Accelerator) +**Steps:** -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). +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 + +[![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=eyJiYXNlVXJsIjogImh0dHBzOi8vcmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbS9taWNyb3NvZnQvQnVpbGQteW91ci1vd24tY29waWxvdC1Tb2x1dGlvbi1BY2NlbGVyYXRvci9yZWZzL2hlYWRzL21haW4vaW5mcmEvdnNjb2RlX3dlYiIsICJpbmRleFVybCI6ICIvaW5kZXguanNvbiIsICJ2YXJpYWJsZXMiOiB7ImFnZW50SWQiOiAiIiwgImNvbm5lY3Rpb25TdHJpbmciOiAiIiwgInRocmVhZElkIjogIiIsICJ1c2VyTWVzc2FnZSI6ICIiLCAicGxheWdyb3VuZE5hbWUiOiAiIiwgImxvY2F0aW9uIjogIiIsICJzdWJzY3JpcHRpb25JZCI6ICIiLCAicmVzb3VyY2VJZCI6ICIiLCAicHJvamVjdFJlc291cmNlSWQiOiAiIiwgImVuZHBvaW50IjogIiJ9LCAiY29kZVJvdXRlIjogWyJhaS1wcm9qZWN0cy1zZGsiLCAicHl0aG9uIiwgImRlZmF1bHQtYXp1cmUtYXV0aCIsICJlbmRwb2ludCJdfQ==) -### Visual Studio Code (WEB) +1. Click the badge above to open in VS Code Web +2. Sign in with your Microsoft account linked to your Azure subscription +3. Select the appropriate subscription to continue +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: + ![alt text](images/vscodeweb_initialize.png) +6. Proceed to [Step 3: Configure Deployment Settings](#step-3-configure-deployment-settings) -You can run this solution in VS Code Web. The button will open a web-based VS Code instance in your browser: -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=eyJiYXNlVXJsIjogImh0dHBzOi8vcmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbS9taWNyb3NvZnQvQnVpbGQteW91ci1vd24tY29waWxvdC1Tb2x1dGlvbi1BY2NlbGVyYXRvci9yZWZzL2hlYWRzL21haW4vaW5mcmEvdnNjb2RlX3dlYiIsICJpbmRleFVybCI6ICIvaW5kZXguanNvbiIsICJ2YXJpYWJsZXMiOiB7ImFnZW50SWQiOiAiIiwgImNvbm5lY3Rpb25TdHJpbmciOiAiIiwgInRocmVhZElkIjogIiIsICJ1c2VyTWVzc2FnZSI6ICIiLCAicGxheWdyb3VuZE5hbWUiOiAiIiwgImxvY2F0aW9uIjogIiIsICJzdWJzY3JpcHRpb25JZCI6ICIiLCAicmVzb3VyY2VJZCI6ICIiLCAicHJvamVjdFJlc291cmNlSWQiOiAiIiwgImVuZHBvaW50IjogIiJ9LCAiY29kZVJvdXRlIjogWyJhaS1wcm9qZWN0cy1zZGsiLCAicHl0aG9uIiwgImRlZmF1bHQtYXp1cmUtYXV0aCIsICJlbmRwb2ludCJdfQ==) +
+ Option D: Local Environment -2. When prompted, sign in using your Microsoft account linked to your Azure subscription. - - Select the appropriate subscription to continue. +**Prerequisites:** -3. Once the solution opens, the **AI Foundry terminal** will automatically start running the following command to install the required dependencies: +Ensure the following tools are installed: - ```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). +- [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+) +- [Python 3.9 to 3.11](https://www.python.org/downloads/) +- [Docker Desktop](https://www.docker.com/products/docker-desktop/) +- [Git](https://git-scm.com/downloads) +- [Microsoft ODBC Driver 18 for SQL Server](https://learn.microsoft.com/en-us/sql/connect/odbc/download-odbc-driver-for-sql-server?view=sql-server-ver16) +**Steps:** + +1. Clone the repository: + ```shell + azd init -t microsoft/build-your-own-copilot-solution-accelerator/ + ``` +2. Open the project folder in your terminal or editor +3. Proceed to [Step 3: Configure Deployment Settings](#step-3-configure-deployment-settings)
-
- Deploy in your local Environment +--- -### Local Environment +## Step 3: Configure Deployment Settings -If you're not using one of the above options for opening the project, then you'll need to: +πŸ’‘ **Before You Start:** 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. -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 to 3.11](https://www.python.org/downloads/) - - [Docker Desktop](https://www.docker.com/products/docker-desktop/) - - [Git](https://git-scm.com/downloads) - - [Microsoft ODBC Driver 18 for SQL Server](https://learn.microsoft.com/en-us/sql/connect/odbc/download-odbc-driver-for-sql-server?view=sql-server-ver16) +### 3.1 Choose Deployment Type (Optional) -2. Clone the repository or download the project code via command-line: +| **Configuration** | **Development/Testing (Default)** | **Production (WAF-Aligned)** | +|-------------------|-----------------------------------|------------------------------| +| 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 | +| Features | Core functionality | Reliability, security, operational excellence | - ```shell - azd init -t microsoft/build-your-own-copilot-solution-accelerator/ - ``` +**To use production configuration:** -3. Open the project folder in your terminal or editor. -4. Continue with the [deploying steps](#deploying-with-azd). +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) + +> **Note:** The WAF-aligned configuration is under active development. More Azure Well-Architected recommendations will be added in future updates. + +### 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: -Consider the following settings during your deployment to modify specific settings: +```shell +azd env set AZURE_ENV_VM_ADMIN_USERNAME +azd env set AZURE_ENV_VM_ADMIN_PASSWORD +``` + +### 3.3 Advanced Configuration (Optional)
- Configurable Deployment Settings + Configurable Parameters -When you start the deployment, most parameters will have **default values**, but you can update the below settings by following the steps [here](CustomizingAzdParameters.md) +When you start the deployment, most parameters will have **default values**, but you can update these settings by following the steps [here](CustomizingAzdParameters.md).
- [Optional] Quota Recommendations + Reuse Existing Resources + +**Reusing an Existing Log Analytics Workspace:** + +Guide to get your [Existing Workspace ID](re-use-log-analytics.md) + +**Reusing an Existing Azure AI Foundry Project:** + +Guide to get your [Existing Project ID](re-use-foundry-project.md) + +
+ +--- + +## 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 and copy the value displayed + +### 4.2 Start Deployment + +```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). + +**During deployment, you'll be prompted for:** + +1. **Environment name** (e.g., "byocaapp") - Must be 3-16 characters long, alphanumeric only +2. **Azure subscription** selection +3. **Azure location** - Select a region where all required services are available with sufficient quota + +**Expected Duration:** 7-10 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 **App Service** and get the app URL from **Default domain** + +⚠️ **Important:** Complete Post-Deployment Steps before accessing the application. + +--- + +## Step 5: Post-Deployment Configuration + +### 5.1 Import Sample Data (Required) + +**Choose the appropriate command based on your deployment method:** + +**If you deployed using `azd up` command:** + +```bash +bash ./infra/scripts/process_sample_data.sh +``` + +> **Note:** The script will automatically take required values from your `azd` environment. + +**If you deployed using custom templates, ARM/Bicep deployments, or `az deployment group` commands:** + +```bash +bash ./infra/scripts/process_sample_data.sh +``` + +> **Note:** Replace `` with the actual name of the resource group containing your deployed Azure resources. -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.** +πŸ’‘ **Tip:** If the deployment metadata does not exist in Azure or has been deleted, the script will prompt you to manually enter the required configuration values. -To adjust quota settings, follow these [steps](./AzureGPTQuotaSettings.md). +### 5.2 Configure Authentication (Required) -**⚠️ Warning:** Insufficient quota can cause deployment errors. Please ensure you have the recommended capacity or request additional capacity before deploying this solution. +This step is mandatory for application access: + +1. Follow [App Authentication Configuration](AppAuthentication.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 + +### 5.4 Test the Application + +Test the app with sample questions to verify functionality: + +- **Sample Question:** _"Show latest asset value by asset type?"_ + +πŸ“– **More Examples:** For additional sample questions you can test in the application, see [Sample Questions](SampleQuestions.md). + +--- + +## 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 in the Azure Portal before running `azd down`, else resource group delete will fail. Navigate to your Log Analytics workspace, disable replication, wait until replication status 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 + +1. Clean up the failed deployment: + ```shell + azd down + ``` + +2. Start a new deployment: + ```shell + 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 - Reusing an Existing Log Analytics Workspace +1. Create a new environment: + ```shell + azd env new + ``` - Guide to get your [Existing Workspace ID](/docs/re-use-log-analytics.md) +2. Deploy to the new environment: + ```shell + azd up + ```
+ +### Switch Between Environments +
+ Switch Between Environments - Reusing an Existing Azure AI Foundry Project +To switch between existing environments: - Guide to get your [Existing Project ID](/docs/re-use-foundry-project.md) +```shell +azd env select +```
-### Deploying with AZD +### Best Practices for Multiple Environments -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: +- **Use descriptive names:** `byocdev`, `byocprod`, `byoctest` (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 -1. Login to Azure: +--- - ```shell - azd auth login - ``` +## Next Steps - #### To authenticate with Azure Developer CLI (`azd`), use the following command with your **Tenant ID**: +Now that your deployment is complete and tested, explore these resources to enhance your experience: - ```sh - azd auth login --tenant-id - ``` +πŸ“š **Learn More:** - > **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 **Azure Active Directory** from the left-hand menu. - > 3. Under the **Overview** section, locate the **Tenant ID** field. Copy the value displayed. +- [Sample Questions](SampleQuestions.md) - Try example queries with the application +- [Troubleshooting Guide](TroubleShootingSteps.md) - Solutions to common issues +- [Customize AZD Parameters](CustomizingAzdParameters.md) - Tailor deployment parameters +- [Azure GPT Quota Settings](AzureGPTQuotaSettings.md) - Adjust model quotas +- [Local Development Setup](LocalSetupAndDeploy.md) - Set up your local development environment -2. Provision and deploy all the resources: - ```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). +## Need Help? -3. Provide an `azd` environment name (e.g., "byocaapp"). -4. Select a subscription from your Azure account and choose a location that has quota for all the resources. - - This deployment will take *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. +- πŸ› **Issues:** Check [Troubleshooting Guide](TroubleShootingSteps.md) +- πŸ’¬ **Support:** Review [Support Guidelines](../SUPPORT.md) +- πŸ”§ **Development:** See [Contributing Guide](../CONTRIBUTING.md) +- πŸ”’ **Security:** Read [Security Policy](../SECURITY.md) +- πŸ“‹ **Transparency:** View [Transparency FAQ](../TRANSPARENCY_FAQ.md) -5. Once the deployment is complete, please follow the [Import Sample Data](#post-deployment-steps) instructions under **Post Deployment Steps** to load the sample data correctly. -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`. -7. Test the app locally with the sample question with any selected client: _Show latest asset value by asset type?_. For more sample questions you can test in the application, see [Sample Questions](SampleQuestions.md). -8. You can now delete the resources by running `azd down`, if you are done trying out the application. +--- -### Publishing Local Build Container to Azure Container Registry +## 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](LocalSetupAndDeploy.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. + +--- + +## Publishing Local Build Container to Azure Container Registry If you need to rebuild the source code and push the updated container to the deployed Azure Container Registry, follow these steps: 1. Set the environment variable `USE_LOCAL_BUILD` to `True`: - - **Linux/macOS**: + - **Linux/macOS:** ```bash export USE_LOCAL_BUILD=True ``` - - **Windows (PowerShell)**: + - **Windows (PowerShell):** ```powershell $env:USE_LOCAL_BUILD = $true ``` -2. Run the `az login` command + +2. Run the `az login` command: ```bash az login ``` @@ -265,54 +489,15 @@ If you need to rebuild the source code and push the updated container to the dep This will rebuild the source code, package it into a container, and push it to the Azure Container Registry associated with your deployment. -### πŸ› οΈ Troubleshooting - If you encounter any issues during the deployment process, please refer [troubleshooting](../docs/TroubleShootingSteps.md) document for detailed steps and solutions - -## Deploy Your local changes -To deploy your local changes rename the below files. - 1. Rename `azure.yaml` to `azure_custom2.yaml` and `azure_custom.yaml` to `azure.yaml`. - 2. Go to `infra` directory - - Rename `main.bicep` to `main_custom2.bicep` and `main_custom.bicep` to `main.bicep`. -Continue with the [deploying steps](#deploying-with-azd). - -## Post Deployment Steps - -### 1. Import Sample Data - -**Choose the appropriate command based on your deployment method:** - -**If you deployed using `azd up` command:** -```bash -bash ./infra/scripts/process_sample_data.sh -``` -> **Note**: The script will automatically take required values from your `azd` environment. - -**If you deployed using custom templates, ARM/Bicep deployments, or `az deployment group` commands:** -```bash -bash ./infra/scripts/process_sample_data.sh -``` -> **Note**: Replace `` with the actual name of the resource group containing your deployed Azure resources. - -> **πŸ’‘ Tip**: If the deployment metadata does not exist in Azure or has been deleted, the script will prompt you to manually enter the required configuration values. - -> **πŸ’‘ Tip**: Since this guide is for azd deployment, you'll most likely use the first command without resource group name. - -### 2. Configure Authentication - -Follow the steps in [App Authentication](./AppAuthentication.md) to configure authentication in App Service. - -> **Note**: Authentication changes can take up to 10 minutes to propagate. - -### 3. Troubleshooting: Cleaning Up After a Failed Deployment +--- -If your deployment fails and you need to clean up resources, follow the steps in [Delete Resource Group](./DeleteResourceGroup.md). +## Environment Configuration for Local Development & Debugging -## 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**. +> 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\App` folder. - 2. Create a `.env` file based on the `.env.sample` file. - 3. Fill in the `.env` file using the deployment output or by retrieving values from the Azure Portal under "Deployments" in your resource group. - 4. Ensure that the `APP_ENV` variable is set to "**dev**". +1. Navigate to the `src\App` folder +2. Create a `.env` file based on the `.env.sample` file +3. Fill in the `.env` file using the deployment output or by retrieving values from the Azure Portal under "Deployments" in your resource group +4. Ensure that the `APP_ENV` variable is set to "**dev**" diff --git a/docs/images/vscodeweb_initialize.png b/docs/images/vscodeweb_initialize.png new file mode 100644 index 00000000..e6d0f526 Binary files /dev/null and b/docs/images/vscodeweb_initialize.png differ