Skip to content

AutomatedLocalSetup.md

Latest commit

 

History

History
199 lines (146 loc) · 7.33 KB

AutomatedLocalSetup.md

File metadata and controls

199 lines (146 loc) · 7.33 KB

Automated Local Development Setup

Two scripts — one for each platform — that automate the entire local development setup: Azure authentication, .env generation, Python/Node dependency installation, RBAC role assignment, and VS Code configuration.

Platform Script
Linux / macOS / WSL / Git Bash infra/scripts/setup_local_dev.sh
Windows PowerShell infra/scripts/setup_local_dev.ps1

Prerequisites

Tool Purpose
Python 3.12+ Backend and frontend virtual environments
Node.js 18+ Frontend build
uv Fast Python package management (backend & MCP)
Azure CLI Fetch Azure config and assign RBAC roles
Git Source control

You must be logged in before running (the script will prompt if you are not):

az login

What It Does (in order)

  1. Checks prerequisites — Python 3.12+, Node.js, npm, uv, Azure CLI, Git
  2. Azure authentication — logs you in if needed, confirms the active subscription 2b. Checks Azure roles & permissions — verifies you have role-assignment permission (Owner / User Access Administrator / RBAC Administrator) before attempting RBAC step (non-fatal warning)
  3. Fetches Azure configuration — reads deployment outputs or queries resources individually to build src/backend/.env
  4. Assigns RBAC roles — grants your user account the roles needed to run the app locally:
    • Cosmos DB Built-in Data Contributor
    • Azure AI User, Azure AI Developer, Cognitive Services OpenAI User
    • Search Index Data Contributor
    • Storage Blob Data Contributor
  5. Sets up Backend (src/backend) — creates a .venv with uv, installs all dependencies
  6. Sets up MCP Server (src/mcp_server) — same as backend
  7. Sets up Frontend (src/App) — creates a .venv, installs Python deps, runs npm install and npm run build
  8. Configures VS Code — writes .vscode/extensions.json and settings.json (skip with --skip-vscode)
  9. Prints a start summary with the exact commands to run each service

Quick Start

# bash (Linux / macOS / WSL / Git Bash)
bash infra/scripts/setup_local_dev.sh --resource-group <resource-group>

# PowerShell (Windows)
.\infra\scripts\setup_local_dev.ps1 -ResourceGroup <resource-group>

The script will:

  • Fetch all Azure settings and write src/backend/.env automatically
  • Create Python virtual environments and install all dependencies
  • Assign your account the required Azure roles

All Options

Bash

bash infra/scripts/setup_local_dev.sh [options]

Options:
  --resource-group, -g <name>   Azure Resource Group (auto-detected from .azure/ if omitted)
  --subscription, -s <id>       Azure Subscription ID (uses current az account if omitted)
  --skip-vscode                 Skip writing .vscode/ settings files
  --skip-prereqs                Skip prerequisite checks
  -h, --help                    Show help

PowerShell

.\infra\scripts\setup_local_dev.ps1 [options]

Options:
  -ResourceGroup <name>         Azure Resource Group (auto-detected from .azure/ if omitted)
  -Subscription <id>            Azure Subscription ID (uses current az account if omitted)
  -SkipVSCode                   Skip writing .vscode/ settings files
  -SkipPrereqs                  Skip prerequisite checks

Examples

# Fetch config from Azure and set up everything
bash infra/scripts/setup_local_dev.sh --resource-group rg-macae-dev

# Use a specific subscription
bash infra/scripts/setup_local_dev.sh --resource-group rg-macae-dev --subscription 00000000-0000-0000-0000-000000000000

# Skip VS Code settings (e.g. using a different editor)
bash infra/scripts/setup_local_dev.sh --resource-group rg-macae-dev --skip-vscode

# Skip prerequisite checks (useful in CI or if tools are on a non-standard PATH)
bash infra/scripts/setup_local_dev.sh --resource-group rg-macae-dev --skip-prereqs
# Fetch config from Azure and set up everything
.\infra\scripts\setup_local_dev.ps1 -ResourceGroup rg-macae-dev

# Use a specific subscription
.\infra\scripts\setup_local_dev.ps1 -ResourceGroup rg-macae-dev -Subscription 00000000-0000-0000-0000-000000000000

# Skip VS Code settings
.\infra\scripts\setup_local_dev.ps1 -ResourceGroup rg-macae-dev -SkipVSCode

Auto-Detection (no --resource-group)

If you ran azd up to deploy, the scripts will automatically find the .azure/<env>/.env file and use it — no flags needed:

bash infra/scripts/setup_local_dev.sh        # reads .azure/<env>/.env written by azd up
.\infra\scripts\setup_local_dev.ps1          # same

If no .azure/ folder exists and no --resource-group is provided, the script will prompt you to enter the resource group name interactively.

RBAC Roles Assigned

The script automatically grants your user account the following roles (skips if already assigned):

Role Resource Purpose
Cosmos DB Built-in Data Contributor Cosmos DB account Read/write conversation history
Azure AI User AI Foundry project Call AI Foundry APIs
Azure AI Developer AI Foundry project Deploy and manage agents
Cognitive Services OpenAI User AI Foundry project Call OpenAI endpoints
Search Index Data Contributor Azure AI Search Read/write search indexes
Storage Blob Data Contributor Storage account Read/write blob storage

Note: RBAC changes can take 5–10 minutes to propagate before the app can use them.

After Setup

Once the script finishes, start the three services in separate terminals (Backend first, then MCP, then Frontend):

Terminal 1 — Backend (port 8000):
  cd src/backend
  Activate virtual environment:
    PowerShell : .\.venv\Scripts\Activate.ps1
    Git Bash   : source .venv/Scripts/activate
    Linux/macOS: source .venv/bin/activate
  python app.py

Terminal 2 — MCP Server (port 9000):
  cd src/mcp_server
  Activate virtual environment:
    PowerShell : .\.venv\Scripts\Activate.ps1
    Git Bash   : source .venv/Scripts/activate
    Linux/macOS: source .venv/bin/activate
  python mcp_server.py --transport streamable-http --host 0.0.0.0 --port 9000

Terminal 3 — Frontend (port 3000):
  cd src/App
  Activate virtual environment:
    PowerShell : .\.venv\Scripts\Activate.ps1
    Git Bash   : source .venv/Scripts/activate
    Linux/macOS: source .venv/bin/activate
  python frontend_server.py

Then open http://localhost:3000.

Troubleshooting

Symptom Likely cause Fix
az login loop CLI not installed or PATH issue Install Azure CLI
.env values empty RG has no deployment outputs Pass --resource-group explicitly
uv: command not found uv not installed pip install uv or see uv docs
RBAC errors at runtime Roles not propagated Wait 10 min for Azure propagation; re-run script
source .venv/Scripts/activate: No such file Incomplete venv Delete .venv/ folder and re-run the script
Frontend npm errors Node.js version too old Upgrade to Node.js 18+

For more detail, see TroubleShootingSteps.md.