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 ( 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 Allow port 22.

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

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


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 Always Trust.

Once done you should be able to browse the Cosmos Emulator UI using https://<<SYNOLOGY_IP_ADDRESS>>:8081/_explorer/index.html

That is it! Your Cosmos Emulator is now available to use all the time.


Related Posts
About author
Utkarsh Shigihalli
Utkarsh Shigihalli
Utkarsh is passionate about software development and has experience in the areas of Azure, Azure DevOps, C# and TypeScript. Over the years he has worked as an architect, independent consultant and manager in many countries including India, United States, Netherlands and United Kingdom. He is a Microsoft MVP and has developed numerous extensions for Visual Studio, Visual Studio Code and Azure DevOps.
We Are
  • onlyutkarsh
    Utkarsh Shigihalli
    Microsoft MVP, Technologist & DevOps Coach

  • arora_tarun
    Tarun Arora
    Microsoft MVP, Author & DevOps Coach at Avanade

Do you like our posts? Subscribe to our newsletter!
Our Book