Skip to content

installation.md

Latest commit

 

History

History
450 lines (339 loc) · 11.7 KB

installation.md

File metadata and controls

450 lines (339 loc) · 11.7 KB

Installation & Setup Guide

Chapter Navigation:

Introduction

This comprehensive guide will walk you through installing and configuring Azure Developer CLI (azd) on your system. You'll learn multiple installation methods for different operating systems, authentication setup, and initial configuration to prepare your development environment for Azure deployments.

Learning Goals

By the end of this lesson, you will:

  • Successfully install Azure Developer CLI on your operating system
  • Configure authentication with Azure using multiple methods
  • Set up your development environment with necessary prerequisites
  • Understand different installation options and when to use each
  • Troubleshoot common installation and setup issues

Learning Outcomes

After completing this lesson, you will be able to:

  • Install azd using the appropriate method for your platform
  • Authenticate with Azure using azd auth login
  • Verify your installation and test basic azd commands
  • Configure your development environment for optimal azd usage
  • Resolve common installation problems independently

This guide will help you install and configure Azure Developer CLI on your system, regardless of your operating system or development environment.

Prerequisites

Before installing azd, ensure you have:

  • Azure subscription - Create a free account
  • Azure CLI - For authentication and resource management
  • Git - For cloning templates and version control
  • Docker (optional) - For containerized applications

Installation Methods

Windows

Option 1: Windows Package Manager (Recommended)

winget install microsoft.azd

Option 2: PowerShell Install Script

# Useful when winget is unavailable
powershell -ex AllSigned -c "Invoke-RestMethod 'https://aka.ms/install-azd.ps1' | Invoke-Expression"

Option 3: Chocolatey

choco install azd

Option 4: Manual Installation

  1. Download the latest release from GitHub
  2. Extract to C:\Program Files\azd\
  3. Add to PATH environment variable

macOS

Option 1: Homebrew (Recommended)

brew tap azure/azd
brew install azd

Option 2: Install Script

curl -fsSL https://aka.ms/install-azd.sh | bash

Option 3: Manual Installation

# Download and install
curl -fsSL https://aka.ms/install-azd.sh | bash -s -- --base-url https://github.com/Azure/azure-dev/releases/latest/download --verbose

Linux

Option 1: Install Script (Recommended)

curl -fsSL https://aka.ms/install-azd.sh | bash

Option 2: Package Managers

Manual installation from release assets:

# Download the latest archive for your Linux architecture from:
# https://github.com/Azure/azure-dev/releases
# Then extract it and add the azd binary to your PATH.

GitHub Codespaces

Some Codespaces and dev container environments already include azd, but you should verify that rather than assume it:

azd version

If azd is missing, install it with the standard script for the environment.

Docker

# Run azd in a container
docker run --rm -it -v $(pwd):/workspace mcr.microsoft.com/azure-dev-cli-tools:latest

# Create an alias for easier use
alias azd='docker run --rm -it -v $(pwd):/workspace mcr.microsoft.com/azure-dev-cli-tools:latest azd'

✅ Verify Installation

After installation, verify azd is working correctly:

# Check version
azd version

# View help
azd --help

# List available templates
azd template list

Expected output:

azd version 1.x.x (commit xxxxxx)

Note: The actual version number will vary. Check Azure Developer CLI releases for the latest version.

✅ Installation Success Checklist:

  • azd version shows version number without errors
  • azd --help displays command documentation
  • azd template list shows available templates
  • You can create a test directory and run azd init successfully

If all checks pass, you're ready to proceed to Your First Project!

Authentication Setup

Recommended Beginner Setup

For AZD-first workflows, sign in with azd auth login.

# Required for AZD commands such as azd up
azd auth login

# Verify AZD authentication status
azd auth login --check-status

Use Azure CLI sign-in only when you plan to run az commands yourself during the course.

Azure CLI Authentication (Optional)

# Install Azure CLI if not already installed
# Windows: winget install Microsoft.AzureCLI
# macOS: brew install azure-cli
# Linux: see the Azure CLI install docs for your distribution

# Login to Azure
az login

# Verify authentication
az account show

Which Sign-In Flow Should You Use?

  • Use azd auth login if you are following the beginner AZD path and mainly running azd commands.
  • Use az login as well when you want to run Azure CLI commands such as az account show or inspect resources directly.
  • If an exercise includes both azd and az commands, run both sign-in commands once at the start.

Device Code Authentication

If you're on a headless system or having browser issues:

azd auth login --use-device-code

Service Principal (CI/CD)

For automated environments:

