Skip to content

installation.md

Latest commit

 

History

History
419 lines (320 loc) · 11 KB

installation.md

File metadata and controls

419 lines (320 loc) · 11 KB
Raw

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: PowerShell (Recommended)

# Run as Administrator or with elevated privileges
powershell -ex AllSigned -c "Invoke-RestMethod 'https://aka.ms/install-azd.ps1' | Invoke-Expression"

Option 2: Windows Package Manager (winget)

winget install Microsoft.Azd

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

Ubuntu/Debian:

# Add Microsoft package repository
curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

# Install azd
sudo apt-get update
sudo apt-get install azd

RHEL/CentOS/Fedora:

# Add Microsoft package repository
sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc
sudo dnf config-manager --add-repo https://packages.microsoft.com/yumrepos/azure-cli
sudo dnf install azd

GitHub Codespaces

azd comes pre-installed in GitHub Codespaces. Simply create a codespace and start using azd immediately.

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.5.0 (commit abc123)

✅ Installation Success Checklist:

  • azd version shows version number without errors
  • azd --help displays command documentation
  • azd template list shows available templates
  • az account show displays your Azure subscription
  • 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

Azure CLI Authentication (Recommended)

# Install Azure CLI if not already installed
# Windows: winget install Microsoft.AzureCLI
# macOS: brew install azure-cli
# Linux: curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

# Login to Azure
az login

# Verify authentication
az account show

Device Code Authentication

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

az login --use-device-code

Service Principal (CI/CD)

For automated environments:

az login --service-principal \
  --username <client-id> \
  --password <client-secret> \
  --tenant <tenant-id>

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 list

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: sudo apt remove azd

# Clean configuration
rm -rf ~/.azd

Getting More Help

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

# View detailed logs
azd logs

# Check system info
azd info

Updating azd

Automatic Updates

azd will notify you when updates are available:

azd version --check-for-updates

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.