Skip to content

LOCALSTACK.md

Latest commit

 

History

History
166 lines (127 loc) · 4.22 KB

LOCALSTACK.md

File metadata and controls

166 lines (127 loc) · 4.22 KB
Raw

LocalStack for Azure Quick Start

Overview

You can emulate selected Azure services locally using the LocalStack Azure Docker image. Before you begin, you must export a valid LOCALSTACK_AUTH_TOKEN, which unlocks Azure emulation features.
Refer to the LocalStack Auth Token documentation (e.g. the Auth Token guide) to obtain your token and set it as an environment variable.

Prerequisites

  • Docker installed and running
  • (Recommended) Docker Compose (v2+)
  • LocalStack account with a valid authentication token
  • Sufficient disk space for the LocalStack persistent volume

1. Pull the Azure Image

docker pull localstack/localstack-azure

2. Choose a Startup Method

You can start the Azure emulator using one of the following methods:

  • lstk CLI
  • Raw docker run
  • Docker Compose

Option A: lstk CLI

Make sure the lstk CLI is installed (brew install localstack/tap/lstk or npm install -g @localstack/lstk).

# Set the authentication token
export LOCALSTACK_AUTH_TOKEN=<your_auth_token>

# Start the LocalStack Azure emulator
lstk start --type azure

# Route all Azure CLI calls to the LocalStack Azure emulator
lstk az start-interception

This:

  • Exports your auth token
  • Starts the LocalStack Azure emulator (--type azure) and waits until it is ready
  • Routes all Azure CLI calls to the emulator

To stop:

lstk stop

Option B: Docker CLI

Run the container directly:

docker run \
  --rm -it \
  -p 4566:4566 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.localstack/volume:/var/lib/localstack \
  -e LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?} \
  localstack/localstack-azure

Notes:

  • -p 4566:4566 exposes the LocalStack edge port
  • Mounting the Docker socket enables starting sidecar containers if needed
  • The ~/.localstack/volume mount persists state across restarts
  • The :? syntax in ${LOCALSTACK_AUTH_TOKEN:?} fails fast if the variable is unset

Option C: Docker Compose

Create a docker-compose.yml:

version: "3.8"

services:
  localstack:
    container_name: localstack-main
    image: localstack/localstack-azure
    ports:
      - "127.0.0.1:4566:4566"
    environment:
      - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?}
    volumes:
      - "./volume:/var/lib/localstack"

Start the service:

docker compose up

(Or with legacy syntax: docker-compose up)

To run detached:

docker compose up -d

Stop and remove:

docker compose down

3. Verify the Emulator

After startup, you can:

  • Check logs: lstk logs --follow, or docker logs -f localstack-main with Docker Compose
  • Curl the edge endpoint: 
    curl -s localhost:4566/_localstack/health | jq

4. Environment Variable Recap

Set the auth token once per shell session:

export LOCALSTACK_AUTH_TOKEN=<your_auth_token>

For shells like Fish:

set -x LOCALSTACK_AUTH_TOKEN <your_auth_token>

For PowerShell:

$Env:LOCALSTACK_AUTH_TOKEN = "<your_auth_token>"

5. Cleanup

  • Stop containers (lstk stop, docker stop <id>, or docker compose down)
  • Remove persisted state if needed: 
    rm -rf ~/.localstack/volume
# or for compose:
rm -rf ./volume

Troubleshooting

Issue Suggestion
Auth error Confirm token validity & export
Port already in use Change mapping (e.g. -p 4567:4566)
State not persisting Verify volume mount path
lstk starts another emulator Start it with lstk start --type azure

Next Steps

  • Explore available Azure service endpoints through the LocalStack documentation
  • Script integration tests against http://localhost:4566
  • Combine with Terraform / SDK clients pointing to the LocalStack endpoint
  • Proxy the Azure CLI to the emulator with lstk az, or run lstk az start-interception to intercept all az calls (see the lstk GitHub repository)