Local Development Setup Guide

This guide provides comprehensive instructions for setting up the Modernize your code Solution Accelerator for local development across Windows and Linux platforms.

Important Setup Notes

Multi-Service Architecture

This application consists of two separate services that run independently:

Backend API - REST API server providing migration and SQL agent services
Frontend - React-based user interface

⚠️ Critical: Each service must run in its own terminal/console window

Do NOT close terminals while services are running

Open 2 separate terminal windows for local development

Each service will occupy its terminal and show live logs

Terminal Organization:

Terminal 1: Backend API - HTTP server on port 8000

Terminal 2: Frontend - Development server on port 5173

Path Conventions

All paths in this guide are relative to the repository root directory:

Modernize-your-code-solution-accelerator/    ← Repository root (start here)
├── src/
│   ├── backend/                           
│   │   ├── .venv/                          ← Virtual environment
│   │   ├── app.py                          ← API entry point
│   │   ├── requirements.txt                ← Python dependencies
│   │   └── .env                            ← Backend config file
│   └── frontend/                           
│       ├── node_modules/                    
│       ├── package.json                    ← Node dependencies
│       └── .env                            ← Frontend config file
└── docs/                                   ← Documentation (you are here)

Before starting any step, ensure you are in the repository root directory:

# Verify you're in the correct location
pwd  # Linux/macOS - should show: .../Modernize-your-code-solution-accelerator
Get-Location  # Windows PowerShell - should show: ...\Modernize-your-code-solution-accelerator

# If not, navigate to repository root
cd path/to/Modernize-your-code-solution-accelerator

Configuration Files

This project uses separate .env files in each service directory with different configuration requirements:

Backend API: src/backend/.env - Azure App Configuration URL and service settings
Frontend: src/frontend/.env - Azure AD authentication settings and API URL

When copying .env samples, always navigate to the specific service directory first.

Step 1: Prerequisites - Install Required Tools

Windows Development

Option 1: Native Windows (PowerShell)

# Install Python 3.9+ and Git
winget install Python.Python.3.12
winget install Git.Git

# Install Node.js for frontend
winget install OpenJS.NodeJS.LTS

# Verify installations
python --version
git --version
node --version
npm --version

Option 2: Windows with WSL2 (Recommended)

# Install WSL2 first (run in PowerShell as Administrator):
wsl --install -d Ubuntu

# Then in WSL2 Ubuntu terminal:
sudo apt update && sudo apt install python3.12 python3.12-venv git curl nodejs npm -y

# Verify installations
python3 --version
git --version
node --version
npm --version

Linux Development

Ubuntu/Debian

# Install prerequisites
sudo apt update && sudo apt install python3.9 python3.9-venv git curl nodejs npm -y

# Verify installations
python3 --version
git --version
node --version
npm --version

RHEL/CentOS/Fedora

# Install prerequisites
sudo dnf install python3.9 python3.9-devel git curl gcc nodejs npm -y

# Verify installations
python3 --version
git --version
node --version
npm --version

Clone the Repository

git clone https://github.com/microsoft/Modernize-your-code-solution-accelerator.git
cd Modernize-your-code-solution-accelerator

Step 2: Development Tools Setup

Development Container Setup (Optional)

The solution contains a development container with all required tooling pre-configured.

Prerequisites:

Quick Start:

Start Docker Desktop
Open in Dev Container: Open in Dev Containers
Wait for the container to build (first time takes a few minutes)
All development tools are pre-installed in the container

Manual Setup:

# Clone the repository
git clone https://github.com/microsoft/Modernize-your-code-solution-accelerator
cd Modernize-your-code-solution-accelerator

# Open in VS Code
code .

# When prompted, click "Reopen in Container"

💡 Tip: Visual Studio Code will recognize the available development container and ask you to open the folder using it. The container configuration files are in /.devcontainer/ folder.

Step 3: Azure Infrastructure Deployment

Before running the application locally, you need to deploy the Azure infrastructure.

Azure Authentication

First, authenticate with Azure:

# Login to Azure CLI
az login

# Set your subscription
az account set --subscription "your-subscription-id"

# Verify authentication
az account show

Create Resource Group

Create a resource group for your deployment:

# Via Azure CLI
az group create --name <resource-group-name> --location eastus

# Or use Azure Portal to create the resource group manually

Deploy Infrastructure

You have two options for deploying the Azure infrastructure:

Option A: Using Azure Developer CLI (Recommended)

# Initialize the environment
azd env new <environment-name>

# Deploy the infrastructure and application
azd up

Note: You will be prompted for various parameters including:

principalId: The ObjectID of your user in Entra ID. To find it:
```
az ad signed-in-user show --query id -o tsv
```
Azure AI Service Location: Choose from supported regions (eastus, japaneast, etc.)
Solution Name: A unique name for your deployment

