Deployment Guide

Overview

This guide walks you through deploying the Content Processing Solution Accelerator to Azure. The deployment process takes approximately 15-20 minutes for the default Development/Testing configuration and includes both infrastructure provisioning and application setup.

🆘 Need Help? If you encounter any issues during deployment, check our Troubleshooting Guide for solutions to common problems.

Note: Some tenants may have additional security restrictions that run periodically and could impact the application (e.g., blocking public network access). If you experience issues or the application stops working, check if these restrictions are the cause. In such cases, consider deploying the WAF-supported version to ensure compliance. To configure, Click here.

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 or Resource Group	Create and manage Azure resources
User Access Administrator	Subscription or Resource Group	Manage user access and role assignments
Role Based Access Control Admin	Subscription/Resource Group level	Configure RBAC permissions
Application Administrator	Tenant	Create app registrations for authentication

🔍 How to Check Your Permissions:

Go to Azure Portal
Navigate to Subscriptions (search for "subscriptions" in the top search bar)
Click on your target subscription
In the left menu, click Access control (IAM)
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)

For App Registration permissions:

Go to Microsoft Entra ID → Manage → App registrations
Try clicking New registration
If you can access this page, you have the required permissions
Cancel without creating an app registration

📖 Detailed Setup: Follow Azure Account Set Up for complete configuration.

1.2 Check Service Availability & Quota

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

Required Azure Services:

Azure AI Foundry
Azure OpenAI Service
Azure AI Content Understanding Service
Azure Blob Storage
Azure Container Apps (4 container apps: Processor, API, Web, Workflow)
Azure Container Registry
Azure Cosmos DB
Azure Queue Storage
Azure App Configuration
GPT Model Capacity

Recommended Regions: Australia East, Central US, East Asia, East US 2, Japan East, North Europe, Southeast Asia, UK South.

🔍 Check Availability: Use Azure Products by Region to verify service availability.

1.3 Quota Check (Optional)

💡 RECOMMENDED: Check your Azure OpenAI quota availability before deployment for optimal planning.

📖 Follow: Quota Check Instructions to ensure sufficient capacity.

Recommended Configuration:

Default: 300k tokens
Optimal: 500k tokens (recommended for multi-document claim processing)

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.

📖 Adjust Quota: Follow Azure GPT Quota Settings if needed.

Step 2: Choose Your Deployment Environment

Select one of the following options to deploy the Content Processing Solution Accelerator:

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

💡 Recommendation: For fastest deployment, start with GitHub Codespaces - no local installation required.

Option A: GitHub Codespaces (Easiest)

Click the badge above (may take several minutes to load)
Accept default values on the Codespaces creation page
Wait for the environment to initialize (includes all deployment tools)
Proceed to Step 3: Configure Deployment Settings

Option B: VS Code Dev Containers

Prerequisites:

Docker Desktop installed and running
VS Code with Dev Containers extension

Steps:

Start Docker Desktop
Click the badge above to open in Dev Containers
Wait for the container to build and start (includes all deployment tools)
Proceed to Step 3: Configure Deployment Settings

Option C: Visual Studio Code Web

Click the badge above (may take a few minutes to load)
Sign in with your Azure account when prompted
Select the subscription where you want to deploy the solution
Wait for the environment to initialize (includes all deployment tools)
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.
Authenticate with Azure (VS Code Web requires device code authentication):
```
az login --use-device-code
```
Note: In VS Code Web environment, the regular az login command may fail. Use the --use-device-code flag to authenticate via device code flow. Follow the prompts in the terminal to complete authentication.
Proceed to Step 3: Configure Deployment Settings

Option D: Local Environment

Required Tools:

Setup Steps:

Install all required deployment tools listed above

Clone the repository:

azd init -t microsoft/content-processing-solution-accelerator/

Open the project folder in your terminal
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:

Copy the contents from the production configuration file to your main parameters file:

Navigate to the infra folder in your project
Open main.waf.parameters.json in a text editor (like Notepad, VS Code, etc.)
Select all content (Ctrl+A) and copy it (Ctrl+C)
Open main.parameters.json in the same text editor
Select all existing content (Ctrl+A) and paste the copied content (Ctrl+V)
Save the file (Ctrl+S)

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:

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.

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

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. Configuration Guide
Azure AI Foundry Project: Leverage your existing AI Foundry project and deployed models to avoid duplication and reduce provisioning time. Configuration Guide

