Skip to content

DeploymentGuide.md

Latest commit

 

History

History
550 lines (371 loc) · 24.8 KB

DeploymentGuide.md

File metadata and controls

550 lines (371 loc) · 24.8 KB
Raw
title Deployment Guide
description Step-by-step guide to deploy the Chat with Your Data solution accelerator to Azure using the Azure Developer CLI.
ms.date 2026-07-23
ms.topic how-to

Back to Chat with your data README

Deployment Guide

Overview

This guide walks you through deploying Chat with Your Data to Azure. The deployment takes approximately 25-30 minutes for the default configuration and includes infrastructure provisioning, container image builds, and application setup.

Tip

If you encounter any issues during deployment, check the Troubleshooting Guide for solutions to common problems.

Note

Some tenants may have additional security restrictions that run periodically and could impact the application (for example, blocking public network access). If you experience issues or the application stops working, check if these restrictions are the cause. Consider deploying the WAF-supported version to ensure compliance. To configure, see Section 3.1.

Step 1: Prerequisites & Setup

1.1 Azure account requirements

Ensure you have access to an Azure subscription with the following permissions:

Required permission/role Scope Purpose
Contributor Subscription level Create and manage Azure resources
User Access Administrator Subscription level Manage user access and role assignments
Role Based Access Control Admin Subscription/Resource Group level Configure RBAC permissions

For detailed setup instructions, follow Azure Account Set Up.

1.2 Check service availability & quota

Before proceeding, ensure your chosen region has all required services available:

Required Azure services:

Recommended regions: East US, East US 2, Australia East, UK South, France Central

Check the Azure Products by Region page to verify service availability in your target region.

1.3 Quota check (recommended)

Check your Azure OpenAI quota availability before deployment. Follow the Quota Check Instructions to ensure sufficient model capacity, then review Azure OpenAI Model Quota Settings to adjust if needed.

Step 2: Choose Your Deployment Environment

Select one of the following options to set up your deployment environment:

Environment comparison

Option Best for Prerequisites Setup time
GitHub Codespaces Quick deployment, no local setup required GitHub account 3-5 minutes
VS Code Dev Containers Fast deployment with local tools Docker Desktop, VS Code 5-10 minutes
Visual Studio 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

Tip

For the fastest deployment, start with GitHub Codespaces — no local installation required.

Option A: GitHub Codespaces (Easiest)

Open in GitHub Codespaces

  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
Option B: VS Code Dev Containers

Open in Dev Containers

[!NOTE] macOS developers on Apple Silicon (ARM64): the Dev Container will not work due to a limitation with the Azure Functions Core Tools (see issue). Use Option D (Local Environment) instead.

Prerequisites:

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

[!TIP] VS Code should recognize the available dev container and prompt you to reopen the folder in it. For more details, see Open an existing folder in a container.

Option C: Visual Studio Code (Web)

Open in Visual Studio Code (Web)

  1. Click the badge above (may take a few minutes to load)

  2. Sign in with your Azure account when prompted

  3. Wait for the environment to initialize

  4. Authenticate with Azure using device code authentication:

    az login --use-device-code

    [!NOTE] In VS Code Web, the regular az login command may fail. Use the --use-device-code flag to authenticate via browser device code flow.

  5. Proceed to Step 3: Configure Deployment Settings

Option D: Local Environment

Required tools:

Setup steps:

  1. Install all required tools listed above

  2. Clone the repository:

    azd init -t chat-with-your-data-solution-accelerator

  3. Open the project folder in your terminal

  4. Run the environment setup script:

    .devcontainer/setupEnv.sh

  5. Select the Python interpreter in VS Code:

    • Open the command palette (Ctrl+Shift+P)
    • Type Python: Select Interpreter
    • Select the Python 3.11 environment created by uv

  6. Proceed to Step 3: Configure Deployment Settings

PowerShell users: If you encounter script execution issues, run:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

Step 3: Configure Deployment Settings

Review the configuration options below. You can customize any settings that meet your needs, or leave them as defaults to proceed with a standard deployment.

3.1 Choose Deployment Type (Optional)

Aspect Development/Testing (Default) Production
Configuration file main.parameters.json (sandbox) Copy main.waf.parameters.json to main.parameters.json
Security controls Minimal (for rapid iteration) Enhanced (production best practices)
Cost Lower costs Cost optimized
Use case POCs, development, testing Production workloads
Framework Basic configuration Well-Architected Framework
Features Core functionality Reliability, security, operational excellence

To use production configuration:

  1. Navigate to the infra folder in your project
  2. Open main.waf.parameters.json in a text editor
  3. Select all content and copy it
  4. Open main.parameters.json in the same editor
  5. Replace all existing content with the copied content
  6. Save the file

