How to connect Azure Cosmos DB Emulator with Spring Boot app at Windows

In this article, we will look at how to install Azure Cosmos DB Emulator on your Windows machine and how to use the Azure Cosmos DB Emulator for local development of our Spring Boot application.

How to install Azure CosmosDB Emulator

First of all, we need to install Azure CosmosDB Emulator locally. Go to https://docs.microsoft.com/en-us/azure/cosmos-db/local-emulator#installation, download the windows installation package and install Azure Cosmos DB Emulator.

When the installation of Azure Cosmos DB Emulator passed successfully on your Windows machine, start the emulator (if it did not start automatically).

If it is already running you can find it minimized in the system hidden in the running application system and either click Open Data Explorer … or visit https://localhost:8081/_explorer/index.html page. You can now get finally into the Azure CosmosDB Emulator.

Exporting security certificates

Azure Cosmos DB Emulator uses a secure connection with your application. We need to extract and register your certificate for communication with the emulator.

Let’s type “Manage user certificates” into Windows Start console or open Windows Certificate Manager (running certlm.msc in the run prompt). Go to Personal->Certificates folder and export certificate with DocumentDbEmulatorCertificate name. The whole tutorial how to do it can be found at Microsoft Azure website explaining how to export the Azure Cosmos DB SSL certificate.

You can name your file when exporting arbitrary. However, we will name it for our example documentdbemulatorcert.cer.

Now when I have extracted SSL certificate, I need to upload it into the correct Java SDK location.

Check which version of Java do you use in your project. In IntelliJ idea you can use either keyword shortcut [ctrl] + [shift] + [alt] + [s] or go to File->Project Structure->SDKs and check which version your Spring Boot application uses or where SDK is located.

Copy certificate into the Java SDK directory. It should be copied into the %JAVA_HOME%/jre/lib/security location.

If you use OpenJDK, OpenJDK does not contain jre folder. Just copy it into %JAVA_HOME%/lib/security location.

Registering certificate

The nearly last thing we need to do is to register the certificate into the system.

We need to open Windows’s Command prompt as an administrator and navigate to JDK’s folder at jdk\jre\lib\security.

Hint: A little hint if you are more familiar with Linux based systems – if you open folder in Windows’s window, copy the path to the folder and place it into quotation marks in command prompt. Executing command changes the directory instantly.

Then, upon the folder, we need just to run the following command to register the certificate into the keystore on your system:

keytool -keystore cacerts -importcert -alias documentdbemulator -file documentdbemulatorcert.cer

Hint : Keytool is a tool located in you Java installation, so for this to work, you need to have jdk/bin on you PATH.

If you need a hint with registration, check this tutorial at Microsoft Azure website where you learn how to add a root certificate to the certification authority certificates storage. However instead of bc2025.cer name in tutorial use name of your certificate.

Otherwise, when the prompt asks for a password, type your password. More likely you didn’t change it, so default password is changeit. Following, you get a question, if you trust this certificate. Answer it simply yes.

That is it. The certificate is registered, and Azure Cosmos DB Emulator should be now created security and with ease.

Using emulator with local Spring Boot app development

And all we need to do now is just run the Spring Boot application. If you implemented a connection to Cosmos DB and registered connection properties to application.properties or application.yml you can successfully run the application.

To fill up application.yml you will need to implement your own data:

azure:
   cosmosdb:
    uri: https://localhost:8081
    key: VERY_LONG_KEY
    database: YOUR_DB_NAME

You can find VERY_LONG_KEY in your Azure Cosmos DB Emulator Data Explorer under the Quick start tab.

And all we need to do now is just run the Spring Boot application. If you check now Data Explorer under Explorer tab, you can find now your database with all the defined structures.

Troubleshooting

In case you already successfully installed the Azure CosmosDB Emulator, and you want to restart the database, you have an option to reset data. This can be a case when you get an authentication issue over HTTPS with your Azure CosmosDB certificate on application run.

Pick up “Reset data” from Azure CosmosDB Emulator mini-panel dialogue window from your start button. Operation is not reversible; it will clean up all your caches and the internal state of Azure CosmosDB Emulator database and reset the certificate.

Then you need to continue extracting the certificate from the list of certificates as according to the description in Exporting Security Certificates. However, before registering the certificate back to Java keytool you need to remove old alias on the certificate with command like this:

keytool -delete -alias documentdbemulator -keystore cacerts -storepass changeit

Note: behind -alias you place the name of the certificate, -keystore is the name of a file containing the certificates and behind -storepass is your password (default is changeit).

This entry was posted in Tutorials and tagged , , , , , , , , , . Bookmark the permalink.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.