Key Benefits:

Cost Optimization: Eliminate duplicate resource charges
Operational Consistency: Maintain unified monitoring and AI infrastructure
Faster Deployment: Skip resource creation for existing compatible services
Simplified Management: 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

💡 Before You Start: If you encounter any issues during deployment, check our Troubleshooting Guide for common solutions.

⚠️ Critical: Redeployment Warning
If you have previously run azd up in this folder (i.e., a .azure folder exists), you must create a fresh environment to avoid conflicts and deployment failures.

4.1 Authenticate with Azure

azd auth login

For specific tenants:

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

Finding Tenant ID:

Open the Azure Portal.

Navigate to Microsoft Entra ID from the left-hand menu.

Under the Overview section, locate the Tenant ID field. Copy the value displayed.

4.2 Start Deployment

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

During deployment, you'll be prompted for:

Environment name - Must be 3-20 characters, lowercase alphanumeric only (e.g., cpsapp01).
Azure subscription selection.
Azure AI Foundry deployment region - Select a region with available GPT-5.1 model quota for AI operations.
Primary location - Select the region where your infrastructure resources will be deployed (Australia East, Central US, East Asia, East US 2, Japan East, North Europe, Southeast Asia, UK South).
Resource group selection (create new or use existing).

Expected Duration: 4-6 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.

⚠️ Important: Complete Post-Deployment Steps before accessing the application.

Step 5: Post-Deployment Configuration

5.1 Schema Registration (Automatic)

Want to customize the schemas for your own documents? Learn more about adding your own schemas here.

Schema registration happens automatically as part of the azd up post-provisioning hook — no manual steps required. After infrastructure is deployed, the hook:

Waits for the API container app to be ready
Registers the sample schema files (auto claim, damaged car image, police report, repair estimate)
Creates an "Auto Claim" schema set
Adds all registered schemas into the schema set
Processes sample file bundles (claim_date_of_loss/ and claim_hail/) — creates claim batches, uploads files with their mapped schemas, and submits them for processing

After successful deployment, the terminal displays container app details and schema registration output:

🧭 Web App Details:
  ✅ Name: ca-<env>-web
  🌐 Endpoint: ca-<env>-web.<region>.azurecontainerapps.io
  🔗 Portal URL: https://portal.azure.com/#resource/...

🧭 API App Details:
  ✅ Name: ca-<env>-api
  🌐 Endpoint: ca-<env>-api.<region>.azurecontainerapps.io
  🔗 Portal URL: https://portal.azure.com/#resource/...

🧭 Workflow App Details:
  ✅ Name: ca-<env>-wkfl
  🔗 Portal URL: https://portal.azure.com/#resource/...

📦 Registering schemas and creating schema set...
  ⏳ Waiting for API to be ready...
  ✅ API is ready.
============================================================
Step 1: Register schemas
============================================================
✓ Successfully registered: Auto Insurance Claim Form's Schema Id - <id>
✓ Successfully registered: Damaged Vehicle Image Assessment's Schema Id - <id>
✓ Successfully registered: Police Report Document's Schema Id - <id>
✓ Successfully registered: Repair Estimate Document's Schema Id - <id>

============================================================
Step 2: Create schema set
============================================================
✓ Created schema set 'Auto Claim' with ID: <id>

============================================================
Step 3: Add schemas to schema set
============================================================
  ✓ Added 'AutoInsuranceClaimForm' (<id>) to schema set
  ✓ Added 'DamagedVehicleImageAssessment' (<id>) to schema set
  ✓ Added 'PoliceReportDocument' (<id>) to schema set
  ✓ Added 'RepairEstimateDocument' (<id>) to schema set

============================================================
Schema registration process completed.
  Schema set ID: <id>
  Schemas added: 4
============================================================

============================================================
Step 4: Process sample file bundles
============================================================

  📂 Processing bundle: claim_date_of_loss
    ✅ Claim batch created with ID: <id>
    ✅ Uploaded 'claim_form.pdf' successfully.
    ✅ Uploaded 'damage_photo.png' successfully.
    ✅ Uploaded 'police_report.pdf' successfully.
    ✅ Uploaded 'repair_estimate.pdf' successfully.
    ✅ Claim batch '<id>' submitted for processing.

  📂 Processing bundle: claim_hail
    ✅ Claim batch created with ID: <id>
    ✅ Uploaded 'claim_form.pdf' successfully.
    ✅ Uploaded 'damage_photo.png' successfully.
    ✅ Uploaded 'repair_estimate.pdf' successfully.
    ✅ Claim batch '<id>' submitted for processing.