Option B: Using Azure CLI with Bicep

az deployment group create \
  -g <resource-group-name> \
  -f infra/main.bicep \
  --query 'properties.outputs'

Required Azure RBAC Permissions

To run the application locally, your Azure account needs the following role assignments:

Cosmos DB Access

# Get your principal ID
PRINCIPAL_ID=$(az ad signed-in-user show --query id -o tsv)

# Assign Cosmos DB Built-in Data Contributor role
az cosmosdb sql role assignment create \
  --resource-group <resource-group-name> \
  --account-name <cosmos-db-account-name> \
  --role-definition-name "Cosmos DB Built-in Data Contributor" \
  --principal-id $PRINCIPAL_ID \
  --scope /subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<cosmos-db-account-name>

Azure OpenAI Access

# Assign Cognitive Services OpenAI User role
az role assignment create \
  --assignee <aad-user-upn> \
  --role "Cognitive Services OpenAI User" \
  --scope /subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.CognitiveServices/accounts/<azure-openai-name>

# Assign Azure AI User role
az role assignment create \
  --assignee <aad-user-upn> \
  --role "Azure AI User" \
  --scope /subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.CognitiveServices/accounts/<azure-openai-name>

Other Required Roles

Depending on the features you use, you may also need:

Storage Blob Data Contributor - For Azure Storage operations

Note: RBAC permission changes can take 5-10 minutes to propagate. If you encounter "Forbidden" errors after assigning roles, wait a few minutes and try again.

Step 4: Backend API Setup & Run Instructions

📋 Terminal Reminder: Open a dedicated terminal window (Terminal 1) for the Backend API. All commands in this section assume you start from the repository root directory.

4.1. Navigate to Backend Directory

# From repository root
cd src/backend

4.2. Configure Backend Environment Variables

Create a .env file in the src/backend directory:

# Copy the example file
cp .env.sample .env  # Linux/macOS
# or
Copy-Item .env.sample .env  # Windows PowerShell

Edit the .env file with your Azure configuration. Find these values by navigating to your resource group and selecting the resource with prefix ca-backend-.

In the resource's Configuration (Application settings) section, copy the environment variable values into your .env file. For reference, see the image below:

Key configuration values:

# CosmosDB Configuration
COSMOSDB_ENDPOINT= https://[your-cosmos-account].documents.azure.com:443/
COSMOSDB_DATABASE= 
COSMOSDB_BATCH_CONTAINER=
COSMOSDB_FILE_CONTAINER=
COSMOSDB_LOG_CONTAINER= 

# Azure OpenAI settings
AZURE_OPENAI_ENDPOINT=https://[your-openai-resource].openai.azure.com/

# Azure Blob Storage Configuration
AZURE_BLOB_ENDPOINT=
AZURE_BLOB_ACCOUNT_NAME= 
AZURE_BLOB_CONTAINER_NAME= 

# Azure AI Foundry Configuration
AZURE_AI_AGENT_PROJECT_CONNECTION_STRING= ""
AZURE_AI_AGENT_SUBSCRIPTION_ID= ""
AZURE_AI_AGENT_RESOURCE_GROUP_NAME= ""
AZURE_AI_AGENT_PROJECT_NAME= ""
AZURE_AI_AGENT_MODEL_DEPLOYMENT_NAME= ""

# Basic application logging (default: INFO level)
AZURE_BASIC_LOGGING_LEVEL=INFO
APP_ENV= "dev"
# Azure package logging (default: WARNING level to suppress INFO)
AZURE_PACKAGE_LOGGING_LEVEL=WARNING

4.3. Install Backend Dependencies

# Create and activate virtual environment
python -m venv .venv

# Activate virtual environment
source .venv/bin/activate  # Linux/macOS/WSL2
# or
.\.venv\Scripts\Activate.ps1  # Windows PowerShell

# Install dependencies
pip install -r requirements.txt

Troubleshooting:

If python command not found, try python3 or py -3.12
On Windows, if activation fails, run: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

4.4. Run the Backend API

# Make sure you're in the backend directory with virtual environment activated
uvicorn app:app --reload --host 0.0.0.0 --port 8000

The Backend API will start at:

API: http://localhost:8000
API Documentation: http://localhost:8000/docs (Swagger UI)
Health Check: http://localhost:8000/health

Expected output:

INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     Started reloader process
INFO:     Started server process
INFO:     Waiting for application startup.
INFO:     Application startup complete.

Step 5: Frontend (UI) Setup & Run Instructions

📋 Terminal Reminder: Open a second dedicated terminal window (Terminal 2) for the Frontend. Keep Terminal 1 (Backend API) running. All commands assume you start from the repository root directory.

5.1. Navigate to Frontend Directory

# From repository root
cd src/frontend

5.2. Install Frontend Dependencies

npm install

Troubleshooting:

