Skip to content

first-project.md

Latest commit

 

History

History
503 lines (389 loc) · 14.4 KB

first-project.md

File metadata and controls

503 lines (389 loc) · 14.4 KB
Raw

Your First Project - Hands-On Tutorial

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)
  • ✅ Azure CLI installed and authenticated
  • ✅ Git installed on your system
  • ✅ Node.js 16+ (for this tutorial)
  • ✅ Visual Studio Code (recommended)

Verify Your Setup

# Check azd installation
azd version

Verify Azure 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 logs

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

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 detailed logs
azd logs --service api
azd logs --service web

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: