This is a simple guide that will help you set up and run the Azure Storage Emulator on your local machine. The Azure Storage Emulator allows you to develop and test your applications that use Azure Storage services without needing an Azure subscription or an Internet connection.

Review the Documentation for more details on how to use the emulator and its features. This document covers a scenario where you want to run the emulator as close to the real Azure Storage service as possible, which means using triple HTTPS endpoints and OAuth simulation.

Installation

You can install and use the emulator in a few different ways, depending on your preferences and environment. The recommended way is to use a container runtime or Kubernetes, but you can also install it natively using Node.js.

Using a container runtime

To run the Azure Storage Emulator in a container, follow these steps:

Ensure that a container runtime is installed. This repository supports both Docker and Apple container command.
Build the emulator image using the provided Dockerfile:
```
./build.sh
```
Run the emulator container:
```
./start-azurite
```

You can also use the included example compose.yaml file for running it using docker compose (or any other compose compatible CLI).

Using Kubernetes

Use the example manifest azurite-deployment.yaml.

Create the required Secret from your local env file:

kubectl create secret generic azurite-accounts \
  --from-env-file="$HOME/.azurite/accounts.env"

Deploy the manifest:

kubectl apply -f azurite-deployment.yaml

Get the Kubernetes Service external IP:

kubectl get svc azurite -o jsonpath='{.status.loadBalancer.ingress[0].ip}'

Add /etc/hosts entries on your workstation and point all Azurite account FQDNs to that Service IP (not 127.0.0.1):

<service_ip> <accountname>.blob.core.windows.net <accountname>.queue.core.windows.net <accountname>.table.core.windows.net

Using Node.js

To install the Azure Storage Emulator natively on your machine, ensure you have Node.js (with npm) and Caddy HTTP Server installed, and follow these steps:

Clone the repository:

git clone https://github.com/azure/azurite

Navigate to the cloned directory:
```
cd azurite
```
Build the emulator package.
```
npm ci
npm run build
npm pack
```
Install the package globally using npm:
```
npm install -g azurite-*.tgz
```
Remove the clone directory, it will not be needed anymore:
```
cd ..
rm -rf azurite
```
Create an accounts.env file in the same directory as the run-server.sh script with the following content:
```
AZURITE_ACCOUNTS=accountname:accountkey
```
Replace accountname with the desired account name. Use OpenSSL to generate an account key.
```
openssl rand -base64 32
```
You can also generate a deterministic account key using any string as a seed:
```
echo -n "your-seed-string" | base64
```

Add the following line to your /etc/hosts file to map the custom domain names to localhost:

127.0.0.1 <accountname>.blob.core.windows.net <accountname>.queue.core.windows.net <accountname>.table.core.windows.net

Run the server:
```
./run-server.sh
```
You can add the --oauth or -o flag to simulate OAuth authentication.
```
./run-server.sh --oauth
```

Accessing the blob storage

RClone

RClone is a command-line program to manage files on cloud storage. You can use it to interact with the Azure Storage Emulator the same way you would with the real Azure Storage service. Edit the rclone.conf file and add the following configuration:

[azurite]
type = azureblob
account = accountname
key = accountkey

or, if you want to use simulated OAuth authentication:

[azurite]
type = azureblob
account = accountname
env_auth = true

Now, you can use rclone commands to interact with the emulator. For example, to list the containers in the blob service:

rclone ls azurite:

Note

: On modern Linux distributions and MacOS systems the rclone.conf file is typically located at ~/.config/rclone/rclone.conf.

Terraform

Use the following Terraform Azure RM backend configuration to use the Azure Storage Emulator as the backend for storing Terraform state:

terraform {
  backend "azurerm" {
    storage_account_name = "accountname"
    container_name       = "tfstate"
    key                  = "terraform.tfstate"
  }
}

and initialize the module:

terraform init -backend-config=access_key=__base64_encoded_account_key__

Note

: Be aware that AI Agents may generate or suggest using the endpoint parameter, which will not work. You have to create fake account FQDNs in your /etc/hosts file as described in the installation steps.