# If you encounter issues, try clearing cache
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

5.3. Configure Frontend Environment Variables

Create a .env file in the src/frontend directory:

# Copy the example file
cp .env.sample .env  # Linux/macOS
# or
Copy-Item .env.sample .env  # Windows PowerShell

Edit the .env file with your Azure AD configuration:

# Required: Your Azure AD app registration client ID
VITE_APP_WEB_CLIENT_ID=your-client-id-here

# Required: Your Azure AD tenant authority
VITE_APP_WEB_AUTHORITY=https://login.microsoftonline.com/your-tenant-id

# Optional: Redirect URLs (defaults to current origin)
VITE_APP_REDIRECT_URL=http://localhost:5173
VITE_APP_POST_REDIRECT_URL=http://localhost:5173

# Required: Scopes for login and token acquisition
VITE_APP_WEB_SCOPE=User.Read
VITE_APP_API_SCOPE=User.Read

# API URL
VITE_API_URL=http://localhost:8000/api

⚠️ Important Authentication Setup Notes:

Azure AD App Registration Required:

You must have an Azure AD app registration with a Client ID and Tenant ID

See AddAuthentication.md for detailed setup instructions

App Registration Configuration in Azure Portal:

Go to Azure Portal → Azure Active Directory → App registrations → Your App

Under Authentication, add a platform:

Select Single-page application (SPA)

Add redirect URI: http://localhost:5173

Enable Implicit grant and hybrid flows:

✅ Check Access tokens

✅ Check ID tokens

Click Save

Restart Required:

After updating .env, stop and restart the frontend dev server

Vite caches environment variables at startup

Navigate to your resource group and select the resource with prefix ca-frontend- to get the frontend environment variables:

For reference, see the image below:

5.4. Build the Frontend

npm run build

5.5. Start Development Server

npm run dev

The frontend will start at:

http://localhost:5173

Expected output:

VITE v4.x.x  ready in xxx ms

➜  Local:   http://localhost:5173/
➜  Network: use --host to expose

Step 6: Verify All Services Are Running

Before using the application, confirm both services are running in separate terminals:

Terminal Status Checklist

Terminal	Service	Command	Expected Output	URL
Terminal 1	Backend API	`uvicorn app:app --reload`	`INFO: Application startup complete`	http://localhost:8000
Terminal 2	Frontend	`npm run dev`	`Local: http://localhost:5173/`	http://localhost:5173

Quick Verification

1. Check Backend API:

# In a new terminal (Terminal 3)
curl http://localhost:8000/health
# Expected: {"status":"healthy"} or similar

# Or visit in browser:
# http://localhost:8000/docs (Swagger UI)

2. Check Frontend:

Open browser to http://localhost:5173
Should see the Modernize Code UI
If authentication is configured, you'll be redirected to Azure AD login

Common Issues

Service not starting?

Ensure you're in the correct directory
Verify virtual environment is activated (Python backend)
Check that port is not already in use (8000 for API, 5173 for frontend)
Review error messages in the terminal

Can't access services?

Verify firewall isn't blocking ports 8000 or 5173
Try http://localhost:port instead of http://127.0.0.1:port
Ensure services show "startup complete" messages

Port Conflicts:

# Check what's using the port
netstat -tulpn | grep :8000  # Linux/macOS
netstat -ano | findstr :8000  # Windows PowerShell

# Kill the process if needed (use PID from above command)
kill -9 <PID>  # Linux/macOS
Stop-Process -Id <PID>  # Windows PowerShell

Step 7: Debugging the Application

Backend Debugging in VS Code

Create or update .vscode/launch.json with this configuration:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python Debugger: Modernize Code API",
      "type": "debugpy",
      "request": "launch",
      "cwd": "${workspaceFolder}/src/backend",
      "module": "uvicorn",
      "args": ["app:app", "--reload", "--host", "0.0.0.0", "--port", "8000"],
      "jinja": true,
      "envFile": "${workspaceFolder}/src/backend/.env"
    }
  ]
}

To debug:

Set breakpoints in your Python code
Press F5 or click "Run and Debug" in VS Code
Select "Python Debugger: Modernize Code API"
Backend will start with debugger attached

Frontend Debugging

For debugging the React frontend:

Use Browser Developer Tools (F12)
Install React Developer Tools browser extension
Set up VS Code debugging with the appropriate extensions

Enable Debug Logging

Enable detailed logging in your src/backend/.env file:

APP_LOGGING_LEVEL=DEBUG
APP_ENV=dev
AZURE_OPENAI_API_VERSION=2024-08-01-preview

Restart the backend after changing environment variables.

Agent System Debugging

To debug the SQL agents system:

Enable debug logging (see above)
Monitor agent interactions through application logs and WebSocket messages
Test individual agents using the API endpoints at http://localhost:8000/docs