============================================================
Sample file processing completed.
============================================================

5.2 Configure Authentication (Automatic)

Starting with this release, authentication is configured automatically as part of the azd up post-provisioning hook. The hook:

Creates two Entra ID app registrations (<env>-web-app, <env>-api-app) with the correct redirect URIs, exposed scopes, and required permissions
Grants admin consent (best effort — see note below)
Mints client secrets and stores them in Container Apps secrets
Enables the Microsoft identity provider on both the Web and API container apps
Restricts the API to only accept tokens from the Web app (allowedApplications)
Sets the APP_WEB_CLIENT_ID, APP_WEB_SCOPE, APP_API_SCOPE, and APP_AUTH_ENABLED environment variables on the Web container

You will see an 🔐 Configuring Entra ID authentication section in the azd up output, ending with a summary of both client IDs and scopes.

Note: EasyAuth can take up to 10 minutes to fully propagate. If the Web app returns 500/401 immediately after deployment, wait a few minutes and retry.

When automatic configuration is not possible

Automatic configuration requires permission to:

Create Entra ID app registrations (Application Administrator or equivalent)
Grant admin consent for delegated permissions (Cloud Application Administrator or Global Administrator)

If your identity cannot grant admin consent, the script prints a clear manual action message like:

⚠️ Admin consent failed. Sign-in may fail until a tenant admin runs:
     az ad app permission admin-consent --id <web-client-id>
   Or visit: https://login.microsoftonline.com/<tenant>/adminconsent?client_id=<web-client-id>

In that case, share the command/URL with your tenant administrator.

Skipping automatic auth configuration

If your tenant blocks programmatic app registration, or you prefer to configure authentication manually, disable the automation before running azd up:

azd env set AZURE_SKIP_AUTH_SETUP true

Then follow the manual instructions: App Authentication Configuration (manual).

Re-running

The automation is idempotent: re-running azd up reuses the existing app registrations (IDs are persisted in AZURE_AUTH_WEB_CLIENT_ID / AZURE_AUTH_API_CLIENT_ID in the azd environment) and does not rotate client secrets.

WAF (Well-Architected Framework) deployments

