Azure-docs: Wrong instructions on using Emulator on Mac OSX

[galvesribeiro]

According to CosmosDB product docs, in order to use the emulator on Mac OSX, we require to have a Windows VM as suggested on this document page.

However, that only works if you are using the old/2.x CosmosDB client SDK.

If you use then any version greater than 3.x+, you will have no way to set the HttpClientHandler and hence no way to _bypass_ the SSL validation.

We now either have to have a new version of the SDK that introduce support to set the HttpClientHandler or, we finally have CosmosDB emulator cross platform (it is already too late indeed).

Please advise what we can do to support Mac OSX users.

Thanks!

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 109ed3f8-faf1-92b9-bf50-4be52e9099d4
• Version Independent ID: ebc5326a-46da-6bc1-1f47-01a8e16d11fb
• Content: Develop locally with the Azure Cosmos Emulator
• Content Source: articles/cosmos-db/local-emulator.md
• Service: cosmos-db
• GitHub Login: @markjbrown
• Microsoft Alias: mjbrown

[Mike-Ubezzi-MSFT]

@galvesribeiro Thank you so much for opening a new Git Issue for this. This has the correct resources associated with the document (content owner, etc.), where the old issue identifies content owners who have moved onto other projects.

[galvesribeiro]

Thank you for getting back @Mike-Ubezzi-MSFT

This issues is being blocking non-Windows users of CosmosDB for a long time. Every single reply I got from multiple MSFT channels points to always a workaround for years. Never a _real_ solution, which would be the cross platform emulator...

I hope this will eventually changed, for good.

Thank you!

[Mike-Ubezzi-MSFT]

Want to provide additional information that development for a MacOS/Linux version of the Emulator has started: Add DocumentDB Emulator support for Mac OS X and *nix

However, the current instructions for installing on an Windows VM has some compatibility issues as well detailed by @galvesribeiro.

[Mike-Ubezzi-MSFT]

I have made this a doc-enhancement as the Running on Mac or Linux section needs to include guidance for the latest revisions of the SDK.

[galvesribeiro]

I have made this a doc-enhancement as the Running on Mac or Linux section needs to include guidance for the latest revisions of the SDK.

That is what I meant...

using Microsoft.Azure.Documents;
using Microsoft.Azure.Documents.Client;

That works with the 2.x version of the SDK: https://www.nuget.org/packages/Microsoft.Azure.DocumentDB.Core/

If you try the 3.x or 4.x-preview like on this package https://www.nuget.org/packages/Microsoft.Azure.Cosmos/:

using Microsoft.Azure.Cosmos;

You will have the problem I mentioned, since there is no way to inject HttpClientHandler.

[mamadou94Diop]

Hi @galvesribeiro, I faced the same issue, I would like to use the emulator on my Mac( given that using azure cosmos db instance is very expensive, mostly for testing purpose).

I had one idea to experiment, Having a Windows pc with emulator, run it on a local network, finally try to reach it by ip of local network

[galvesribeiro]

Hello @mamadou94Diop

It doesn't matter if it is a _real_ PC or an VM. What matters is the self-signed certificate that is issued by the emulator that isn't valid on another machine, and specially now that with OSX 10.15 (Catelina), Apple is very strict about HTTPS/TLS...

[mamadou94Diop]

Looking forward that Microsoft provides solution to that issue quickly

[SnehaGunda]

@Mike-Ubezzi-MSFT if I understand the issue correctly, we have already documented the limitation for V3 SDK. So I don't see any further doc update. Are we waiting for the team to share the timelines for the support?

[galvesribeiro]

@SnehaGunda where is the documentation for that limitation? I can't see it on the docs site. Can you please point me out?

Also yes, a solution must be implemented as it breaks everyone using the emulator because there isn't a way to use it outside Windows.

[SnehaGunda]

@galvesribeiro it's in this section: https://docs.microsoft.com/en-us/azure/cosmos-db/local-emulator#running-on-docker

[galvesribeiro]

That is the whole point of this issue. That document is for V2 and NOT valid on V3 and V4.

There is no way to set HttpClientHandler on V3/V4...

[mamadou94Diop]

@galvesribeiro I found a workaround that fits to my needs.
After installing a windows 10 VM in VirtualBox, I installed dotnet sdk and runtime on it.
I shared my ASP.Net core project folder, so that is accessible on windows VM.
I configured the network settings on Virtual Box with NAT, I did after that a port forwarding( HOST IP localhost:5000 --------> GUEST IP : 10.0.2.15:5000).
I run now my project with an endpoint which corresponds to IP of VM (10.0.2.15) at port 5000
When I made a call from my host mac with localhost:5000/{action}, I managed to reach data from cosmos fetched by the backend running on my windows VM .

[galvesribeiro]

@mamadou94Diop I don't see how it would be a workaround for my case.

I'm talking about SDK v3 or greater and I need the application to run on my Mac, just like on SDK v2, not on the VM...

[mamadou94Diop]

@galvesribeiro Fou your information, I have a mac and I use the Azure cosmos DB V3 .NET SDK.
Emulator is available only on Windows docker container or msi installer, I do not have choice at this other than trying to find a trick.
I do not hear an upcoming Emulator available for mac, so I just want share a solution to avoid being stucked

[galvesribeiro]

I understand that. Just saying that hosting the application that talks to the Cosmos Emulator on the Windows VM isn't an option on our case. To be honest, use a VM is already being a HUGE problem for us...

We need a real fix for this either on the SDK or the Emulator. I've already provided multiple options on how to fix this on multiple issues over the SDK repositories and I'm pretty sure Microsoft has resources to apply them very quickly.

[mamadou94Diop]

Sure! They can do it quickly but is it the priority for them?? Hope it is

[galvesribeiro]

Well, MSFT is selling out and loud that they now are a fully cross-plat/cross-cloud/cross-anything. It is a pretty bad press impression to keep things Windows-only. Not to mention this is an issue very old. Again, the changes to support that are very simple. If the emulator was Open Source, I'm pretty sure the community (including myself) would already have that fixed...

[galvesribeiro]

Hello folks!

This is issue is labeled _assigned-to-author_. I'm now see how I can fix this problem...

Can someone give us directions?

Thank you!

[markjbrown]

We're pushing an update to our docs which will address this issue. When this docs update gets merged into our docs I'll post an update here

thanks

[SnehaGunda]

The updated doc is live, we will now close this issue.

please-close

[galvesribeiro]

Can you please share the link? Can’t find the update

[Mike-Ubezzi-MSFT]

@galvesribeiro It was merged into master about 30 mins ago, and will be visible by you within 24 hours per our docs publishing process. Likely by 10am PST Friday morning (Jan 31) at the very latest.

[markjbrown]

Here's the link.
https://docs.microsoft.com/en-us/azure/cosmos-db/local-emulator#running-on-mac-or-linux

Thanks everyone for your patience on this. We are very happy we could provide a workaround on this.

Thanks again