Step 8: Using Docker for Local Development (Optional)

If you prefer containerized development, you can use Docker Compose:

Prerequisites

Docker Desktop installed and running
Navigate to repository root

Run with Docker Compose

# Build and start all services
docker-compose -f docker/docker-compose.yml up --build

# Run in detached mode (background)
docker-compose -f docker/docker-compose.yml up -d --build

# View logs
docker-compose -f docker/docker-compose.yml logs -f

# Stop services
docker-compose -f docker/docker-compose.yml down

Access Services

Frontend: http://localhost:3000
Backend: http://localhost:8000
API Docs: http://localhost:8000/docs

Troubleshooting

Common Issues

Python Module Not Found

# Ensure virtual environment is activated
source .venv/bin/activate  # Linux/macOS
.\.venv\Scripts\Activate.ps1  # Windows

# Reinstall dependencies
pip install -r requirements.txt

Node.js Dependencies Issues

# Clear npm cache and reinstall
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Azure Authentication Issues

# Re-authenticate
az logout
az login

# Verify correct subscription
az account show

Environment Variables Not Loading

Verify .env file is in the correct directory
Check file permissions (especially on Linux/macOS)
Ensure no extra spaces in variable assignments
Restart the service after changing .env files

CORS Issues

Ensure API CORS settings include the web app URL
Check browser network tab for CORS errors
Verify API is running on the expected port

Agent Initialization Failures

Verify Azure AI Foundry endpoint is correct
Check Azure OpenAI model deployments are available
Ensure proper authentication and permissions (see Step 3)

Windows PowerShell Execution Policy

# If you can't activate virtual environment
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Database Connection Issues

Using a Different Database in Cosmos:

You can configure the solution to use a different database in Cosmos (e.g., modernize-dev):

Change the environment variable AZURE_COSMOS_DATABASE in .env
Create the database in Cosmos DB account from the Data Explorer pane in Azure Portal

Debug Mode Checklist

When troubleshooting issues, ensure:

✅ All prerequisites installed (Python, Node.js, Azure CLI)
✅ Azure infrastructure deployed successfully
✅ RBAC permissions assigned (may take 5-10 minutes to propagate)
✅ .env files created and configured correctly
✅ Virtual environment activated for Python
✅ Dependencies installed (pip install / npm install)
✅ Ports 8000 and 5173 are not in use by other applications
✅ Services show "startup complete" messages
✅ Azure AD app registration configured for SPA (if using authentication)

Step 9: Next Steps

Once all services are running (as confirmed in Step 6), you can:

Access the Application: Open http://localhost:5173 in your browser
Explore the API: Visit http://localhost:8000/docs for interactive API documentation
Customize Agents: Follow CustomizingScenario.md to modify agent behavior
Deploy to Production: See DeploymentGuide.md for production deployment

FilesExpand file tree

LocalDevelopmentSetup.md

Latest commit

History

LocalDevelopmentSetup.md

File metadata and controls

Local Development Setup Guide

Important Setup Notes

Multi-Service Architecture

Path Conventions

Configuration Files

Step 1: Prerequisites - Install Required Tools

Windows Development

Option 1: Native Windows (PowerShell)

Option 2: Windows with WSL2 (Recommended)

Linux Development

Ubuntu/Debian

RHEL/CentOS/Fedora

Clone the Repository

Step 2: Development Tools Setup

Development Container Setup (Optional)

Step 3: Azure Infrastructure Deployment

Azure Authentication

Create Resource Group

Deploy Infrastructure

Option A: Using Azure Developer CLI (Recommended)

Option B: Using Azure CLI with Bicep

Required Azure RBAC Permissions

Cosmos DB Access

Azure OpenAI Access

Other Required Roles

Step 4: Backend API Setup & Run Instructions

4.1. Navigate to Backend Directory

4.2. Configure Backend Environment Variables

4.3. Install Backend Dependencies

4.4. Run the Backend API

Step 5: Frontend (UI) Setup & Run Instructions

5.1. Navigate to Frontend Directory

5.2. Install Frontend Dependencies

5.3. Configure Frontend Environment Variables

5.4. Build the Frontend

5.5. Start Development Server

Step 6: Verify All Services Are Running

Terminal Status Checklist

Quick Verification

Common Issues

Step 7: Debugging the Application

Backend Debugging in VS Code

Frontend Debugging

Enable Debug Logging

Agent System Debugging

Step 8: Using Docker for Local Development (Optional)

Prerequisites

Run with Docker Compose

Access Services

Troubleshooting

Common Issues

Python Module Not Found

Node.js Dependencies Issues

Azure Authentication Issues

Environment Variables Not Loading

CORS Issues

Agent Initialization Failures

Windows PowerShell Execution Policy

Database Connection Issues

Debug Mode Checklist

Step 9: Next Steps

Related Documentation