Skip to content

Installation

Prerequisites

To run miniblue (basic):

  • Docker or Go 1.26+ (for building from source)
  • That's it. No Azure account, no credentials, no config.

For real backends (optional):

Feature Requires Env var
Real PostgreSQL databases PostgreSQL server (or Docker) POSTGRES_URL=postgres://user:pass@host:5432/db?sslmode=disable
Real Redis connectivity Redis server (or Docker) REDIS_URL=redis://host:6379
Real Docker containers (ACI) Docker daemon running Docker socket available at /var/run/docker.sock
Persistent storage (Postgres) PostgreSQL server DATABASE_URL=postgres://...
Persistent storage (file) Nothing extra PERSISTENCE=1

For Terraform:

  • Terraform 1.5+
  • Trust the self-signed cert: sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ~/.miniblue/cert.pem (macOS, one-time)

For Pulumi:

  • Pulumi CLI
  • Python 3.9+ with requests package

Homebrew (macOS / Linux)

brew tap moabukar/tap
brew install miniblue

This installs both miniblue (server) and azlocal (CLI).

Pull and run with a single command:

docker run -p 4566:4566 -p 4567:4567 moabukar/miniblue:latest

docker run -p 4566:4566 -p 4567:4567 ghcr.io/moabukar/miniblue:latest

Verify it is running:

curl http://localhost:4566/health

{
  "services": ["subscriptions","tenants","resourcegroups","blob","table","queue","keyvault","cosmosdb","servicebus","functions","network","dns","acr","eventgrid","appconfig","identity"],
  "status": "running",
  "version": "0.2.5"
}

Binary

From source (Go 1.26+)

git clone https://github.com/moabukar/miniblue.git
cd miniblue
make build

This produces two binaries in bin/:

Binary Purpose
bin/miniblue The emulator server
bin/azlocal CLI client (like awslocal for LocalStack)

Start the server:

./bin/miniblue

Install azlocal globally

sudo make install

This copies azlocal to /usr/local/bin/azlocal.

go install

go install github.com/moabukar/miniblue/cmd/miniblue@latest
go install github.com/moabukar/miniblue/cmd/azlocal@latest

Build from source

Requirements:

  • Go 1.26 or later
  • Make (optional)
git clone https://github.com/moabukar/miniblue.git
cd miniblue
go build -o bin/miniblue ./cmd/miniblue
go build -o bin/azlocal ./cmd/azlocal
./bin/miniblue

Docker image size

The miniblue Docker image is ~15MB (Alpine-based, statically compiled Go binary). Compare that to Azurite (~300MB) or LocalStack (~1GB).

Verifying the installation

Regardless of install method, confirm everything works:

# Server health
curl http://localhost:4566/health

# Create a resource group
curl -X PUT "http://localhost:4566/subscriptions/sub1/resourcegroups/test-rg?api-version=2020-06-01" \
  -H "Content-Type: application/json" \
  -d '{"location": "eastus"}'

# Clean up
curl -X DELETE "http://localhost:4566/subscriptions/sub1/resourcegroups/test-rg?api-version=2020-06-01"

Next steps