Your First Project - Hands-On Tutorial

March 27, 2026 · View on GitHub

Chapter Navigation:

Introduction

Welcome to your first Azure Developer CLI project! This comprehensive hands-on tutorial provides a complete walkthrough of creating, deploying, and managing a full-stack application on Azure using azd. You'll work with a real todo application that includes a React frontend, Node.js API backend, and MongoDB database.

Learning Goals

By completing this tutorial, you will:

  • Master the azd project initialization workflow using templates
  • Understand Azure Developer CLI project structure and configuration files
  • Execute complete application deployment to Azure with infrastructure provisioning
  • Implement application updates and redeployment strategies
  • Manage multiple environments for development and staging
  • Apply resource cleanup and cost management practices

Learning Outcomes

Upon completion, you will be able to:

  • Initialize and configure azd projects from templates independently
  • Navigate and modify azd project structures effectively
  • Deploy full-stack applications to Azure using single commands
  • Troubleshoot common deployment issues and authentication problems
  • Manage multiple Azure environments for different deployment stages
  • Implement continuous deployment workflows for application updates

Getting Started

Prerequisites Checklist

  • ✅ Azure Developer CLI installed (Installation Guide)
  • ✅ AZD authentication completed with azd auth login
  • ✅ Git installed on your system
  • ✅ Node.js 16+ (for this tutorial)
  • ✅ Visual Studio Code (recommended)

Before you continue, run the setup validator from the repository root:

Windows: ./validate-setup.ps1

macOS / Linux: bash ./validate-setup.sh

Verify Your Setup

# Check azd installation
azd version

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

Verify optional Azure CLI authentication

az account show

Check Node.js version

node --version

Step 1: Choose and Initialize a Template

Let's start with a popular todo application template that includes a React frontend and Node.js API backend.

# Browse available templates
azd template list

# Initialize the todo app template
mkdir my-first-azd-app
cd my-first-azd-app
azd init --template todo-nodejs-mongo

# Follow the prompts:
# - Enter an environment name: "dev"
# - Choose a subscription (if you have multiple)
# - Choose a region: "East US 2" (or your preferred region)

What Just Happened?

  • Downloaded the template code to your local directory
  • Created an azure.yaml file with service definitions
  • Set up infrastructure code in the infra/ directory
  • Created an environment configuration

Step 2: Explore the Project Structure

Let's examine what azd created for us:

# View the project structure
tree /f   # Windows
# or
find . -type f | head -20   # macOS/Linux

You should see:

my-first-azd-app/
├── .azd/
│   └── config.json              # Project configuration
├── .azure/
│   └── dev/                     # Environment-specific files
├── .devcontainer/               # Development container config
├── .github/workflows/           # GitHub Actions CI/CD
├── .vscode/                     # VS Code settings
├── infra/                       # Infrastructure as code (Bicep)
│   ├── main.bicep              # Main infrastructure template
│   ├── main.parameters.json     # Parameters for deployment
│   └── modules/                # Reusable infrastructure modules
├── src/
│   ├── api/                    # Node.js backend API
│   │   ├── src/               # API source code
│   │   ├── package.json       # Node.js dependencies
│   │   └── Dockerfile         # Container configuration
│   └── web/                   # React frontend
│       ├── src/               # React source code
│       ├── package.json       # React dependencies
│       └── Dockerfile         # Container configuration
├── azure.yaml                  # azd project configuration
└── README.md                   # Project documentation

Key Files to Understand

azure.yaml - The heart of your azd project:

# View the project configuration
cat azure.yaml

infra/main.bicep - Infrastructure definition:

# View the infrastructure code
head -30 infra/main.bicep

Step 3: Customize Your Project (Optional)

Before deploying, you can customize the application:

Modify the Frontend

# Open the React app component
code src/web/src/App.tsx

Make a simple change:

// Find the title and change it
<h1>My Awesome Todo App</h1>

Configure Environment Variables

