Skip to content
This repository was archived by the owner on Nov 17, 2023. It is now read-only.

Windows setup

Jump to bottom
Miguel Veloso edited this page Jan 28, 2020 · 26 revisions

This page covers the setup of your Windows development computer and assumes you've already:

The approach followed is to have the app running from the CLI first, since it's usually easier to deploy, and then go on to the option of using Visual Studio.

CONTENT

Configure Docker

The initial Docker for Desktop configuration is not suitable to run eShopOnContainers because the app uses a total of 25 Linux containers.

Even though the microservices are rather light, the application also runs SQL Server, Redis, MongoDb, RabbitMQ and Seq as separate containers. The SQL Server container has four databases (for different microservices) and takes an important amount of memory.

So it's important to configure enough memory RAM and CPU to Docker.

Memory and CPU

Once Docker for Windows is installed, go to the Settings > Advanced option, from the Docker icon in the system tray, to configure the minimum amount of memory and CPU like so:

  • Memory: 4096 MB
  • CPU: 2

This amount of memory is the absolute minimum to have the app running, and that's why you need a 16GB RAM machine for optimal configuration.

What can I do if my computer has only 8 GB RAM?

Shared drives

This step is optional but recommended, as Docker sometimes needs to access the shared drives when building, depending on the build actions.

This is not really necessary when building from the CLI, but it's mandatory when building from Visual Studio to access the code to build.

The drive you'll need to share depends on where you place your source code.

Configure local networking

IMPORTANT: Ports 5100 to 5105 must be open in the local Firewall, so authentication to the STS (Security Token Service container, based on IdentityServer) can be done through the 10.0.75.1 IP, which should be available and already setup by Docker. These ports are also needed for client remote apps like Xamarin app or SPA app in a remote browser.

You can manually create a rule in your local firewall in your development machine or you can just run the add-firewall-rules-for-sts-auth-thru-docker.ps1 script available in the solution's deploy\windows\ folder.

NOTE: If you get the error Unable to obtain configuration from: http://10.0.75.1:5105/.well-known/openid-configuration you might need to allow the program vpnkit for connections to and from any computer through all ports.

If you are working within a corporate VPN you might need to run this power shell command every time you power up your machine, to allow access from the DockerNAT network:

Get-NetConnectionProfile | Where-Object { $_.InterfaceAlias -match "(DockerNAT)" } | ForEach-Object { Set-NetConnectionProfile -InterfaceIndex $_.InterfaceIndex -NetworkCategory Private }

Or just run the set-dockernat-networkategory-to-private.ps1 script available in the solution's deploy/windows folder.

Build and deploy eShopOnContainers

At this point you should be able to run eShopOnContainers from the command line. To do that, you should:

1. Create a folder for your repositories

Go to a directory to clone the repo, something like C:\Users\<username>\source will be fine.

2. Clone eShopOnContainer's GitHub repo 

git clone https://github.com/dotnet-architecture/eShopOnContainers.git

Note: Remember that the active development is done in dev branch. To test the latest code, use this branch instead of master.

3. Build the application

cd eShopOnContainers\src
docker-compose build

While building the docker images, you should see something like the following image, and the process should take between 10 and 30 minutes to complete, depending on the system speed.

The first time you run this command it'll take some more additional time as it needs to pull/download the dotnet/core/aspnet and SDK images, so it'll take its time.

4. Deploy to the local Docker host

docker-compose up

You should view something like this in the first seconds:

After a few more seconds you should see something like this:

At this point you should be able to navigate to http://localhost:5107/ and see the WebStatus microservice:

When all microservices are up (green checks) you should be able to navigate to http://localhost:5100/ and see the Home Page of eShopOnContainers:

Explore the application

You can now explore the application or continue with the optional Visual Studio setup.

Optional - Use Visual Studio

If you want to explore the code and debug the application to see it working, you have to install Visual Studio.

You have to install at least VS 2017 (15.9) and you can install the latest release from https://visualstudio.microsoft.com/vs/.

Make sure you have the latest SDK 3.0 version from https://dotnet.microsoft.com/download/dotnet-core/3.0 installed.

Upon running the installer, select the following workloads depending on the apps you intend to test or work with:

Server side (Microservices and web applications) - Workloads

  • .NET Core cross-platform development
  • Azure development (Optional) - It is optional but recommended in case you want to deploy to Docker hosts in Azure or use any other infrastructure in Azure.

Mobile (Xamarin apps for iOS, Android and Windows UWP) - Workloads

If you also want to test/work with the eShopOnContainer model app based on Xamarin, you need to install the following additional workloads:

  • Mobile development with .NET (Xamarin)
  • Universal Windows Platform development
  • .NET desktop development (Optional) - This is not required, but just in case you also want to make tests consuming the microservices from WPF or WinForms desktop apps

IMPORTANT: As mentioned above, make sure you are NOT installing Google's Android emulator with Intel HAXM hypervisor or you will run on an incompatibility and Hyper-V won't work in your machine, therefore, Docker for Windows won't work when trying to run the Linux host or any host with Hyper-V.

Make sure that you DO NOT select the highlighted options below with red arrows:

Stop Docker background tasks on project open

VS runs some docker related tasks when opening a project with Docker support, to avoid these tasks from executing and slowing down your system, you might want to configure this options:

Open eShopOnContainers solution in Visual Studio

  • If testing/working only with the server-side applications and services, open the solution: eShopOnContainers-ServicesAndWebApps.sln (Recommended for most cases testing the containers and web apps)

  • If testing/working either with the server-side applications and services plus the Xamarin mobile apps, open the solution: eShopOnContainers.sln

Below you can see the full eShopOnContainers-ServicesAndWebApps.sln solution (server side) opened in Visual Studio 2017:

Note how VS 2017 loads the docker-compose.yml files in a special node-tree so it uses that configuration to deploy/debug all the containers configured, at the same time into your Docker host.

Build and run the application with F5 or Ctrl+F5

Set docker-compose as the default StartUp project

IMPORTANT: If the "docker-compose" project is not your "by default startup project", right click on the "docker-compose" node and select the "Set as Startup Project" menu option, as shown below:

At this point, after waiting sometime for the NuGet packages to be properly restored, you should be able to build the whole solution or even directly deploy/debug it into Docker by simple hitting F5 or pressing the debug "Play" button that now should be labeled as "Docker":

VS 2017 should compile the .NET projects, then create the Docker images and finally deploy the containers in the Docker host (your by default Linux VM in Docker for Windows). Note that the first time you hit F5 it'll take more time, a few minutes at least, because in addition to compile your bits, it needs to pull/download the base images (SQL for Linux Docker Image, Redis Image, ASPNET image, etc.) and register them in the local image repo of your PC. The next time you hit F5 it'll be much faster.

Finally, because the docker-compose configuration project is configured to open the MVC application, it should open your by default browser and show the MVC application with data coming from the microservices/containers:

Here's how the docker-compose configuration project is configured to open the MVC application:

Finally, you can check out how the multiple containers are running in your Docker host by running the command "docker ps" like below:

You can see the 8 containers are running and what ports are being exposed, etc.

Debug with several breakpoints across the multiple containers/projects

Something very compelling and productive in VS 2017 is the capability to debug several breakpoints across the multiple containers/projects. For instance, you could set a breakpoint in a controller within the MVC web app plus a second breakpoint in a second controller within the Catalog Web API microservice, then refresh the browser if you were still running the app or F5 again, and VS will be stopping within your microservices running in Docker as shown below! :)

Breakpoint at the MVC app running as Docker container in the Docker host:

Press F5 again...

Breakpoint at the Catalog microservice running as Docker container in the Docker host:

And that's it! Super simple! Visual Studio is handling all the complexities under the covers and you can directly do F5 and debug a multi-container application!

Issue with "Visual Studio 2017 Tools for Docker" and network proxies/firewalls

After installing VS2017 with docker support, if you cannot debug properly and you are trying from a corporate network behind a proxy, consider the following issue and workarounds, until this issue is fixed in Visual Studio:

Optional - Use Visual Studio Code

After installing VS code from Visual Studio Code you can edit particular file or "open" the whole solution folder like in the following screenshots:

Opening the Solution's folder

Editing a .yml file

It is also recommended to install the C# extension and the Docker extension for VS Code:

Explore the code

You should be now ready to begin learning by exploring the code and debugging eShopOnContainers.

Low memory configuration

If your computer has only 8 GB RAM, you might still get eShopOnContainers up and running, but it's not sure and you will not be able to run Visual Studio. You might be able to run VS Code and you'll be limited to the CLI. You might even need to run Chromium or any other bare browser, Chrome will most probably not do. You'll also need to close any other program running in your machine.

The easiest way to get Chromium binaries directly from Google is to install the node-chromium package in a folder and then look for the chrome.exe program, as follows:

  1. Install node.

  2. Create a folder wherever best suits you.

  3. Run npm install --save chromium

  4. After installation finishes go to folder node_modules\chromium\lib\chromium\chrome-win (in Windows) to find chrome.exe

The installation process should look something like this:

Additional resources

eShopOnContainers

Getting started

FREQUENT ERRORS

Explore

Deployment

Local

Production (generic)

Cloud

Other Deployment Scenarios

DevOps

Clone this wiki locally