Skip to content

Latest commit

 

History

History
490 lines (340 loc) · 21.1 KB

DeploymentGuide.md

File metadata and controls

490 lines (340 loc) · 21.1 KB

Deployment Guide

Overview

This guide walks you through deploying the Modernize Your Code Solution Accelerator to Azure. The deployment process takes approximately 10-15 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.

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 Subscription/Resource Group level Configure RBAC permissions
App Registration Creation Azure Active Directory Create and configure authentication

🔍 How to Check Your Permissions:

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

  1. Go to Microsoft Entra ID → Manage → App registrations
  2. Try clicking New registration
  3. If you can access this page, you have the required permissions
  4. 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:

Recommended Regions: East US, East US2, Australia East, UK South, France Central, Japan East, Norway East, South India, Sweden Central, West US, West US 3

🔍 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: 5k tokens
  • Optimal: 200k tokens (recommended for best performance)

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 AI Model Quota Settings if needed.

Step 2: Choose Your Deployment Environment

Select one of the following options to deploy the Modernize Your Code 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)

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

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
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. Select the subscription where you want to deploy the solution

  4. Wait for the environment to initialize (includes all deployment tools)

  5. When prompted in the VS Code Web terminal, choose one of the available options shown

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

  7. Proceed to Step 3: Configure Deployment Settings

Option D: Local Environment

Required Tools:

Setup Steps:

  1. Install all required deployment tools listed above
  2. Clone the repository: 
    azd init -t microsoft/Modernize-your-Code-Solution-Accelerator/
  3. Open the project folder in your terminal
  4. 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

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

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:

  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)

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

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

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

4.1 Authenticate with Azure

azd auth login

For specific tenants:

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

Finding Tenant ID:

  1. Open the Azure Portal.
  2. Navigate to Microsoft Entra ID from the left-hand menu.
  3. Under the Overview section, locate the Tenant ID field. Copy the value displayed.

4.2 Start Deployment

azd up

During deployment, you'll be prompted for:

  1. Environment name (e.g., "cmsaapp") - Must be 3-16 characters long, alphanumeric only
  2. Azure subscription selection
  3. Azure region - Select a region with available GPT model quota
  4. Resource group selection (create new or use existing)

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

4.3 Get Application URL

After successful deployment:

  1. Open Azure Portal
  2. Navigate to your resource group
  3. Find the Container App with "frontend" in the name
  4. Copy the Application URI

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

Step 5: Post-Deployment Configuration

5.1 Configure Authentication (Required)

This step is mandatory for application access:

  1. Follow App Authentication Configuration
  2. Wait up to 10 minutes for authentication changes to take effect

5.2 Verify Deployment

  1. Access your application using the URL from Step 4.3
  2. Confirm the application loads successfully
  3. Verify you can sign in with your authenticated account

5.3 Test the Application

Follow the detailed workflow to test the migration functionality:

Quick Test Steps:

  1. Download sample SQL files from the /data/informix folder
  2. Upload the files to the application
  3. Click Start Processing to begin the migration
  4. Monitor the batch processing status
  5. Review the translated files and generated reports
  6. Download the results using the Download all as .zip button

📖 Detailed Instructions: See the complete Sample Workflow 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:

Managing Multiple Environments

Recover from Failed Deployment

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

Recover from Failed Deployment

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

If your deployment failed or encountered errors:

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

Example Recovery Workflow:

# Remove failed deployment (optional)
azd down

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

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

Example:

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

# Switch to the new environment
azd env select cmsaprod

# Deploy with fresh settings
azd up

Environment Name Requirements:

  • Length: 3-16 characters
  • Characters: Alphanumeric only (letters and numbers)
  • Valid examples: cmsaapp, 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:

azd env get-values

Best Practices for Multiple Environments

  • Use descriptive names: cmsadev, cmsaprod, cmsatest (remember: 3-16 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 to enhance your experience:

📚 Learn More:

Need Help?

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

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

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.

Environment Configuration for Local Development & Debugging

Set APP_ENV in your .env file to control Azure authentication. Use dev to enable to use Azure CLI credential, Prod to enable Managed Identity (for production). Ensure you're logged in via az login when using dev in local.

  1. Navigate to the src\backend 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.