You can use OAuth simulation with Terraform by adding the use_azuread_auth parameter to the backend configuration:

terraform {
  backend "azurerm" {
    storage_account_name = "accountname"
    container_name       = "tfstate"
    key                  = "terraform.tfstate"
    use_azuread_auth     = true
  }
}

Command Reference

`run-server.sh`

The script is the entry point for starting the Azure Storage Emulator natively. It discovers the account name and key from the accounts.env file, generates the necessary SSL certificates, configures Caddy for HTTPS endpoints, and starts the Azurite server with the appropriate settings.

It accepts the following optional flag: --oauth or -o. It enables OAuth simulation for the emulator. When this flag is set, the emulator simulates OAuth authentication flows, allowing you to test scenarios that involve Entra ID authentication. It does not implement a real authentication flow; instead, it accepts any valid token.

The script assumes that both Azurite and Caddy are installed and available in the system's PATH. It also assumes that the accounts.env file is properly configured with at least one account name and key, and that the /etc/hosts file contains the necessary entries for the custom domain names, e.g. accountname.blob.core.windows.net, accountname.queue.core.windows.net, and accountname.table.core.windows.net.

The storage location is determined by the AZURITE_DIR environment variable, which defaults to the relative storage subdirectory of the current directory if not set. Ensure that the specified directory is writable by the user running the script, as Azurite will need to create and manage files for the emulated storage accounts.

The script will generate self-signed SSL certificates for the specified account name and store them in the storage directory. Caddy will be configured to use these certificates for the HTTPS endpoints. The emulator will be accessible at the following endpoints:

Blob service: https://accountname.blob.core.windows.net
Queue service: https://accountname.queue.core.windows.net
Table service: https://accountname.table.core.windows.net

You need to add storage/ca_cert.pem as a trusted root certificate in your system to avoid SSL errors when connecting to the emulator.

For Linux-based systems, you can use the following commands to add the certificate to the trusted store:

sudo cp storage/ca_cert.pem /usr/local/share/ca-certificates/azurite_ca_cert.crt
sudo update-ca-certificates

For macOS, you can use the Keychain Access application to import the certificate and mark it as trusted. Windows users can use the Certificate Manager to import the certificate into the "Trusted Root Certification Authorities" store.

`build.sh`

The script builds a container image for the Azure Storage Emulator using the provided Dockerfile. The image includes the Azurite server and Caddy HTTP server, configured to run the emulator with triple HTTPS endpoints and optional OAuth simulation. It does not require Azurite or Caddy to be installed on the host machine, as they are included in the container image.

Accepted flags:

--arch: Specifies the target architecture for the container image. Supported values are amd64 and arm64. If not provided, the script will build for the architecture of the host machine. It can be specified twice to build for both architectures.
--version: Specifies the version tag for the built container image. The version value must correspond to a valid Azurite GitHub tag.
--latest: Uses the latest released version of Azurite from GitHub as the base for the container image. This flag cannot be used together with --version.
--registry: Specifies the container registry to which the built image will be pushed. If not provided, the image will only be built locally and not tagged with registry prefix.

`start-azurite`

The script runs the Azure Storage Emulator using a supported container runtime (Docker or Apple container command). It accepts the same flag as run-server.sh to enable OAuth simulation (--oauth or -o). It also assumes AZURITE_DIR is either set in the environment or empty (not set), in which case it will default to the ./storage subdirectory of the current directory. The script mounts the specified storage directory into the container, allowing you to persist data and access the generated SSL certificates on the host machine.

The default image name is azurite:latest, but it can be overridden by setting the AZURITE_IMAGE environment variable before running the script. For example:

AZURITE_IMAGE=myregistry/azurite:latest ./start-azurite

Both AZURITE_DIR and AZURITE_IMAGE should be set in the shell profile if you are running the emulator as a local Azure Storage replacement for development purposes.

Remember: Make backups of the storage directory when the container is not running.

You have to use the same procedure as for run-server.sh to install the generated CA certificate as a trusted root certificate in your system to avoid SSL errors when connecting to the emulator.