Cosmos DB Emulator is great for developing against Azure Cosmos DB in your local environment. If you want to run the emulator on Mac/Linux though, the emulator is now in preview mode at the time of writing this and uses Docker to make it available.
Recently I wanted to setup Cosmos DB Emulator on Mac, but I did not want to set it up such that I keep it running always on my Mac. Instead, I decided to use my Synology NAS to host the emulator directly on my NAS as it is built on Linux and also because it allows the emulator running and available for me all the time.
In this post we will see how to set it up on Synology NAS.
The goal is to run Cosmos DB emulator as a Docker container on Synology.
Enabling SSH on Synology
Since Cosmos DB Emulator image is hosted on Microsoft Registry (
mcr.microsoft.com) which does not provide UI/discovery service, Synology’s Docker app, cannot pull images from Microsoft Registry. For this purpose we need to enable SSH on Synology so that we can SSH to Synology and run docker commands directly.
If you have firewall enabled on Synology, you must also
Pulling the docker image
After enabling SSH on SYnology, you can SSH on to Synology and run the below command to pull the Docker image of Cosmos Emulator.
sudo docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator
You should see Cosmos DB Emulator image available in Syonology’s Docker app.
Starting the Container
You can now create a container using the docker image you just pulled. Before we start, as per the Microsoft documentation for the Emulator, we need to ensure we have setup few environment variables for the container. They are
AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE = <<SYNOLOGY_IP_ADDRESS>> AZURE_COSMOS_EMULATOR_ENABLE_DATA_PERSISTENCE = true AZURE_COSMOS_EMULATOR_PARTITION_COUNT = 10
Finally, you will need to ensure you have mapped these ports for the container. Ensure you have opened these below ports on the Synology’s Firewall as well
For more information on creating container from docker image, see Synology’s documentation.
Install the certificate on your machine
To avoid errors due to certificate, you need to download the self-signed certificate for the emulator and install it on your machine. To download the certificate for the emulator run below command
curl -k https://<<SYNOLOGY_IP_ADDRESS>>:8081/_explorer/emulator.pem > emulatorcert.crt
On my Mac, I had to install it on Keychain Access App and set it as
Once done you should be able to browse the Cosmos Emulator UI using
That is it! Your Cosmos Emulator is now available to use all the time.