Skip to main content

Cosmos DB Emulator

Set up Cosmos DB Emulator locally

The Azure CosmosDB Emulator provides a local environment that emulates the Azure Cosmos DB service for development purposes. Using the Azure CosmosDB Emulator, you can develop and test your application locally, without creating an Azure subscription or incurring any costs. Latest instruction can be found in here

Using the Cosmos DB Emulator to run the database locally

Download and install the latest version of CosmosDB Emulator. Once it's installed, it will be available on localhost.

The CosmosDB Emulator service is primarily a Windows service, so using it in Unix/Linux/MacOS requires a few additional steps. One of the simplest ways of running the emulator is to download the Linux Emulator for Docker. Please follow the installation instructions, with one exception: when running the Docker image, don't set the AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE=$ipaddr. Instead, set it to

The value for COSMOSDB_KEY can be found within the emulator. See Primary Key:

cosmosdb Please, take a note of the cosmosdb URI, databaseName and key, as they will be needed to configure the application in a further step.

Create the Cosmos DB structure

Based on the template the CosmosDB has to contain a fixed structure.

Create a collection Stacks with a container id menu and the partition key /id.

Create a database called Stacks for the application, and a database called CosmosDBPackage for the integration tests of the CosmosDB package (using the same container id and partition key as the main database).


The Stacks database should have a container called Menu partitioned by /id.


Export Azure Cosmos DB Emulator certificates to use in the Java Application

Download the certificate

curl -k https://localhost:8081/_explorer/emulator.pem > emulatorcert.crt

Import to Java trust store

keytool -importcert -cacerts -alias documentdbemulator -file <path to emulatorcert.crt>

In order to make sure the certificate is there, you can run the following:

keytool -list -cacerts | grep -A1 documentdbemulator