azd auth login \
  --client-id <client-id> \
  --client-secret <client-secret> \
  --tenant-id <tenant-id>

Validate Your Complete Setup

If you want a quick readiness check before starting Chapter 1:

Windows:

.\validate-setup.ps1

macOS / Linux:

bash ./validate-setup.sh

Configuration

Global Configuration

# Set default subscription
azd config set defaults.subscription <subscription-id>

# Set default location
azd config set defaults.location eastus2

# View all configuration
azd config show

Environment Variables

Add to your shell profile (.bashrc, .zshrc, .profile):

# Azure configuration
export AZURE_SUBSCRIPTION_ID="your-subscription-id"
export AZURE_LOCATION="eastus2"

# azd configuration
export AZD_ALPHA_ENABLE_APPSERVICE_REMOTE_DEBUGGING=true
export AZD_DEBUG=true  # Enable debug logging

IDE Integration

Visual Studio Code

Install the Azure Developer CLI extension:

  1. Open VS Code
  2. Go to Extensions (Ctrl+Shift+X)
  3. Search for "Azure Developer CLI"
  4. Install the extension

Features:

  • IntelliSense for azure.yaml
  • Integrated terminal commands
  • Template browsing
  • Deployment monitoring

GitHub Codespaces

Create a .devcontainer/devcontainer.json:

{
  "name": "Azure Developer CLI",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "features": {
    "ghcr.io/azure/azure-dev/azd:latest": {}
  },
  "postCreateCommand": "azd version"
}

IntelliJ/JetBrains

  1. Install the Azure plugin
  2. Configure Azure credentials
  3. Use integrated terminal for azd commands

🐛 Troubleshooting Installation

Common Issues

Permission Denied (Windows)

# Run PowerShell as Administrator
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

PATH Issues

Manually add azd to your PATH:

Windows:

setx PATH "%PATH%;C:\Program Files\azd\"

macOS/Linux:

echo 'export PATH=$PATH:/usr/local/bin' >> ~/.bashrc
source ~/.bashrc

Network/Proxy Issues

# Configure proxy
azd config set http.proxy http://proxy:8080
azd config set https.proxy https://proxy:8080

# Skip SSL verification (not recommended for production)
azd config set http.insecure true

Version Conflicts

# Remove old installations
# Windows: winget uninstall microsoft.azd
# macOS: brew uninstall azd
# Linux: remove the previous azd binary or symlink before reinstalling

# Clean configuration
rm -rf ~/.azd

Getting More Help

# Enable debug logging
export AZD_DEBUG=true
azd <command> --debug

# View current configuration
azd config show

# View current deployment status
azd show

Updating azd

Update Check

azd warns when a newer release is available, and you can confirm your current build with:

azd version

Manual Updates

Windows (winget):

winget upgrade microsoft.azd

macOS (Homebrew):

brew upgrade azd

Linux:

curl -fsSL https://aka.ms/install-azd.sh | bash

💡 Frequently Asked Questions

What's the difference between azd and az CLI?

Azure CLI (az): Low-level tool for managing individual Azure resources

  • az webapp create, az storage account create
  • One resource at a time
  • Infrastructure management focus

Azure Developer CLI (azd): High-level tool for complete application deployments

  • azd up deploys entire app with all resources
  • Template-based workflows
  • Developer productivity focus

You need both: azd uses az CLI for authentication

Can I use azd with existing Azure resources?

Yes! You can:

  1. Import existing resources into azd environments
  2. Reference existing resources in your Bicep templates
  3. Use azd for new deployments alongside existing infrastructure

See Configuration Guide for details.

Does azd work with Azure Government or Azure China?

Yes, configure the cloud:

# Azure Government
az cloud set --name AzureUSGovernment
az login

# Azure China
az cloud set --name AzureChinaCloud
az login
Can I use azd in CI/CD pipelines?

Absolutely! azd is designed for automation:

  • GitHub Actions integration
  • Azure DevOps support
  • Service principal authentication
  • Non-interactive mode

See Deployment Guide for CI/CD patterns.

What's the cost of using azd?

azd itself is completely free and open-source. You only pay for:

  • Azure resources you deploy
  • Azure consumption costs (compute, storage, etc.)

Use azd provision --preview to estimate costs before deployment.

Next Steps

  1. Complete authentication: Ensure you can access your Azure subscription
  2. Try your first deployment: Follow the First Project Guide
  3. Explore templates: Browse available templates with azd template list
  4. Configure your IDE: Set up your development environment

Support

If you encounter issues:

Chapter Navigation:

✅ Installation Complete! Continue to Your First Project to start building with azd.