Container Services Guide

Add databases, caches, and Azure emulators to your development environment with Docker containers managed by azd app.

Overview

azd app supports running Docker containers alongside your application services. This is perfect for local development with databases, caches, message queues, and Azure service emulators without needing to install them directly on your machine.

🐘

Databases

PostgreSQL, MySQL, MongoDB

⚡

Caches

Redis, Memcached

☁️

Azure Emulators

Azurite, Cosmos DB

Quick Start

The fastest way to add a container service is using the azd app add command:

# List available container services
azd app add --list

# Add a service to your project
azd app add azurite

This automatically adds the service to your azure.yaml with optimal defaults for ports, environment variables, and health checks.

Built-in Container Services

azd app includes pre-configured definitions for common services. Use azd app add --list to see all available services.

Service	Image	Ports	Use Case
`azurite`	mcr.microsoft.com/azure-storage/azurite	10000-10002	Azure Blob, Queue, Table storage
`cosmos`	mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator	8081, 10250-10254	Azure Cosmos DB NoSQL
`postgres`	postgres:16	5432	Relational database
`redis`	redis:7-alpine	6379	In-memory cache, sessions

Manual Configuration

You can also manually add container services to your azure.yaml. Any service with an image property is treated as a container service.

Basic Container Service

services:
  api:
    path: ./src/api
    language: node

  postgres:
    host: containerapp
    image: postgres:16
    ports:
      - "5432:5432"

With Environment Variables

services:
  postgres:
    host: containerapp
    image: postgres:16
    ports:
      - "5432:5432"
    env:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: app

With Volume Persistence

services:
  postgres:
    host: containerapp
    image: postgres:16
    ports:
      - "5432:5432"
    env:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: app
    volumes:
      - postgres-data:/var/lib/postgresql/data

With Health Check

services:
  postgres:
    host: containerapp
    image: postgres:16
    ports:
      - "5432:5432"
    env:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

Configuration Options

Property	Type	Required	Description
`image`	string	Yes	Docker image name with optional tag
`ports`	string[]	No	Port mappings in "host:container" format
`env`	map	No	Environment variables for the container
`volumes`	string[]	No	Volume mounts for data persistence
`healthcheck`	object	No	Docker Compose-compatible health check
`command`	string[]	No	Override the container's default command

Health Check Configuration

Health checks help azd app know when a container service is ready to accept connections. The format is compatible with Docker Compose.

Property	Type	Default	Description
`test`	string[]	-	Command to run for health check
`interval`	duration	30s	Time between health checks
`timeout`	duration	30s	Time to wait for health check
`retries`	int	3	Number of retries before unhealthy
`start_period`	duration	0s	Grace period before starting checks

Connection Strings

Use these connection strings in your application services to connect to the container services:

Service	Connection String / URL
`azurite`	`UseDevelopmentStorage=true`
`cosmos`	`AccountEndpoint=https://localhost:8081/;AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==`
`postgres`	`postgresql://postgres:postgres@localhost:5432/app?sslmode=disable`
`redis`	`redis://localhost:6379` or `localhost:6379`

Complete Example

Here's a complete azure.yaml with an API service connected to multiple container services:

services:
  api:
    path: ./src/api
    language: node
    env:
      DATABASE_URL: postgresql://postgres:postgres@localhost:5432/app
      REDIS_URL: redis://localhost:6379
      AZURE_STORAGE_CONNECTION_STRING: UseDevelopmentStorage=true

  postgres:
    host: containerapp
    image: postgres:16
    ports:
      - "5432:5432"
    env:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: app
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    host: containerapp
    image: redis:7-alpine
    ports:
      - "6379:6379"
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

  azurite:
    host: containerapp
    image: mcr.microsoft.com/azure-storage/azurite:latest
    ports:
      - "10000:10000"  # Blob
      - "10001:10001"  # Queue
      - "10002:10002"  # Table

Running Container Services

Container services are managed automatically when you run your project:

# Run all services including containers
azd app run

# Run specific services
azd app run --service api,postgres

# Dry run to see what would start
azd app run --dry-run

How it Works

Container services are started before application services
Health checks are monitored to ensure containers are ready
Logs from containers are streamed to the dashboard
Containers are stopped when you stop the development session
Named volumes persist data between sessions

Requirements

Container services require Docker to be installed and running on your machine. The azd app reqs command will automatically check for Docker when container services are defined in your project.

Docker Desktop (Windows/macOS)
Docker Engine (Linux)