Prerequisites

Prerequisites

One-Time Setup

Complete these prerequisites once before starting any guide in this documentation.

Windows Users: Use Bash

This project's scripts and Makefile targets are designed for Bash. On Windows:

• Recommended: Use Git Bash (comes with Git for Windows)
• Alternative: Use WSL 2 with Ubuntu
• Not recommended: PowerShell or Command Prompt may encounter issues with shell scripts

All commands in this documentation assume a Bash-compatible shell.

---

Required Tools

Install these tools on your development machine:

Tool	Purpose	Install	Verify
Azure CLI	Azure resource management	Install	az --version
Azure Developer CLI	One-command deployment	Install	azd version
Docker or Podman	Container builds	Docker / Podman	docker --version
Python 3.11+	Backend runtime	Install	python --version
Node.js 22+	Frontend build	Install	node --version
jq	JSON processing for scripts	Install	jq --version

Podman as Docker Alternative

Podman is fully supported! If you prefer Podman over Docker, see Using Podman for setup instructions.

---

Quick Install Scripts

Linux / WSL macOS Windows

# Azure CLI
curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

# Azure Developer CLI
curl -fsSL https://aka.ms/install-azd.sh | bash

# Python 3.11 (Ubuntu/Debian)
sudo apt update && sudo apt install python3.11 python3.11-venv

# Node.js 22 (via NodeSource)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# jq (JSON processor)
sudo apt install -y jq

# Docker
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

# Using Homebrew
brew install azure-cli
brew install azd
brew install python@3.11
brew install node@22
brew install jq

# Choose one:
brew install --cask docker        # Docker Desktop
brew install podman               # Podman (Docker alternative)

Using Podman on macOS

If using Podman, you'll need to set up Docker compatibility. See Using Podman for detailed setup instructions.

# Using winget
winget install Microsoft.AzureCLI
winget install Microsoft.Azd
winget install Python.Python.3.11
winget install OpenJS.NodeJS.LTS
winget install jqlang.jq
winget install Docker.DockerDesktop

---

Azure Requirements

Subscription Access

You need an Azure subscription with Contributor access.

# Verify your subscription
az login
az account show --query "{Name:name, ID:id, State:state}" -o table

Don't have a subscription?

Create a free account: Azure Free Account

Required Permissions

Permission	Required For
Contributor	Creating resources (OpenAI, ACS, Cosmos DB, etc.)
User Access Administrator	Assigning managed identity roles

Permission Denied Errors?

If you see permission errors during deployment:

1. Contact your Azure administrator
2. Request Contributor + User Access Administrator on your subscription
3. Or request a dedicated resource group with these permissions

---

Verification Checklist

Run this script to verify all prerequisites:

#!/bin/bash
echo "🔍 Checking prerequisites..."

# Check each tool
for cmd in az azd docker python3 node jq; do
  if command -v $cmd &> /dev/null; then
    echo "✅ $cmd: $(command -v $cmd)"
  else
    echo "❌ $cmd: NOT FOUND"
  fi
done

# Check Azure login
if az account show &> /dev/null; then
  echo "✅ Azure CLI: Logged in"
else
  echo "❌ Azure CLI: Not logged in (run 'az login')"
fi

# Check azd auth
if azd auth login --check-status &> /dev/null; then
  echo "✅ Azure Developer CLI: Authenticated"
else
  echo "❌ Azure Developer CLI: Not authenticated (run 'azd auth login')"
fi

echo "🏁 Done!"

---

Next Steps

Once prerequisites are installed:

Goal	Guide
Deploy to Azure (recommended first step)	Quickstart
Run locally (after deployment)	Local Development
Try the demo	Demo Guide

---

Terraform Note

Terraform is automatically installed by azd during deployment. You don't need to install it separately.