Skip to content

DeploymentGuide.md

Latest commit

 

History

History
259 lines (165 loc) · 14.2 KB

DeploymentGuide.md

File metadata and controls

259 lines (165 loc) · 14.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, app registrations, and assign roles at the resource group level. This should include Contributor role at the subscription level and Role Based Access Control role on the subscription and/or resource group level. Follow the steps in Azure Account Set Up.

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.

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:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

This will allow the scripts to run for the current session without permanently changing your system's policy.

Deployment Options & Steps

Sandbox or WAF Aligned Deployment Options

The infra folder of the Multi Agent 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, and Local Environments.

Open in GitHub Codespaces Open in Dev Containers
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 GitHub 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

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 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/document-generation-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 following settings:here:

Setting Description Default Value
Azure Region The region where resources will be created. eastus
Environment Name A 3–20 character alphanumeric value used to generate a unique ID to prefix the resources. byctemplate
Secondary Location A less busy region for CosmosDB, useful in case of availability constraints. eastus2
Deployment Type Model deployment type (allowed: Standard, GlobalStandard). GlobalStandard
GPT Model The GPT model used by the app gpt-4.1
GPT Model Version The GPT Version used by the app 2024-05-13
OpenAI API Version Azure OpenAI API version used for deployments. 2024-05-01-preview
GPT Model Deployment Capacity Configure the capacity for GPT model deployments (in thousands). 30k
Embedding Model The embedding model used by the app. text-embedding-ada-002
Embedding Model Capacity Configure the capacity for embedding model deployments (in thousands). 80k
Image Tag Image version for deployment (allowed: latest_waf, dev, hotfix). latest_waf
Existing Log Analytics Workspace If reusing a Log Analytics Workspace, specify the ID. (none)
[Optional] Quota Recommendations

By default, the Gpt-4.1 model capacity in deployment is set to 30k tokens, so we recommend:

  • For Global Standard | GPT-4.1 - the capacity to at least 150k tokens post-deployment for optimal performance.

  • For Standard | GPT-4 - ensure a minimum of 30k–40k tokens for best results.

To adjust quota settings, follow these steps.

⚠️ Important: Check Azure OpenAI Quota Availability

➡️ To ensure sufficient quota is available in your subscription, please follow Quota check instructions guide before you deploy the solution. Insufficient quota can cause deployment errors. Please ensure you have the recommended capacity or request additional capacity before deploying this solution.

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

  2. Provision and deploy all the resources:

    azd up

  3. Provide an azd environment name (e.g., "dgapp").

  4. Select a subscription from your Azure account and choose a location that has quota for all the resources.

    • This deployment 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 has completed successfully and you would like to use the sample data, run the bash command printed in the terminal. The bash command will look like the following:

    bash ./infra/scripts/process_sample_data.sh

    If you don't have azd env then you need to pass parameters along with the command. Then the command will look like the following:

    bash ./infra/scripts/process_sample_data.sh <Storage-Account-Name> <Storage-Container-Name> <Key-Vault-Name> <CosmosDB-Account-Name> <Resource-Group-Name> <Search-Service-Name> <Managed-Identity-Client-ID> <AI-Foundry-Resource-ID>

  6. Open the Azure Portal, go to the deployed resource group, find the App Service and get the app URL from Default domain.

  7. You can now delete the resources by running azd down, if you are done trying out the application.

🛠️ Troubleshooting

If you encounter any issues during the deployment process, please refer troubleshooting document for detailed steps and solutions

Post Deployment Steps

  1. Add App Authentication

    Note: Authentication changes can take up to 10 minutes

    Follow steps in App Authentication to configure authentication in app service.

  2. Deleting Resources After a Failed Deployment

    • Follow steps in Delete Resource Group if your deployment fails and/or you need to clean up the resources.

Environment configuration for local development & debugging

Set APP_ENV in your .env file to control Azure authentication. Set the environment variable to dev to use Azure CLI credentials, or to prod to use Managed Identity for production. Ensure you're logged in via az login when using dev in local. To configure your environment, follow these steps:

  1. Navigate to the src folder.
  2. Create a .env file based on the .env.sample file.
  3. Fill in the .env file using the deployment output or by checking the Azure Portal under "Deployments" in your resource group.
  4. Alternatively, if resources were provisioned using azd provision or azd up, a .env file is automatically generated in the .azure/<env-name>/.env file. To get your <env-name> run azd env list to see which env is default.
  5. Ensure that APP_ENV is set to "dev" in your .env file.

Next Steps

Now that you've completed your deployment, you can start using the solution.

To help you get started, here are some Sample Questions you can follow to try it out.