# Set custom environment variables
azd env set WEBSITE_TITLE "My First AZD App"
azd env set API_VERSION "v1.18"
# View all environment variables
azd env get-values

Step 4: Deploy to Azure

Now for the exciting part - deploy everything to Azure!

# Deploy infrastructure and application
azd up

# This command will:
# 1. Provision Azure resources (App Service, Cosmos DB, etc.)
# 2. Build your application
# 3. Deploy to the provisioned resources
# 4. Display the application URL

What's Happening During Deployment?

The azd up command performs these steps:

  1. Provision (azd provision) - Creates Azure resources
  2. Package - Builds your application code
  3. Deploy (azd deploy) - Deploys code to Azure resources

Expected Output

Packaging services (azd package)

SUCCESS: Your up workflow to provision and deploy to Azure completed in 4 minutes 32 seconds.

You can view the resources created under the resource group rg-my-first-azd-app-dev in the Azure portal:
https://portal.azure.com/#@/resource/subscriptions/{subscription-id}/resourceGroups/rg-my-first-azd-app-dev

Navigate to the Todo app at:
https://app-web-abc123def.azurewebsites.net

Step 5: Test Your Application

Access Your Application

Click on the URL provided in the deployment output, or get it anytime:

# Get application endpoints
azd show

# Open the application in your browser
azd show --output json | jq -r '.services.web.endpoint'

Test the Todo App

  1. Add a todo item - Click "Add Todo" and enter a task
  2. Mark as complete - Check off completed items
  3. Delete items - Remove todos you no longer need

Monitor Your Application

# Open Azure portal for your resources
azd monitor

# View application logs
azd monitor --logs

# View live metrics
azd monitor --live

Step 6: Make Changes and Redeploy

Let's make a change and see how easy it is to update:

Modify the API

# Edit the API code
code src/api/src/routes/lists.js

Add a custom response header:

// Find a route handler and add:
res.header('X-Powered-By', 'Azure Developer CLI');

Deploy Just the Code Changes

# Deploy only the application code (skip infrastructure)
azd deploy

# This is much faster than 'azd up' since infrastructure already exists

Step 7: Manage Multiple Environments

Create a staging environment to test changes before production:

# Create a new staging environment
azd env new staging

# Deploy to staging
azd up

# Switch back to dev environment
azd env select dev

# List all environments
azd env list

Environment Comparison

# View dev environment
azd env select dev
azd show

# View staging environment  
azd env select staging
azd show

Step 8: Clean Up Resources

When you're done experimenting, clean up to avoid ongoing charges:

# Delete all Azure resources for current environment
azd down

# Force delete without confirmation and purge soft-deleted resources
azd down --force --purge

# Delete specific environment
azd env select staging
azd down --force --purge

Classic App vs. AI-Powered App: Same Workflow

You just deployed a traditional web application. But what if you wanted to deploy an AI-powered app instead—say, a chat application backed by Microsoft Foundry Models?

The good news: the workflow is identical.

StepClassic Todo AppAI Chat App
Initializeazd init --template todo-nodejs-mongoazd init --template azure-search-openai-demo
Authenticateazd auth loginazd auth login
Deployazd upazd up
Monitorazd monitorazd monitor
Clean upazd down --force --purgeazd down --force --purge

The only difference is the template you start from. An AI template includes additional infrastructure (like an Microsoft Foundry Models resource or an AI Search index), but azd handles all of that for you. You don't need to learn new commands, adopt a different tool, or change how you think about deployment.

This is the core principle of azd: one workflow, any workload. The skills you practiced in this tutorial—initializing, deploying, monitoring, redeploying, and cleaning up—apply equally to AI applications and agents.

What You've Learned

Congratulations! You've successfully:

  • ✅ Initialized an azd project from a template
  • ✅ Explored the project structure and key files
  • ✅ Deployed a full-stack application to Azure
  • ✅ Made code changes and redeployed
  • ✅ Managed multiple environments
  • ✅ Cleaned up resources