The automation is fully compatible with the WAF / production profile (main.waf.parameters.json, which enables enablePrivateNetworking, enableRedundancy, and enableScalability). The Web and API container apps keep external ingress in the default WAF profile, so the redirect URIs registered by the script (https://<fqdn>/.auth/login/aad/callback) remain the correct public entry points. All script operations use the Azure management plane (Graph + ARM) and are unaffected by the private networking applied to backend resources such as Storage, Cosmos DB, and ACR.

If you further customize the WAF deployment to make the Web or API container app ingress internal-only, automatic configuration still runs, but end-user access to the sign-in page will require reaching the private endpoint (e.g., via the deployed jumpbox or a VPN).

5.3 Verify Deployment

Access your application using the Web App Endpoint from the deployment output.
Confirm the application loads successfully.
Verify you can sign in with your authenticated account.

5.4 Test the Application

Note: The post-deployment hook automatically uploads and processes two sample claim bundles (claim_date_of_loss and claim_hail). You can verify the results in the web app immediately after deployment.

Quick Test Steps:

Check Processed Results: Open the web app — you should see the two sample claim batches already processed with extracted data.
Review: Click a processed claim row to verify the extracted data against the source document.
Upload More (Optional): To test additional uploads, get sample files from the samples directory, select the "Auto Claim" schema set, and upload via Import Content.

📖 Detailed Instructions: See the complete Golden Path Workflows guide for step-by-step testing procedures.

Step 6: Clean Up (Optional)

Remove All Resources

azd down

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.

Manual Cleanup (if needed)

If deployment fails or you need to clean up manually:

Follow Delete Resource Group Guide.

Managing Multiple Environments

Recover from Failed Deployment

If your deployment failed or encountered errors, here are the steps to recover:

Recover from Failed Deployment

If your deployment failed or encountered errors:

Try a different region: Create a new environment and select a different Azure region during deployment
Clean up and retry: Use azd down to remove failed resources, then azd up to redeploy
Check troubleshooting: Review Troubleshooting Guide for specific error solutions
Fresh start: Create a completely new environment with a different name

Example Recovery Workflow:

# Remove failed deployment (optional)
azd down

# Create new environment (3-20 chars, alphanumeric only)
azd env new conpro2

# Deploy with different settings/region
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

Create Environment Explicitly:

# Create a new named environment (3-20 characters, lowercase 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

Example:

# Create a new environment for production (valid: 3-20 chars)
azd env new conproprod

# Switch to the new environment
azd env select conproprod

# Deploy with fresh settings
azd up

Environment Naming Requirements:

Length: 3-20 characters

Characters: Lowercase alphanumeric only (a-z, 0-9)

No special characters (-, _, spaces, etc.)

Valid examples: conpro, test123, myappdev, prod2024

Invalid examples: co (too short), my-very-long-environment-name (too long), test_env (underscore not allowed), myapp-dev (hyphen not allowed)

Switch Between Environments

List Available Environments:

azd env list

Switch to Different Environment:

azd env select <environment-name>

View Current Environment Variables:

azd env get-values

Best Practices for Multiple Environments

Use descriptive names: conprodev, conproprod, conprotest (remember: 3-20 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

Next Steps

Now that your deployment is complete and tested, explore these resources:

Technical Architecture - Understand the system design and components
Create Custom Schemas - Learn how to add your own document schemas
API Integration - Explore programmatic document processing
Local Development Setup - Set up your local development environment

Need Help?

🐛 Issues: Check Troubleshooting Guide
💬 Support: Review Support Guidelines
🔧 Development: See Contributing Guide

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.

Step 1: Rename Azure Configuration Files

In the root directory:

Rename azure.yaml to azure_custom2.yaml
Rename azure_custom.yaml to azure.yaml

Step 2: Rename Infrastructure Files

In the infra directory:

Rename main.bicep to main_custom2.bicep
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.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Deployment Guide

Overview

Step 1: Prerequisites & Setup

1.1 Azure Account Requirements

1.2 Check Service Availability & Quota

1.3 Quota Check (Optional)

Step 2: Choose Your Deployment Environment

Environment Comparison

Step 3: Configure Deployment Settings

3.1 Choose Deployment Type (Optional)

3.2 Set VM Credentials (Optional - Production Deployment Only)

3.3 Advanced Configuration (Optional)

Step 4: Deploy the Solution

4.1 Authenticate with Azure

4.2 Start Deployment

Step 5: Post-Deployment Configuration

5.1 Schema Registration (Automatic)

5.2 Configure Authentication (Automatic)

When automatic configuration is not possible

Skipping automatic auth configuration

Re-running

WAF (Well-Architected Framework) deployments

5.3 Verify Deployment

5.4 Test the Application

Step 6: Clean Up (Optional)

Remove All Resources

Manual Cleanup (if needed)

Managing Multiple Environments

Recover from Failed Deployment

Creating a New Environment

Best Practices for Multiple Environments

Next Steps

Need Help?

Advanced: Deploy Local Changes

Step 1: Rename Azure Configuration Files

Step 2: Rename Infrastructure Files

Step 3: Deploy Changes

FilesExpand file tree

DeploymentGuide.md

Latest commit

History

DeploymentGuide.md

File metadata and controls

Deployment Guide

Overview

Step 1: Prerequisites & Setup

1.1 Azure Account Requirements

1.2 Check Service Availability & Quota

1.3 Quota Check (Optional)

Step 2: Choose Your Deployment Environment

Environment Comparison

Step 3: Configure Deployment Settings

3.1 Choose Deployment Type (Optional)

3.2 Set VM Credentials (Optional - Production Deployment Only)

3.3 Advanced Configuration (Optional)

Step 4: Deploy the Solution

4.1 Authenticate with Azure

4.2 Start Deployment

Step 5: Post-Deployment Configuration

5.1 Schema Registration (Automatic)

5.2 Configure Authentication (Automatic)

When automatic configuration is not possible

Skipping automatic auth configuration

Re-running

WAF (Well-Architected Framework) deployments

5.3 Verify Deployment

5.4 Test the Application

Step 6: Clean Up (Optional)

Remove All Resources

Manual Cleanup (if needed)

Managing Multiple Environments

Recover from Failed Deployment

Creating a New Environment

Best Practices for Multiple Environments

Next Steps

Need Help?

Advanced: Deploy Local Changes

Step 1: Rename Azure Configuration Files

Step 2: Rename Infrastructure Files

Step 3: Deploy Changes