3.2 Set VM credentials (Optional — production 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:

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

3.3 Advanced configuration (Optional)

Configurable parameters

You can customize various deployment settings before running azd up, including Azure regions, AI model configurations (deployment type, version, capacity), container registry settings, and resource names.

See Parameter Customization Guide for the full list of available parameters and their usage.

These key parameters are environment-variable driven (not interactive prompts). Set any of them before running azd up with azd env set <ENV_VAR> <value>:

Parameter (env var) Values Notes
databaseType (DATABASE_TYPE) postgresql (default), cosmosdb Selects both the chat-history backend and the vector index store. cosmosdb deploys Cosmos DB + Azure AI Search; postgresql deploys PostgreSQL Flexible Server with pgvector (Azure AI Search is not deployed). Locked after deployment.
ingestionTrigger (INGESTION_TRIGGER) direct_enqueue (default) Document-ingestion trigger mode for the Functions app.
azureAiServiceLocation (AZURE_AI_SERVICE_LOCATION) Azure region Region for Azure AI Foundry models. Prompted during azd up if unset.
enableMonitoring (ENABLE_MONITORING) true, false Adds Log Analytics and Application Insights. Defaults to false.
enableScalability (ENABLE_SCALABILITY) true, false Higher SKUs and autoscaling. Defaults to false (dev) / true (production WAF).
enableRedundancy (ENABLE_REDUNDANCY) true, false Zone/region redundancy. Defaults to false.
enablePrivateNetworking (ENABLE_PRIVATE_NETWORKING) true, false Adds a virtual network, private DNS, and a bastion host. Defaults to false (dev) / true (production WAF).

[!NOTE] The enable* flags are wired through the production main.waf.parameters.json. When using the default main.parameters.json (development/testing), toggling them requires editing that file or switching to the WAF parameters file per Section 3.1.

Reuse existing resources

To optimize costs and integrate with your existing Azure infrastructure, you can configure the solution to reuse compatible resources already deployed in your subscription.

Supported resources for reuse:

  • Log Analytics Workspace: integrate with your existing monitoring infrastructure by reusing an established Log Analytics workspace for centralized logging and monitoring.
  • Resource Group: leverage an existing resource group to organize resources within your current Azure infrastructure. Follow the setup steps here before running azd up.

Key benefits:

  • Eliminate duplicate resource charges by reusing existing services.
  • Maintain unified monitoring across your Azure infrastructure.
  • Skip resource creation for existing compatible services to speed up provisioning.
  • Reduce the number of resources to manage and monitor.

Important considerations:

  • Ensure existing resources meet the solution's requirements and are in compatible regions.
  • Review access permissions and configurations before reusing resources.
  • Consider the impact on existing workloads when sharing resources.

Step 4: Deploy the Solution

Tip

If you encounter any issues during deployment, check the Troubleshooting Guide for common solutions.

4.1 Authenticate with Azure

azd auth login

For specific tenants:

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

Tip

To find your Tenant ID: open the Azure Portal, navigate to Microsoft Entra ID, and copy the Tenant ID from the Overview page.

4.2 Start deployment

Note

If you are running azd version 1.23.9, run the following command first:

azd config set provision.preflight off
azd up

During deployment, you will be prompted for:

  1. Environment name (e.g., cwyd) — must be 3-16 characters, alphanumeric only
  2. Azure subscription selection
  3. Location — the region where your infrastructure resources will be deployed
  4. Resource group selection (create new or use existing)

Expected duration: 25-30 minutes for the default configuration

Note

If you encounter errors or timeouts, try a different region as there may be capacity constraints. For detailed error solutions, see the Troubleshooting Guide.

What azd up does:

flowchart TD
  A[azd auth login] --> B[azd up]
  B --> C[Provision infra via Bicep]
  C --> D[Print post-deployment steps]
  D --> E[Application URL printed]
Loading

azd up provisions the Azure infrastructure only. It does not build the application images or ingest data — those are manual steps you complete in Step 5.

  1. Provisions the resource group contents described in Architecture overview using Bicep — Container Apps, container registry, Azure OpenAI, the search or database resources, and supporting services.
  2. Creates the three Container Apps (frontend, backend, ingestion) running a temporary placeholder image.
  3. Prints the post-deployment commands you run next to build the application images and configure the data plane.

4.3 Get application URL

After successful deployment, azd prints the application URL in the terminal. You can also locate it manually:

  1. Open the Azure Portal
  2. Navigate to your resource group
  3. Find the Container Apps — you will see the frontend, backend, and ingestion (function) services
  4. Click the frontend Container App and copy its Application URL from the overview page

Important

Complete Post-Deployment Steps before accessing the application.

4.4 Redeploy the application images

azd up provisions infrastructure only, so there is no azd deploy step for this accelerator. To rebuild the application images and roll out new revisions to all three Container Apps after code changes, re-run the container workflow described in Step 5.1.

Step 5: Post-Deployment Configuration

5.1 Build, push, and update container images (Required)

azd up provisions the Container Apps with a temporary placeholder image. Run the combined container workflow to build the application images, push them to your Azure Container Registry, and roll out new revisions to all three Container Apps (frontend, backend, ingestion).

Login to Azure CLI:

az login

For specific tenants:

az login --tenant-id <tenant-id>

PowerShell (Windows):

.\infra\scripts\post-provision\acr_build_push_update.ps1 -ResourceGroupName "<your-resource-group-name>"

Bash (Linux/macOS/WSL):

bash infra/scripts/post-provision/acr_build_push_update.sh -g "<your-resource-group-name>"

This script builds and pushes the images to your ACR using ACR Tasks (remote build — no local Docker required), updates each Container App to pull its image from your private ACR using managed-identity authentication, and restarts all services. It works for both standard and private-networking (WAF) deployments by temporarily unlocking the registry for the build and re-locking it afterwards.

Tip

Pass a custom image tag with -Tag <tag> in PowerShell or -t <tag> in Bash (default: latest).

Note

If you re-run azd provision, run this script again to restore the correct container images.

5.2 Run post-deployment setup script (Required)

Run the post-deployment script to complete data-plane setup. It auto-discovers the resources in your resource group and, based on databaseType:

  • postgresql mode: enables the vector (pgvector) extension on the PostgreSQL Flexible Server. Tables are created automatically by the application at runtime.
  • cosmosdb mode: creates the Azure AI Search index (cwyd-index) and seeds the Foundry IQ knowledge base used for retrieval.

For private-networking (WAF) deployments it temporarily enables public access, performs the setup, then restores the original network state.

Important

The post-deployment script requires Azure CLI version 2.87.0 or later. Check your installed version with az version. If it is earlier than 2.87.0, upgrade first with az upgrade.

PowerShell (Windows):

.\infra\scripts\post-provision\post_deployment_setup.ps1 -ResourceGroupName "<your-resource-group-name>"

Bash (Linux/macOS/WSL):

bash infra/scripts/post-provision/post_deployment_setup.sh "<your-resource-group-name>"

Note

The script auto-discovers all resources in the resource group. It handles private networking (WAF) deployments by temporarily enabling public access, performing the setup, then restoring the original state.

5.3 Configure authentication (Recommended)

The deployed app works without an identity provider, but it then treats every visitor as a single shared default user with no sign-in and no per-user history isolation. Configure authentication to require Microsoft Entra ID sign-in, give each user their own chat history, and control who can reach the admin area.

  1. Follow Set up authentication.
  2. Allow a few minutes for the authentication changes to take effect.

5.4 Verify deployment

  1. Access your application using the URL from Step 4.3
  2. Confirm the application loads successfully
  3. If you configured authentication in Step 5.3, verify you can sign in with your authenticated account

5.5 Test the application

  1. Navigate to the admin experience at /admin on your application URL, upload documents via Ingest Data, and add your data. Sample data is available in the data/ directory.
  2. Navigate to the chat application and start chatting on top of your data.

Step 6: Clean Up (Optional)

Remove all resources

azd down

Warning

azd down permanently deletes all deployed resources and ingested data. Export anything you need before running this command.

Note

If you deployed with enableRedundancy=true and Log Analytics workspace replication is enabled, you must first disable replication before running azd down, otherwise the 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.

Manual cleanup (if needed)

If deployment fails or you need to clean up manually, follow the Delete Resource Group Guide.

Managing Multiple Environments

Recover from failed deployment

Recover from failed deployment

If your deployment failed or encountered errors:

  1. Try a different region by creating a new environment and selecting a different Azure region during deployment.
  2. Clean up and retry: use azd down to remove failed resources, then azd up to redeploy.
  3. Create a completely new environment with a different name for a fresh start.

Example recovery workflow:

# Remove failed deployment (optional)
azd down

# Create new environment (3-16 chars, alphanumeric only)
azd env new cwydretry

# Deploy with different settings/region
azd up

Create a new environment

Create a new environment

If you need to deploy to a different region, test different configurations, or create additional environments:

# Create a new named environment (3-16 characters, alphanumeric only)
azd env new <new-environment-name>

# Select the new environment
azd env select <new-environment-name>

# Deploy to the new environment
azd up

Environment name requirements:

  • Length: 3-16 characters
  • Characters: alphanumeric only (letters and numbers)
  • Valid examples: cwyd, test123, myappdev, prod2024
  • Invalid examples: cd (too short), my-very-long-environment-name (too long), test_env (underscore not allowed), myapp-dev (hyphen not allowed)

Switch between environments

Switch between environments 
# List all environments
azd env list

# Switch to a different environment
azd env select <environment-name>

# View current environment variables
azd env get-values

Best practices for multiple environments

  • Use descriptive names such as cwyddev, cwydprod, cwydtest (3-16 chars, alphanumeric only).
  • Deploy to multiple regions for testing quota availability.
  • Each environment can have different parameter settings.
  • Use azd down to remove environments you no longer need and avoid unnecessary costs.

Deploy using Bicep directly

If you prefer not to use azd, you can deploy using the Bicep file directly. A Bicep file is used to generate the ARM template.

az deployment sub create --template-file ./infra/main.bicep --subscription {your_azure_subscription_id} --location {your_preferred_location}

Next steps

Need help?