slawek/azure-storage-emulator
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: update storage directory variable in run.sh for consistency

Browse Source
This commit is contained in:
Sławek Koszewski
2026-02-28 11:15:21 +01:00
parent aa9274aca3
commit 050986ff87
2 changed files with 56 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

55
README.md
View File

@@ -1,10 +1,9 @@
# 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 actual Azure subscription nor Internet connection.
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 nor Internet connection.
Review the [Documentation](#reference) for more details on how to use the emulator and its features. This document will cover 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:
@@ -97,6 +96,58 @@ To install the Azure Storage Emulator natively on your machine, follow these ste
./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 will simulate OAuth authentication flows, allowing you to test scenarios that involve Entra ID authentication. It does not implement a real authentication flow, instead it will accept 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 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 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. Can be specfied 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.
### `run.sh`
The script runs the Azure Storage Emulator using 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 the AZURITE_DIR is either set in the environment or empty (not set) in which case it will default to `./storage` subdirectory of the current directory. The script will mount the specified storage directory into the container, allowing you to persist data and access the generated SSL certificates on the host machine.
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.
## Using Let's Encrypt Certificates
> **Note:** This procedure is work in progress and not yet fully documented.
By default, the emulator generates self-signed certificates for the HTTPS endpoints. If you want to use real certificates from Let's Encrypt, you will have to deploy a real Azure Storage Account and use it to complete the HTTP-01 challenge for the desired domain name. You won't be able to use table and queue services because you will not be able to complete the challenge for the corresponding endpoints.
## Reference
- [Azure Storage Emulator GitHub Repository](https://github.com/azure/azurite)