🎯 Skill Validation Exercises

Exercise 1: Deploy a Different Template (15 minutes)

Goal: Demonstrate mastery of azd init and deployment workflow

# Try Python + MongoDB stack
mkdir todo-python && cd todo-python
azd init --template todo-python-mongo
azd up

# Verify deployment
azd show
curl $(azd show --output json | jq -r '.services.web.endpoint')

# Clean up
azd down --force --purge

Success Criteria:

  • Application deploys without errors
  • Can access application URL in browser
  • Application functions correctly (add/remove todos)
  • Successfully cleaned up all resources

Exercise 2: Customize Configuration (20 minutes)

Goal: Practice environment variable configuration

cd my-first-azd-app

# Create custom environment
azd env new custom-config

# Set custom variables
azd env set APP_TITLE "My Custom Todo App"
azd env set API_VERSION "2.0.0"
azd env set ENABLE_DEBUG "true"

# Verify variables
azd env get-values | grep APP_TITLE

# Deploy with custom config
azd up

Success Criteria:

  • Custom environment created successfully
  • Environment variables set and retrievable
  • Application deploys with custom configuration
  • Can verify custom settings in deployed app

Exercise 3: Multi-Environment Workflow (25 minutes)

Goal: Master environment management and deployment strategies

# Create dev environment
azd env new dev-$(whoami)
azd env set ENVIRONMENT_TYPE dev
azd env set LOG_LEVEL debug
azd up

# Note dev URL
DEV_URL=$(azd show --output json | jq -r '.services.web.endpoint')
echo "Dev: $DEV_URL"

# Create staging environment
azd env new staging-$(whoami)
azd env set ENVIRONMENT_TYPE staging
azd env set LOG_LEVEL info
azd up

# Note staging URL
STAGING_URL=$(azd show --output json | jq -r '.services.web.endpoint')
echo "Staging: $STAGING_URL"

# Compare environments
azd env list

# Test both environments
curl "$DEV_URL/health"
curl "$STAGING_URL/health"

# Clean up both
azd env select dev-$(whoami) && azd down --force --purge
azd env select staging-$(whoami) && azd down --force --purge

Success Criteria:

  • Two environments created with different configurations
  • Both environments deployed successfully
  • Can switch between environments using azd env select
  • Environment variables differ between environments
  • Successfully cleaned up both environments

📊 Your Progress

Time Invested: ~60-90 minutes
Skills Acquired:

  • ✅ Template-based project initialization
  • ✅ Azure resource provisioning
  • ✅ Application deployment workflows
  • ✅ Environment management
  • ✅ Configuration management
  • ✅ Resource cleanup and cost management

Next Level: You're ready for Configuration Guide to learn advanced configuration patterns!

Troubleshooting Common Issues

Authentication Errors

# Re-authenticate with Azure
az login

# Verify subscription access
az account show

Deployment Failures

# Enable debug logging
export AZD_DEBUG=true
azd up --debug

# View application logs in Azure
azd monitor --logs

# For Container Apps, use Azure CLI:
# az containerapp logs show --name <app-name> --resource-group <rg-name> --follow

Resource Name Conflicts

# Use a unique environment name
azd env new dev-$(whoami)-$(date +%s)

Port/Network Issues

# Check if ports are available
netstat -an | grep :3000
netstat -an | grep :3100

Next Steps

Now that you've completed your first project, explore these advanced topics:

1. Customize Infrastructure

2. Set Up CI/CD

3. Production Best Practices

4. Explore More Templates

# Browse templates by category
azd template list --filter web
azd template list --filter api
azd template list --filter database

# Try different technology stacks
azd init --template todo-python-mongo
azd init --template todo-csharp-sql
azd init --template todo-java-mongo

Additional Resources

Learning Materials

Community & Support

Templates & Examples

Congratulations on completing your first azd project! You're now ready to build and deploy amazing applications on Azure with confidence.

Chapter Navigation: