Updated 03. Setting the eShopOnContainers solution up in a Windows CLI environment (dotnet CLI, Docker CLI and VS Code) (markdown)
Cesar De la Torre
parent
861128758a
commit
84f4bdc405
@ -2,6 +2,8 @@
|
|||||||
|
|
||||||
* [https://github.com/dotnet-architecture/eShopOnContainers/blob/master/readme/readme-docker-compose.md](https://github.com/dotnet-architecture/eShopOnContainers/blob/master/readme/readme-docker-compose.md): All docker compose files that we have and how to use them
|
* [https://github.com/dotnet-architecture/eShopOnContainers/blob/master/readme/readme-docker-compose.md](https://github.com/dotnet-architecture/eShopOnContainers/blob/master/readme/readme-docker-compose.md): All docker compose files that we have and how to use them
|
||||||
|
|
||||||
|
IMPORTANT NOTE:
|
||||||
|
|
||||||
## Want to try it out from the CLI?
|
## Want to try it out from the CLI?
|
||||||
|
|
||||||
Main steps:
|
Main steps:
|
||||||
@ -15,19 +17,119 @@ NOTE: In order for the authentication based on the STS (Security Token Service)
|
|||||||
For further instructions, especially if this is the first time you are going to try .NET Core on Docker, see the detailed instructions below. This is also important in order to make the SPA app (Single Page Application) to work as there are some considerations (npm install, etc.) in regards when using NPM from Windows and Linux (the build container).
|
For further instructions, especially if this is the first time you are going to try .NET Core on Docker, see the detailed instructions below. This is also important in order to make the SPA app (Single Page Application) to work as there are some considerations (npm install, etc.) in regards when using NPM from Windows and Linux (the build container).
|
||||||
|
|
||||||
--------------------------------------------------------------------
|
--------------------------------------------------------------------
|
||||||
--------------------------------------------------------------------
|
|
||||||
## Detailed procedure - Setting eShopOnContainers up in a CLI and Windows based development machine
|
# Detailed procedure - Setting eShopOnContainers up in a CLI and Windows based development machine
|
||||||
This CLI environment means that you want to build/run by using the CLI (Command line interface) available in .NET Core (dotnetcore) and Docker CLI.
|
This CLI environment means that you want to build/run by using the CLI (Command line interface) available in .NET Core (dotnetcore) and Docker CLI.
|
||||||
<p>
|
<p>
|
||||||
You don't need Visual Studio 2017 for this environment but can use any code editor like Visual Studio Code, Sublime, etc. Of course, you could still use VS 2017 at the same time, as well.
|
You don't need Visual Studio 2017 for this environment but can use any code editor like Visual Studio Code, Sublime, etc. Of course, you could still use VS 2017 at the same time, as well.
|
||||||
|
|
||||||
### GitHub branch to use/pull
|
|
||||||
By default, use the MASTER branch which supports .CSPROJ projects and .NET Core 1.1 CLI and Docker CLI. The same branch's code supports Visual Studio 2017 or CLI scenarios, simultaneously, depending on each developer's preference.
|
|
||||||
|
|
||||||
### Approach building bits from a container instead of the local dev-machine
|
## Prerequisites
|
||||||
|
|
||||||
|
1. [Docker for Windows](https://docs.docker.com/docker-for-windows/install/).
|
||||||
|
1. A Git client. The [git-scm site](https://git-scm.com/download/gui/mac) maintains a great list of clients.
|
||||||
|
1. [Node.js](http://nodejs.org). The stable channel is fine as well.
|
||||||
|
1. Bower (/> npm install -g bower) needed for the MVC web app.
|
||||||
|
1. [.NET Core and SDK](http://dot.net). Install the SDK and runtime.
|
||||||
|
|
||||||
|
# Setting up the development environment
|
||||||
|
|
||||||
|
## Installing and configuring Docker in your development machine
|
||||||
|
|
||||||
|
### Install Docker for Windows
|
||||||
|
Install Docker for Windows (The Stable channel should suffice) from this page: https://docs.docker.com/docker-for-windows/install/
|
||||||
|
About further info on Docker for windows, check this additional page
|
||||||
|
https://docs.docker.com/docker-for-windows/
|
||||||
|
|
||||||
|
Docker for Windows uses Hyper-V to run a Linux VM which is the by default Docker host. If you don't have Hyper-V installed/enabled, it'll be installed and you will probably need to reboot your machine. Docker's setup should warn you about it, though.
|
||||||
|
|
||||||
|
**IMPORTANT**: Check that you don't have any other hypervisor installed that might be not compatible with Hyper-V. For instance, Intel HAXM can be installed by VS 2017 if you chose to install Google's Android emulator which works on top of Intel HAXM. In that case, you'd need to uninstall Google's Android emulator and Intel HAXM.
|
||||||
|
VS 2017 recommends to install the Google Android emulator because it is the only Android emulator with support for Google Play Store, Google Maps, etc. However, take into account that it currently is not compatible with Hyper-V, so you might have incompatibilities with this scenario.
|
||||||
|
|
||||||
|
### Set needed assigned Memory and CPU to Docker
|
||||||
|
For the development environment of eShopOnContainers, by default, it runs 1 instance of SQL Server running as a container with multiple databases (one DB per microservice), other 6 additional ASP.NET Core apps/services each one running as a container, plus 1 Redis server running as a container. Therefore, especially because of the SQL Server requirements on memory, it is important to set Docker up properly with enough memory RAM and CPU assigned to it or you will get errors when starting the containers with "docker-compose up".
|
||||||
|
|
||||||
|
Once Docker for Windows is installed in your machine, enter into its Settings and the Advanced menu option so you are able to adjust it to the minimum amount of memory and CPU (Memory: Around 4096MB and CPU:3) as shown in the image. Usually you might need a 16GB memory machine for optimal configuration.
|
||||||
|
|
||||||
|
<img src="img/docker_settings.png">
|
||||||
|
|
||||||
|
### Share drives in Docker settings
|
||||||
|
Tis is an important and required configuration step in order to build the bits from the build-container so it has access to the solution files.<p>
|
||||||
|
You need to share the drives from Settings-> Shared Drives in the "Docker for Windows" configuration.
|
||||||
|
If you don't do this, you will get an error when trying to build from te container, like "Cannot create container for service yourApplication: C: drive is not shared". <p>
|
||||||
|
The drive you'll need to share depends on where you place your source code.
|
||||||
|
|
||||||
|
<img src="img/docker_settings_shared_drives.png">
|
||||||
|
|
||||||
|
**NOTE**: If you are using **Windows 10 Creators Update** (Windows 10 Creators Update, version 1703, codenamed "Redstone 2") **and your machine is joined to a Windows or Azure Domain**, you might get some issues when configuring the share drives for Docker. Providing a local user credential (from your actual machine) instead of a Windows/Azure Domain user credential might solve the issue.
|
||||||
|
Check the following blog post for additional workarounds:
|
||||||
|
https://blogs.msdn.microsoft.com/stevelasker/2016/06/14/configuring-docker-for-windows-volumes/
|
||||||
|
|
||||||
|
### IMPORTANT: Open ports in local Firewall so Authentication to the STS (Security Token Service container) can be done through the 10.0.75.1 IP which should be available and already setup by Docker. Also needed for client remote apps like Xamarin app or SPA app in remote browser.
|
||||||
|
- You can manually create a rule in your local firewall in your development machine or you can also create that rule by just executing the <b>add-firewall-rules-for-sts-auth-thru-docker.ps1</b> script available in the solution's **cli-windows** folder.
|
||||||
|
- Basically, you need to open the ports 5100 to 5105 that are used by the solution by creating an IN-BOUND RULE in your firewall, as shown in the screenshot below (for Windows).
|
||||||
|
<img src="img/firewall-rule-for-eshop.png">
|
||||||
|
|
||||||
|
## .NET Core SDK setup
|
||||||
|
(OPTIONAL) As mentioned, this requirement is optional because when building through the "build container" it will be using the .NET SDK available within the ASPNETCore build image, not the local .NET Core SDK. However, it is recommended to have it installed locally for any further building/testing of the ASP.NET Core projects without Docker.
|
||||||
|
The .NET Core SDK install the .NET Core framework plus the SDK CLI tools with commands like "dotnet build", "dotnet publish", etc.
|
||||||
|
|
||||||
|
Install the .NET Core SDK from here
|
||||||
|
https://www.microsoft.com/net/download/core#/current
|
||||||
|
(Current/x64 .NET Core 1.1 SDK Installer, usually)
|
||||||
|
|
||||||
|
Run the setup like in the following screenshot:
|
||||||
|
<img src="img/netcore-sdk-11-installer.png">
|
||||||
|
|
||||||
|
## Install NPM
|
||||||
|
In order to be able to build the JavaScript dependencies from command line by using npm you need to install npm globally.
|
||||||
|
|
||||||
|
NPM is bundled with NODE.JS. Installing NPM and NODE is pretty straightforward by using the installer package available at https://nodejs.org/en/
|
||||||
|
|
||||||
|
<img src="img/spa/installing_npm_node.png">
|
||||||
|
You can install the version "Recommended For Most Users" of Node which at the moment of this writing was v6.10.0 LTS.
|
||||||
|
|
||||||
|
<img src="img/Node_setup_for_npm.png">
|
||||||
|
|
||||||
|
<p>
|
||||||
|
After installing Node, you can check the installed NPM version with the command <b>npm -v</b>, as shown below.
|
||||||
|
<p>
|
||||||
|
<img src="img/spa/npm-versions-powershell.png">
|
||||||
|
|
||||||
|
## Install Bower
|
||||||
|
Bower is needed by minor dependencies at the MVC web app. It using Visual Studio, VS will handle that. But if using the CLI in Windows, you need to install Bower globally by running the following NPM command:
|
||||||
|
|
||||||
|
`npm install -g bower `
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
# Clone the eShopOnContainers GitHub code Repository into your dev machine
|
||||||
|
|
||||||
|
## GitHub branch to use/pull
|
||||||
|
Use the default branch at eShopOnContainers Github repo. The same branch's code supports Visual Studio 2017 or CLI scenarios, simultaneously, depending on each developer's preference.
|
||||||
|
|
||||||
|
Clone the code from: https://github.com/dotnet/eShopOnContainers.git
|
||||||
|
as in the following screenshot:
|
||||||
|
<img src="img/cli-windows/git-clone-powershell.png">
|
||||||
|
|
||||||
|
# Get NPM dependencies for the SPA application
|
||||||
|
|
||||||
|
Move to the SPA app folder (`cd eShopOnContainers\src\Web\WebSPA`) and run `npm install`
|
||||||
|
<img src="img/spa/npm-install_full.png">
|
||||||
|
|
||||||
|
Then, run the command `npm run build:prod` as shown below:
|
||||||
|
<img src="img/spa/npm-run-build-prod.png">
|
||||||
|
|
||||||
|
After a successful execution of those npm commands, move to the next step.
|
||||||
|
If you have any issue here, read the [Setting the Web SPA application up](https://github.com/dotnet/eShopOnContainers/wiki/06.-Setting-the-Web-SPA-application-up) for further details.
|
||||||
|
|
||||||
|
|
||||||
|
# Option A. Approach building bits from a Linux build-container instead of the local Windows dev-machine
|
||||||
|
|
||||||
|
*IMPORTANT NOTE (as of Oct. 2017):* Even when this is the simplest way to do it from the CLI, but until a [bug is solved in .NET CLI when running "dotnet publish" within a container](https://github.com/Microsoft/msbuild/issues/2153#issuecomment-305375162), please, follow the OPTION B explained below, which is building the app's .NET binaries in the local Windows machine, instead of from a Linux build-container.
|
||||||
|
---
|
||||||
The recommended approach is to build the .NET bits and Docker images by using an special build container/image that should be used either from the CLI or your CI/CD pipeline. Doing that way you'll make sure that what you run and test locally is also built the same way by your CI/CD pipleine (having the same dependencies available within the build container, etc.).
|
The recommended approach is to build the .NET bits and Docker images by using an special build container/image that should be used either from the CLI or your CI/CD pipeline. Doing that way you'll make sure that what you run and test locally is also built the same way by your CI/CD pipleine (having the same dependencies available within the build container, etc.).
|
||||||
|
|
||||||
|
|
||||||
<img src="img/building-bits_from_ci_container.png">
|
<img src="img/building-bits_from_ci_container.png">
|
||||||
|
|
||||||
<p>
|
<p>
|
||||||
@ -46,93 +148,6 @@ WINDOWS DEV MACHINE
|
|||||||
- <a href='https://code.visualstudio.com/'>Visual Studio Code</a> or any other code editor.
|
- <a href='https://code.visualstudio.com/'>Visual Studio Code</a> or any other code editor.
|
||||||
- NPM and related dependencies for running the SPA Web app. <a href='https://github.com/dotnet/eShopOnContainers/wiki/06.-Setting-the-Web-SPA-application-up'>SPA app setup process described here. </a>
|
- NPM and related dependencies for running the SPA Web app. <a href='https://github.com/dotnet/eShopOnContainers/wiki/06.-Setting-the-Web-SPA-application-up'>SPA app setup process described here. </a>
|
||||||
|
|
||||||
## Setting up the development environment
|
|
||||||
|
|
||||||
### Installing and configuring Docker in your development machine
|
|
||||||
|
|
||||||
#### Install Docker for Windows
|
|
||||||
Install Docker for Windows (The Stable channel should suffice) from this page: https://docs.docker.com/docker-for-windows/install/
|
|
||||||
About further info on Docker for windows, check this additional page
|
|
||||||
https://docs.docker.com/docker-for-windows/
|
|
||||||
|
|
||||||
Docker for Windows uses Hyper-V to run a Linux VM which is the by default Docker host. If you don't have Hyper-V installed/enabled, it'll be installed and you will probably need to reboot your machine. Docker's setup should warn you about it, though.
|
|
||||||
|
|
||||||
**IMPORTANT**: Check that you don't have any other hypervisor installed that might be not compatible with Hyper-V. For instance, Intel HAXM can be installed by VS 2017 if you chose to install Google's Android emulator which works on top of Intel HAXM. In that case, you'd need to uninstall Google's Android emulator and Intel HAXM.
|
|
||||||
VS 2017 recommends to install the Google Android emulator because it is the only Android emulator with support for Google Play Store, Google Maps, etc. However, take into account that it currently is not compatible with Hyper-V, so you might have incompatibilities with this scenario.
|
|
||||||
|
|
||||||
#### Set needed assigned Memory and CPU to Docker
|
|
||||||
For the development environment of eShopOnContainers, by default, it runs 1 instance of SQL Server running as a container with multiple databases (one DB per microservice), other 6 additional ASP.NET Core apps/services each one running as a container, plus 1 Redis server running as a container. Therefore, especially because of the SQL Server requirements on memory, it is important to set Docker up properly with enough memory RAM and CPU assigned to it or you will get errors when starting the containers with "docker-compose up".
|
|
||||||
|
|
||||||
Once Docker for Windows is installed in your machine, enter into its Settings and the Advanced menu option so you are able to adjust it to the minimum amount of memory and CPU (Memory: Around 4096MB and CPU:3) as shown in the image. Usually you might need a 16GB memory machine for optimal configuration.
|
|
||||||
|
|
||||||
<img src="img/docker_settings.png">
|
|
||||||
|
|
||||||
#### Share drives in Docker settings
|
|
||||||
Tis is an important and required configuration step in order to build the bits from the build-container so it has access to the solution files.<p>
|
|
||||||
You need to share the drives from Settings-> Shared Drives in the "Docker for Windows" configuration.
|
|
||||||
If you don't do this, you will get an error when trying to build from te container, like "Cannot create container for service yourApplication: C: drive is not shared". <p>
|
|
||||||
The drive you'll need to share depends on where you place your source code.
|
|
||||||
|
|
||||||
<img src="img/docker_settings_shared_drives.png">
|
|
||||||
|
|
||||||
**NOTE**: If you are using **Windows 10 Creators Update** (Windows 10 Creators Update, version 1703, codenamed "Redstone 2") **and your machine is joined to a Windows or Azure Domain**, you might get some issues when configuring the share drives for Docker. Providing a local user credential (from your actual machine) instead of a Windows/Azure Domain user credential might solve the issue.
|
|
||||||
Check the following blog post for additional workarounds:
|
|
||||||
https://blogs.msdn.microsoft.com/stevelasker/2016/06/14/configuring-docker-for-windows-volumes/
|
|
||||||
|
|
||||||
### IMPORTANT: Open ports in local Firewall so Authentication to the STS (Security Token Service container) can be done through the 10.0.75.1 IP which should be available and already setup by Docker. Also needed for client remote apps like Xamarin app or SPA app in remote browser.
|
|
||||||
- You can manually create a rule in your local firewall in your development machine or you can also create that rule by just executing the <b>add-firewall-rules-for-sts-auth-thru-docker.ps1</b> script available in the solution's **cli-windows** folder.
|
|
||||||
- Basically, you need to open the ports 5100 to 5105 that are used by the solution by creating an IN-BOUND RULE in your firewall, as shown in the screenshot below (for Windows).
|
|
||||||
<img src="img/firewall-rule-for-eshop.png">
|
|
||||||
|
|
||||||
### .NET Core SDK setup
|
|
||||||
(OPTIONAL) As mentioned, this requirement is optional because when building through the "build container" it will be using the .NET SDK available within the ASPNETCore build image, not the local .NET Core SDK. However, it is recommended to have it installed locally for any further building/testing of the ASP.NET Core projects without Docker.
|
|
||||||
The .NET Core SDK install the .NET Core framework plus the SDK CLI tools with commands like "dotnet build", "dotnet publish", etc.
|
|
||||||
|
|
||||||
Install the .NET Core SDK from here
|
|
||||||
https://www.microsoft.com/net/download/core#/current
|
|
||||||
(Current/x64 .NET Core 1.1 SDK Installer, usually)
|
|
||||||
|
|
||||||
Run the setup like in the following screenshot:
|
|
||||||
<img src="img/netcore-sdk-11-installer.png">
|
|
||||||
|
|
||||||
### Install NPM
|
|
||||||
In order to be able to build the JavaScript dependencies from command line by using npm you need to install npm globally.
|
|
||||||
|
|
||||||
NPM is bundled with NODE.JS. Installing NPM and NODE is pretty straightforward by using the installer package available at https://nodejs.org/en/
|
|
||||||
|
|
||||||
<img src="img/spa/installing_npm_node.png">
|
|
||||||
You can install the version "Recommended For Most Users" of Node which at the moment of this writing was v6.10.0 LTS.
|
|
||||||
|
|
||||||
<img src="img/Node_setup_for_npm.png">
|
|
||||||
|
|
||||||
<p>
|
|
||||||
After installing Node, you can check the installed NPM version with the command <b>npm -v</b>, as shown below.
|
|
||||||
<p>
|
|
||||||
<img src="img/spa/npm-versions-powershell.png">
|
|
||||||
|
|
||||||
### Install Bower
|
|
||||||
Bower is needed by minor dependencies at the MVC web app. It using Visual Studio, VS will handle that. But if using the CLI in Windows, you need to install Bower globally by running the following NPM command:
|
|
||||||
|
|
||||||
`npm install -g bower `
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## Clone the eShopOnContainers GitHub code Repository into your dev machine
|
|
||||||
|
|
||||||
Clone the code from: https://github.com/dotnet/eShopOnContainers.git
|
|
||||||
as in the following screenshot:
|
|
||||||
<img src="img/cli-windows/git-clone-powershell.png">
|
|
||||||
|
|
||||||
## Get NPM dependencies for the SPA application
|
|
||||||
|
|
||||||
Move to the SPA app folder (`cd eShopOnContainers\src\Web\WebSPA`) and run `npm install`
|
|
||||||
<img src="img/spa/npm-install_full.png">
|
|
||||||
|
|
||||||
Then, run the command `npm run build:prod` as shown below:
|
|
||||||
<img src="img/spa/npm-run-build-prod.png">
|
|
||||||
|
|
||||||
After a successful execution of those npm commands, move to the next step.
|
|
||||||
If you have any issue here, read the [Setting the Web SPA application up](https://github.com/dotnet/eShopOnContainers/wiki/06.-Setting-the-Web-SPA-application-up) for further details.
|
|
||||||
|
|
||||||
## Build the bits through the build container image
|
## Build the bits through the build container image
|
||||||
|
|
||||||
@ -190,7 +205,8 @@ When running `docker-compose up` you should see something similar to the followi
|
|||||||
Those Docker images are the ones you have available in your local image repository in your machine.
|
Those Docker images are the ones you have available in your local image repository in your machine.
|
||||||
You might have additional images, but at least, you should see the following list of images which are 6 custom images starting with the prefix "eshop" which is the name of the image repo. The rest of the images that are not starting with "eshop" will probably be official base-images like the microsoft/aspnetcore or the SQL Server for Linux images.
|
You might have additional images, but at least, you should see the following list of images which are 6 custom images starting with the prefix "eshop" which is the name of the image repo. The rest of the images that are not starting with "eshop" will probably be official base-images like the microsoft/aspnetcore or the SQL Server for Linux images.
|
||||||
|
|
||||||
### Build using the CLI scripts
|
|
||||||
|
# Option B. Approach building bits from your local Windows dev-machine by using CLI scripts
|
||||||
|
|
||||||
Althought using the build container is the recommended approach, we provide powershell scripts for using directly from windows CLI. You can find them in `/cli-windows` folder:
|
Althought using the build container is the recommended approach, we provide powershell scripts for using directly from windows CLI. You can find them in `/cli-windows` folder:
|
||||||
|
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user