Azure Developer CLI (azd) Deployment Guide

July 3, 2026 · View on GitHub

This guide covers deploying the Content Generation Solution Accelerator using Azure Developer CLI (azd).

Prerequisites

Required Tools

  1. Azure Developer CLI (azd) v1.18.0 or higher

    # Install on Linux/macOS
curl -fsSL https://aka.ms/install-azd.sh | bash

# Install on Windows (PowerShell)
powershell -ex AllSigned -c "Invoke-RestMethod 'https://aka.ms/install-azd.ps1' | Invoke-Expression"

# Verify installation
azd version

  2. Azure CLI

    # Install: https://docs.microsoft.com/cli/azure/install-azure-cli
az version

  3. Node.js v18 or higher (for frontend build)

    node --version

  4. Python 3.11+ (for post-deployment scripts)

    python3 --version

  5. Bicep CLI v0.33.0 or higher (for compiling infrastructure templates)

    # Install or upgrade via Azure CLI (upgrade ensures an existing older Bicep is bumped to the required version)
az bicep install
az bicep upgrade

# Verify installation
az bicep version

Azure Requirements

  • An Azure subscription with the following permissions:

    • Create Resource Groups
    • Deploy Azure AI Services (GPT-5.1, GPT-Image-1-mini)
    • Create Container Registry, Container Instances, App Service
    • Create Cosmos DB, Storage Account, AI Search
    • Assign RBAC roles

  • Quota: Ensure you have sufficient quota for:

    • GPT-5.1 (or your chosen model)
    • GPT-Image-1-mini (or GPT-Image-1.5 - for image generation)

Quick Start

1. Authenticate

# Login to Azure
azd auth login

# Login to Azure CLI (required for some post-deployment scripts)
az login

Alternatively, login to Azure using a device code (recommended when using VS Code Web):

az login --use-device-code

2. Initialize Environment


# Create a new environment
azd env new <environment-name>

# Example:
azd env new content-gen-dev

3. Choose Deployment Configuration

The infra folder 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.

For production deployments, the repository also provides main.waf.parameters.json, which applies a Well-Architected Framework (WAF) aligned configuration. This can be used for Production scenarios.

How to choose your deployment configuration:

  • To use sandbox/dev environment — Use the default main.parameters.json file.

  • To use production configuration:

Before running azd up, 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).

4. Deploy

NOTE: If you are running the latest azd version (version 1.23.9), please run the following command.

azd config set provision.preflight off

azd up

This command will provision all Azure resources (AI Services, Cosmos DB, Storage, AI Search, App Service, Container Instance, Container Registry) and configure RBAC and Cosmos DB roles. The Container Registry (ACR) is initially deployed with placeholder images; the application images are built and pushed by the follow-up scripts below.

When provisioning completes, the terminal prints the two follow-up scripts you must run, in order, to finish the deployment.

5. Log in to Azure CLI

These scripts use the Azure CLI, so log in first:

az login

Alternatively, log in using a device code (recommended when using VS Code Web):

az login --use-device-code

Note: If you are running this deployment in GitHub Codespaces, a VS Code Dev Container, or VS Code Web, skip this step and continue with step 7.

6. Create and activate a Python virtual environment

# PowerShell (Windows)
python -m venv .venv
.venv\Scripts\Activate.ps1

# Bash (macOS/Linux, or Git Bash on Windows)
python -m venv .venv
source .venv/bin/activate        # on Git Bash (Windows): source .venv/Scripts/activate

7. Run the script to build and push the application images

Build and push the frontend and backend images to ACR, then update the App Service and Container Instance:

# PowerShell
./infra/scripts/build_and_deploy_images.ps1

# Bash
bash ./infra/scripts/build_and_deploy_images.sh

8. Run the script to load the sample data (script 2)

Run this only after step 7 has completed — it loads the sample data into the application:

# PowerShell
./infra/scripts/process_sample_data.ps1

# Bash
bash ./infra/scripts/process_sample_data.sh

Using Existing Resources

Reuse Existing AI Foundry Project

# Set the resource ID of your existing AI Project
azd env set AZURE_EXISTING_AIPROJECT_RESOURCE_ID "/subscriptions/<sub-id>/resourceGroups/<rg>/providers/Microsoft.MachineLearningServices/workspaces/<project-name>"

Reuse Existing Log Analytics Workspace

