# Azure Storage Emulator

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](#reference) 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.

## Docker Installation

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

1. Ensure that a container runtime is installed. This repository supports both Docker and Apple `container` command.

2. Build the emulator image using the provided Dockerfile:

   ```bash
   ./build.sh
   ```

3. Run the emulator container:

   ```bash
   ./start-azurite
   ```

## Native Installation

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

1. Clone the repository:

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

2. Navigate to the cloned directory:

   ```bash
   cd azurite
   ```

3. Build the emulator package.

   ```bash
   npm ci
   npm run build
   npm pack
   ```

4. Install the package globally using npm:

   ```bash
   npm install -g azurite-*.tgz
   ```

5. Remove the clone directory, it will not be needed anymore:

   ```bash
   cd ..
   rm -rf azurite
   ```

6. Install the Caddy HTTP server.

7. Create an `accounts.env` file in the same directory as the `run-server.sh` script with the following content:

   ```bash
   AZURITE_ACCOUNTS=accountname:accountkey
   ```

   Replace `accountname` with the desired account name. Use OpenSSL to generate an account key.

   ```bash
   openssl rand -base64 32
   ```

   You can also generate a deterministic account key using any string as a seed:

   ```bash
   echo -n "your-seed-string" | base64
   ```

8. 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
   ```

9. Run the server:

   ```bash
   ./run-server.sh
   ```

   You can add the `--oauth` or `-o` flag to simulate OAuth authentication.

   ```bash
   ./run-server.sh --oauth
   ```

## 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:

```bash
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:

```bash
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.

## Reference

- [Azure Storage Emulator GitHub Repository](https://github.com/azure/azurite)
- [Azure Storage Emulator Documentation](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite)
- [Caddy Server](https://caddyserver.com)