Skip to content

DeploymentGuide.md

Latest commit

 

History

History
319 lines (207 loc) · 17.2 KB

DeploymentGuide.md

File metadata and controls

319 lines (207 loc) · 17.2 KB

Deployment Guide

Pre-requisites

To deploy this solution accelerator, ensure you have access to an Azure subscription 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

Check the Azure Products by Region page and select a region where the following services are available:

Here are some example regions where the services are available: East US, East US2, Australia East, UK South, France Central.

[Optional] Quota Recommendations

By default, the Gpt-4o-mini model capacity in deployment is set to 30k tokens, so we recommend updating the following:

For Global Standard | GPT-4o-mini - increase the capacity to at least 150k tokens post-deployment for optimal performance.

Depending on your subscription quota and capacity, you can adjust quota settings to better meet your specific needs. You can also adjust the deployment parameters for additional optimization. ­

Deployment Options

Sandbox or WAF Aligned Deployment Options

The infra folder of the Build-your-own-copilot-Solution-Accelerator contains the main.bicep Bicep script, which defines all Azure infrastructure components for this solution.

By default, the azd up command uses the 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 production deployments, the repository also provides main.waf.parameters.json, which applies a Well-Architected Framework (WAF) aligned configuration. This option enables additional Azure best practices for reliability, security, cost optimization, operational excellence, and performance efficiency, such as:

  • 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

How to choose your deployment configuration:

  • 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

VM Credentials Configuration

By default, the solution sets the VM administrator username and password from environment variables.

To set your own VM credentials before deployment, use:

azd env set AZURE_ENV_VM_ADMIN_USERNAME <your-username>
azd env set AZURE_ENV_VM_ADMIN_PASSWORD <your-password>

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.

Important

The WAF-aligned configuration is under active development. More Azure Well-Architected recommendations will be added in future updates.

Deployment Options & Steps

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 Open in Dev Containers Open in Visual Studio Code Web
Deploy in GitHub Codespaces

GitHub Codespaces

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):

    Open in Codespaces

  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.

Deploy in VS Code Dev Containers

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:

  1. Start Docker Desktop (install it if not already installed).

  2. Open the project:

    Open in Dev Containers

  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.

Deploy in Visual Studio Code (WEB)

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:

  1. Open the solution accelerator (this may take several minutes):

    Open in Visual Studio Code Web

  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:

    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.

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:

  2. Clone the repository or download the project code via command-line:

    azd init -t microsoft/build-your-own-copilot-solution-accelerator/

  3. Open the project folder in your terminal or editor.

  4. Continue with the deploying steps.


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 below settings by following the steps here

[Optional] Quota Recommendations

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.

To adjust quota settings, follow these steps.

⚠️ Warning: Insufficient quota can cause deployment errors. Please ensure you have the recommended capacity or request additional capacity before deploying this solution.

Reusing an Existing Log Analytics Workspace

Guide to get your Existing Workspace ID

Reusing an Existing Azure AI Foundry Project

Guide to get your Existing Project ID

Deploying with AZD

Once you've opened the project in Codespaces, Dev Containers, Visual Studio Code (WEB), or locally, you can deploy it to Azure by following these steps:

  1. Login to Azure:

    azd auth login

    To authenticate with Azure Developer CLI (azd), use the following command with your Tenant ID:

    azd auth login --tenant-id <tenant-id>

    Note: To retrieve the Tenant ID required for local deployment, you can go to Tenant Properties in Azure Portal from the resource list. Alternatively, follow these steps:

    1. Open the Azure Portal.
    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.

  2. Provision and deploy all the resources:

    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.

  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.

  5. Once the deployment is complete, please follow the Import Sample Data instructions under Post Deployment Steps to load the sample data correctly.

  6. Open the Azure Portal, 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.

  8. 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, wait until replication returns false, then run azd down.

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:

      export USE_LOCAL_BUILD=True

    • Windows (PowerShell):

      $env:USE_LOCAL_BUILD = $true

  2. Run the az login command

    az login

  3. Run the azd up command again to rebuild and push the updated container:

    azd up

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 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.

Post Deployment Steps

1. Import Sample Data

Choose the appropriate command based on your deployment method:

If you deployed using azd up command:

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 ./infra/scripts/process_sample_data.sh <your-resource-group-name>

Note: Replace <your-resource-group-name> 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 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.

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\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**".