# Set the resource ID of your existing Log Analytics workspace
azd env set AZURE_ENV_EXISTING_LOG_ANALYTICS_WORKSPACE_RID "/subscriptions/<sub-id>/resourceGroups/<rg>/providers/Microsoft.OperationalInsights/workspaces/<workspace-name>"

Post-Deployment

After azd up completes, the terminal prints the provisioning summary and the two follow-up scripts to run:

===== Provisioning Complete =====
Run the following two scripts, in order:
  1. Build and push the application images to ACR, then update the web app and container instance:
     ./infra/scripts/build_and_deploy_images.ps1
  2. Load the sample data into the application (run only after the previous script run has completed):
     ./infra/scripts/process_sample_data.ps1

Web app URL: https://app-<env-name>.azurewebsites.net

Run those two scripts as described in steps 5–8 above, then verify the deployment.

Verify Deployment

  1. Open the Web App URL in your browser
  2. Sign in with your Azure AD account
  3. Navigate to the Products page to verify sample data was loaded
  4. Create a test marketing content document

Access Resources

# View all environment values
azd env get-values

# Get the web app URL
azd env get-value WEB_APP_URL

# Get resource group name
azd env get-value RESOURCE_GROUP_NAME

View Logs

# Backend container logs
az container logs \
  --name $(azd env get-value CONTAINER_INSTANCE_NAME) \
  --resource-group $(azd env get-value RESOURCE_GROUP_NAME) \
  --follow

# App Service logs
az webapp log tail \
  --name $(azd env get-value APP_SERVICE_NAME) \
  --resource-group $(azd env get-value RESOURCE_GROUP_NAME)

Clean Up

Delete All Resources

# Delete all Azure resources and the environment
azd down --purge

# Or just delete resources (keep environment config)
azd down

Delete Specific Environment

# List environments
azd env list

# Delete an environment
azd env delete <environment-name>

Troubleshooting

Common Issues

1. Quota Exceeded

Error: InsufficientQuota

Solution: Check your quota in the Azure portal or run:

az cognitiveservices usage list --location <region>

Request a quota increase or choose a different region.

2. Model Not Available in Region

Error: The model 'gpt-4o' is not available in region 'westeurope'

Solution: Set a different region for AI Services:

azd env set AZURE_ENV_AI_SERVICE_LOCATION eastus2

3. Container Build Fails

Error: az acr build failed

Solution: Check the Dockerfile and ensure all required files are present:

# Manual build for debugging
cd src/App
docker build -f WebApp.Dockerfile -t content-gen-app:test .

4. Frontend Deployment Fails

Error: az webapp deploy failed

Solution: Ensure the frontend builds successfully:

cd src/App
npm install
npm run build

5. RBAC Assignment Fails

Error: Authorization failed

Solution: Ensure you have Owner or User Access Administrator role on the subscription.

Debug Mode

For more verbose output:

azd up --debug

Reset Environment

If deployment gets into a bad state:

# Re-run provisioning
azd provision

Architecture Deployed

When enablePrivateNetworking is enabled:

┌─────────────────────────────────────────────────────────────────┐
│                        Azure Resource Group                      │
│                                                                  │
│  ┌──────────────────┐      ┌───────────────────────────────┐   │
│  │   App Service    │      │         Virtual Network        │   │
│  │  (Node.js Proxy) │──────│  ┌─────────────────────────┐  │   │
│  │                  │      │  │   Container Instance    │  │   │
│  └──────────────────┘      │  │   (Python Backend)      │  │   │
│          │                 │  └─────────────────────────┘  │   │
│          │                 │                                │   │
│  ┌───────▼──────────┐      │  ┌─────────────────────────┐  │   │
│  │  Azure AI Search │◄─────│──│   Private Endpoints     │  │   │
│  └──────────────────┘      │  └─────────────────────────┘  │   │
│          │                 └───────────────────────────────┘   │
│  ┌───────▼──────────┐                                          │
│  │    Cosmos DB     │                                          │
│  └──────────────────┘                                          │
│          │                                                      │
│  ┌───────▼──────────┐      ┌───────────────────────────────┐   │
│  │  Storage Account │      │      Azure AI Services        │   │
│  └──────────────────┘      │  (GPT-5.1, GPT-Image-1-mini) │   │
│                            └───────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

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

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:

azd up

Note: These custom files are configured to deploy your local code changes instead of pulling from the GitHub repository.