|
| 1 | +--- |
| 2 | +title: Emulator (Docker/local) |
| 3 | +titleSuffix: Azure Cosmos DB |
| 4 | +description: Use the Azure Cosmos DB local or docker-based emulator to test your applications against multiple API endpoints. |
| 5 | +author: sajeetharan |
| 6 | +ms.author: sasinnat |
| 7 | +ms.reviewer: sidandrews |
| 8 | +ms.service: cosmos-db |
| 9 | +ms.topic: conceptual |
| 10 | +ms.date: 09/11/2023 |
| 11 | +# CustomerIntent: As a developer, I want to use the Azure Cosmos DB emulator so that I can develop my application against a database during development. |
| 12 | +--- |
| 13 | + |
| 14 | +# What is the Azure Cosmos DB emulator? |
| 15 | + |
| 16 | +The Azure Cosmos DB emulator provides a local environment that emulates the Azure Cosmos DB service designed for development purposes. Using the emulator, you can develop and test your application locally, without creating an Azure subscription or incurring any service costs. When you're satisfied with how your application is working with the emulator, you can transition to using an Azure Cosmos DB account with minimal friction. |
| 17 | + |
| 18 | +> [!IMPORTANT] |
| 19 | +> We do not recommend the use of the emulator for production workloads. |
| 20 | +
|
| 21 | +## Differences between the emulator and cloud service |
| 22 | + |
| 23 | +The emulator provides an environment on your developer workspace that isn't capable of emulating every aspect of the Azure Cosmos DB service. Here are a few key differences in functionality between the emulator and the equivalent cloud service. |
| 24 | + |
| 25 | +> [!IMPORTANT] |
| 26 | +> The Linux emulator currently has limited support for developer machines running on M1 and M2 chips. A temporary workaround is to install a Windows virtual machine and run the emulator on that platform. |
| 27 | +
|
| 28 | +- The emulator's **Data Explorer** pane is only supported in the API for NoSQL and API for MongoDB. |
| 29 | +- The emulator only supports **provisioned throughput**. The emulator doesn't support **serverless** throughput. |
| 30 | +- The emulator uses a well-known key when it starts. You can't regenerate the key for the running emulator. To use a different key, you must [start the emulator with the custom key specified](#authentication). |
| 31 | +- The emulator can't be replicated across geographical regions or multiple instances. Only a single running instance of the emulator is supported. The emulator can't be scaled out. |
| 32 | +- The emulator only supports up to 10 fixed-size containers at 400 RU/s or 5 unlimited-size containers. |
| 33 | +- The emulator only supports the [Session](consistency-levels.md#session-consistency) and [Strong](consistency-levels.md#strong-consistency) consistency levels. The emulator isn't a scalable service and doesn't actually implement the consistency levels. The emulator only flags the configured consistency level for testing purposes. |
| 34 | +- The emulator constraints the unique identifier of items to a size of **254** characters. |
| 35 | +- The emulator supports a maximum of five `JOIN` statements per query. |
| 36 | + |
| 37 | +The emulator's features may lag behind the pace of new features for the cloud service. There could potentially be new features and changes in the cloud service that have a small delay before they're available in the emulator. |
| 38 | + |
| 39 | +## Authentication |
| 40 | + |
| 41 | +Every request made against the emulator must be authenticated using a key over TLS/SSL. The emulator ships with a single account configured to use a well-known authentication key. By default, these credentials are the only credentials permitted for use with the emulator: |
| 42 | + |
| 43 | +| | Value | |
| 44 | +| --- | --- | |
| 45 | +| **Endpoint** | `localhost:8081` | |
| 46 | +| **Key** | `C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==` | |
| 47 | +| **Connection string** | `` | |
| 48 | + |
| 49 | +> [!TIP] |
| 50 | +> With the Windows (local) emulator, you can also customize the key used by the emulator. For more information, see [Windows emulator arguments](emulator-command-line-parameters.md#manage-the-emulator-with-command-line-syntax). |
| 51 | +
|
| 52 | +## Import emulator certificate |
| 53 | + |
| 54 | +In some cases, you may wish to manually import the TLS/SS certificate from the emulator's running container into your host machine. This step avoids bad practices like disabling TLS/SSL validation in the SDK. |
| 55 | + |
| 56 | +### [Docker (container)](#tab/docker) |
| 57 | + |
| 58 | +The certificate for the emulator is available in the `_explorer/emulator.pem` path on the running container. Use `curl` to download the certificate from the running container to your local machine. |
| 59 | + |
| 60 | +```bash |
| 61 | +curl -k https://localhost:8081/_explorer/emulator.pem > ~/emulatorcert.crt |
| 62 | +``` |
| 63 | + |
| 64 | +> [!NOTE] |
| 65 | +> You may need to change the host (or IP address) and port number if you have previously modified those values. |
| 66 | +
|
| 67 | +Install the certificate according to the process typically used for your operating system. For example, in Linux you would copy the certificate to the `/usr/local/share/ca-certificats/` path. |
| 68 | + |
| 69 | +```bash |
| 70 | +cp ~/emulatorcert.crt /usr/local/share/ca-certificates/ |
| 71 | +``` |
| 72 | + |
| 73 | +### [Windows (local)](#tab/windows) |
| 74 | + |
| 75 | +The Windows local installation of the emulator automatically imports the TLS/SSL certificates. No further action is necessary. |
| 76 | + |
| 77 | +--- |
| 78 | + |
| 79 | +## Next step |
| 80 | + |
| 81 | +> [!div class="nextstepaction"] |
| 82 | +> [Get started with Azure Cosmos DB](../index.yml) |
0 commit comments