Testing Azure Cosmos DB Locally Using A Docker Container Image

Why use the emulator? And why Docker?

Microsoft's Cosmos DB is a cloud-based, scalable database service that has been popular ever since its launch in May 2017. In order to develop solutions using Cosmos DB as a backend, a cheap and easy way is to use the emulator provided by Microsoft. However, nobody wants to mess around with installing stuff like this locally on your developer workstation. And fully virtualized VMware images consume a large portion of resources. Docker comes to the rescue, as a docker image co-uses the kernel of the machine its running on and thus is slick, has a rather small footprint both in storage and memory consumption and gets you up and running in minutes.

How to get started?

First of all, you need to install the Docker client on your machine. For Windows, Docker Desktop can be downloaded from here. Once installed, you can grab the Cosmos DB emulator from Microsoft's container registry by using the command line:

docker pull mcr.microsoft.com/cosmosdb/windows/azure-cosmos-emulator

In order to start the container image, all you have to do afterwards is to create a new directory and then run the image mounting this directory. You may want to adapt the memory footprint you're allowing for, however the 2GB seem to be just enough to get by. Make sure the ports you're passing are not conflicting with other ports you have in use.

md %LOCALAPPDATA%\CosmosDBEmulator\bind-mount

docker run --name azure-cosmosdb-emulator --memory 2GB --mount "type=bind,source=%LOCALAPPDATA%\CosmosDBEmulator\bind-mount,destination=C:\CosmosDB.Emulator\bind-mount" --interactive --tty -p 8081:8081 -p 8900:8900 -p 8901:8901 -p 8902:8902 -p 10250:10250 -p 10251:10251 -p 10252:10252 -p 10253:10253 -p 10254:10254 -p 10255:10255 -p 10256:10256 -p 10350:10350 mcr.microsoft.com/cosmosdb/windows/azure-cosmos-emulator

Running this command results in an output like this:

Additionally, a PowerShell script gets created automatically that contains the code required to import the SSH certificate for the docker container instance. You'll find it in the newly created bind-mount directory. Import the certificate by double-clicking the importcert.ps1 file. Also note the different endpoints provided in the response. You can start the emulator by navigating to this endpoint in your browser then. Specifically, to <endpoint>/_explorer/index.html. For the sample above, this would be

https://172.28.9.42:8081/_explorer/index.html

which brings up the Azure Cosmos DB Emulator UI:

From here you can start your encounters working with the Cosmos DB database. For a quick start, you might have a look at this blog post that gets you up and running with a TODO collection. Microsoft provides very handy means to get started with a C# app which are described in more detail there.

Conclusion

The presented emulator solution using Docker is a very helpful way to keep your machine clear, save costs during the development phase and get to know Cosmos DB. Let me know if you've worked with the emulator before and make sure to share your experiences.