Merge branch 'master' of https://github.com/dotnet/eShopOnContainers.wiki

.vs/VSWorkspaceState.json

@@ -2,6 +2,6 @@
   "ExpandedNodes": [
     ""
   ],
-  "SelectedNode": "\\02.-Setting-eShopOnContainer-solution-up-in-a-Visual-Studio-2017-environment.md",
+  "SelectedNode": "\\03.-Setting-the-eShopOnContainers-solution-up-in-a-Windows-CLI-environment-(dotnet-CLI,-Docker-CLI-and-VS-Code).md",
   "PreviewInSolutionExplorer": false
 }

02.-Setting-eShopOnContainer-solution-up-in-a-Visual-Studio-2017-environment.md

@@ -1,4 +1,20 @@
-## Setting eShopOnContainers up in a Visual Studio 2017 development machine
+## Want to try it out from Visual Studio 2017?
+
+Main steps:
+ 
+```
+- Git clone https://github.com/dotnet/eShopOnContainers.git 
+- Open solution eShopOnContainers-ServicesAndWebApps.sln
+- Hit F5!
+```
+NOTE: In order for the authentication based on the STS (Security Token Service) to properly work and have access from remote client apps like the Xamarin mobile app, you also need to open the ports in your firewall as specified in the procedure below.
+For further instructions, especially if this is the first time you are going to try .NET Core on Docker, see the detailed instructions below.
+
+--------------------------------------------------------------------
+--------------------------------------------------------------------
+
+
+## Detailed procedure: Setting eShopOnContainers up in a Visual Studio 2017 development machine
 Visual Studio 2017 with its built-in Docker Tools adds a number of very convenient features which are solid reasons why you'd want to use VS 2017 when developing Docker container based applications. The most important features are:
 * Multi-container debugging, supporting true microservice scenarios
 * Windows Server Containers for .NET Framework apps
@@ -46,8 +62,8 @@ The drive you'll need to share depends on where you place your source code.
 <img src="img/docker_settings_shared_drives.png">
 
 
-### IMPORTANT: Open ports in 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
+### 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-docker.ps1</b> script in the solution's root folder. 
+- 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-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"> 
 

03.-Setting-the-eShopOnContainers-solution-up-in-a-Windows-CLI-environment-(dotnet-CLI,-Docker-CLI-and-VS-Code).md

@@ -1,22 +1,42 @@
-## Setting eShopOnContainers up in a CLI and Windows based development machine
+## Want to try it out from the CLI?
+
+Main steps:
+ 
+```
+- Git clone https://github.com/dotnet/eShopOnContainers.git
+- Docker-compose -f docker-compose.build.ci.yml up
+- Docker-compose up
+```
+NOTE: In order for the authentication based on the STS (Security Token Service) to properly work and have access from remote client apps like the Xamarin mobile app, you also need to open the ports in your firewall as specified in the procedure below.
+For further instructions, especially if this is the first time you are going to try .NET Core on Docker, see the detailed instructions below.
+
+--------------------------------------------------------------------
+--------------------------------------------------------------------
+
+## 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.
+<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.
+
+### 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
+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 build container to use is based on the `image: microsoft/aspnetcore-build:1.0-1.1` ASP.NET Core build image which includes the .NET SDK, NPM and many other Web and ASP.NET dependencies (Gulp, Bower, etc.) to build your services and web apps.
+See building procedure below.
 
-### GitHub branch to use
-As of February 20th, the branch to use with .NET Core CLI and Docker CLI with .CSPROJ projects support is the branch: vs2017 :
-https://github.com/dotnet/eShopOnContainers/tree/vs2017  
-(It is the same code than used with VS 2017)
 
 ### Software requirements
-Software installation requirements for a Windows dev machine with CLI SDKs, Docker for Windows and Visual Studio Code or any other editor.
+Software installation requirements for a Windows dev machine with CLI SDKs, "Docker for Windows" and Visual Studio Code or any other editor.
 
 WINDOWS DEV MACHINE
 - <a href='https://docs.docker.com/docker-for-windows/install/'>Docker for Windows</a>. Important, follow the concrete configuration specified in the steps below.
-- <a href='https://www.microsoft.com/net/download/core#/current'>.NET Core SDK</a> - (Latest version. As of February 2017, using .NET 1.1 SDK)
+- <a href='https://git-for-windows.github.io/'>Git for Windows</a>. Have your preferred way to install and have available the git command line tool. Either <a href='https://git-for-windows.github.io/'>Git for Windows</a> or <a href='https://desktop.github.com/'>Git for Desktop</a> can also work.
+- <a href='https://www.microsoft.com/net/download/core#/current'>.NET Core SDK</a> - Latest version. As of early March 2017, using .NET 1.1 SDK. Note that 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.
 - <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>  
-
-This environment means that you want to build/run by using the CLI (Command line interface plus PowerShell scripts and "docker-compose up/build" CLI).
-
-Because in this environment you need to build the .NET projects from the dotnet CLI plus being able to build the docker images with docker-compose build, there are some SDKs that need to be available from the command line and you need to install and configure so commands are available from the cmd context.
 
 ## Setting up the development environment
 
@@ -33,29 +53,29 @@ Docker for Windows uses Hyper-V to run a Linux VM which is the by default Docker
 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 VS 2017 or "docker-compose up".
+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 this configuration if you also want to run the Android emulator for the Xamarin app or multiple instances of applications demanding significant memory at the same time. If you have a less powerful machine, you can try with a lower configuration and/or by not starting certain containers like the basket and Redis. But if you don't start all the containers, the application will not fully function properly, of course. 
+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 (In order to deploy and debug with Visual Studio 2017)
+#### Share drives in Docker settings 
-(Note, this is not required if running from Docker CLI with docker-compose up and using VS 2015 or any other IDE or Editor)<p>
+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>
-In order to deploy/debug from Visual Studio 2017, you'll need to share the drives from Settings-> Shared Drives in the "Docker for Windows" configuration.
+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 deploy/debug from VS 2017, like "Cannot create container for service yourApplication: C: drive is not shared". <p>
+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">
 
 
-### IMPORTANT: Open ports in 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
+### 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-docker.ps1</b> script in the solution's root folder. 
+- 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-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
-You need the .NET Core SDK so you can run the .NET Core CLI with commands like "dotnet build", "dotnet publish", etc.
+(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
@@ -64,57 +84,57 @@ https://www.microsoft.com/net/download/core#/current
 Run the setup like in the following screenshot:
 <img src="img/netcore-sdk-11-installer.png"> 
 
-### Node, Bower and Gulp installation
+### Install NPM
-Before building the .NET and JS bits, and specifically when generating the web apps binaries with "dotnet build" and "dotnet publish" from the custom scripts (like when running the build-bits.ps1 script from PowerShell), it needs to have access to the paths where you have installed Bower and Gulp. For that, the recommendation is to install Bower and Gulp with a global installation by running the following commands from command-line or bash:
+In order to be able to build the JavaScript dependencies from command line by using npm you need to install npm globally.
-- Install Node if you don't have it installed, from here: https://nodejs.org/en/ 
- <img src="img/Node_setup_for_npm.png">
-- NOTE: After installing Node, **if you are also using the full Visual Studio 2017**, you need to align that installed version with the version used by Visual Studio, so you need to make sure that VS2017 is using the same nodejs that you are using from command line.<br>
-**Go to "Tools -> Options -> Project and Solutions -> Web Package Management -> External Web Tools"** and ensure that the nodejs you use from command line is listed before the entry "$(VSINSTALLDIR)\Web\External"
-- Install Bower and Gulp with the following npm commands (npm is installed as part of Node)
 
-    `npm install -g bower` 
+NPM is bundled with NODE.JS. Installing NPM and NODE is pretty straightforward by using the installer package available at https://nodejs.org/en/
 
-    `npm install -g gulp`
+<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.
 
-Below you can see how those commands are run in Windows:
+<img src="img/Node_setup_for_npm.png">
-<img src="img/Bower_and_Gulp_setup.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">
+
+## 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">
+After a successful execution of npm intall, move to the next step.
 
 
-## Build, Ship, Run 
+## Build the bits through the build container image 
-Within eShopOnContainers' root directory you will find the scripts needed to build the .NET bits of the application which under the covers are using the .NET Core CLI (dotnet). Afterwards, you'll be able to use "docker-compose up/build" to deploy to your local Docker host. <br>
-The steps are the following: 
 
-### Build the SPA web app Angular/TypeScript/JavaScript code
+This step is very much simplified thanks to the mentioned compilation process based on a build-container using the image `image: microsoft/aspnetcore-build:1.0-1.1` ASP.NET Core build image which includes the .NET SDK, NPM and many other Web and ASP.NET dependencies (Gulp, Bower, etc.) to build your services and web apps. 
-In order to build and test the SPA web app in addition to the regular MVC app and microservices, you need to follow the steps in this link before continuing: <br>
-**Setting up the SPA web application**
-https://github.com/dotnet/eShopOnContainers/wiki/06.-Setting-the-Web-SPA-application-up
-<br>(You will only need to run these steps in the SPA link once, because the script below is also running the "npm build" command triggered by the .csproj file).
 
-### Compile the .NET apps and publish the bits in the publish folders
+Move to the root folder of the solution: <p> 
+`cd YourPath\eShopOnContainers\`
+<p>
+Then, run the following docker-compose command which is using a special docker-compose file (docker-compose.ci.build.yml) which internally is spinning up the mentioned "build container".
 
-These steps are easily performed by running a convenient script already created for you. As mentioned, it is internally using the .NET Core CLI (dotnet).
+`docker-compose -f docker-compose.ci.build.yml up`
-- Open a PowerShell window in Windows. Make sure that you have permission to run scripts by running the following command:
+<img src="img/cli-windows/docker-compose-pulling-aspnetbuild-image.png">
-    `Set-ExecutionPolicy Unrestricted -Scope LocalMachine`
-    <img src="img/cli-windows/powershell-set-execution-policy.png">
 
-- There is a Power-Shell script that you will find in the <u>root directory of the solution</u> named <b>build-bits.ps1</b> which is responsible for building the .NET applications and copy the binaries into multiple publish folder.
+The first time you run this command it'll take some more additional time as it needs to pull/download the aspnet-build image with all the SDKs as part of that build-image, so it'll take its time.
+<p>
+It should take a few minutes to compile the .NET Core projects plus the SPA application (TypeScript/JavaScript).
+It should end with something like the following screenshot:
 
-    Move to the root folder of your solution (like yourPath\eShopOnContainers) and run the <b>build-bits.ps1</b> script file, which will compile the .NET Core projects and publish the bits in each project's publish folder within "project-folder\obj\Docker\publish" (per project), like in the following screenshots.
+<img src="img/cli-windows/docker-compose-ci-compose-file-ending.png">
-
-    PowerShell to run:
-    <img src="img/cli-windows/build-bits-1.png">
-
-    Below you see the **build-bits.ps1** execution after compiling the .NET Core projects and publishing the bits into the publish folders:
-    <img src="img/cli-windows/build-bits-2.png">
-
-    Note that this script will also delete previous eShop/* docker images and any container that you might have created in your local Docker repository, so afterwards when running "docker-compose up/build" it will start from a clean state in regards the eShop images.
-
-    You can check how in every project, under the folder "project-folder\obj\Docker\publish" (per project) the script generated the bits/binaries to be packaged as a Docker image and deployed as a container, afterwards:
-
-    <img src="img/cli-windows/build-bits-3-catalog-bits.png">
 
+At this point you have the .NET bits ready. Now, create the Docker images and run the containers.
 
 ### Build Images and Deploy containers into your Docker host
+
 You can build the Docker images and deploy the containers to a regularDocker host by using the Docker CLI tool `docker-compose up` which is very convenient for multi-container applications as it can build all the Docker images for you and then spin-up all the multiple containers of your application, all with a single command.
 If you don't want to deploy the containers but only build the images, you can do so by running `docker-compose build`
 These are the steps:
@@ -224,3 +244,26 @@ By default, the Xamarin app shows fake data from mock-services. In order to real
 - In addition, you need to make sure that the used TCP ports of the services are open in the local firewall. <img src="img/xamarin-settings.png">
 
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

06.-Setting-the-Web-SPA-application-up.md

@@ -9,7 +9,7 @@ In order to be able to build the JavaScript dependencies from command line by us
 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.9.3 LTS and comes with a newer version of NPM.
+You can install the version "Recommended For Most Users" of Node which at the moment of this writing was v6.10.0 LTS.
 You can see the installed NPM version with the command <b>npm -v</b>, as shown below.
 <p>
 <img src="img/spa/npm-versions-powershell.png">
@@ -57,8 +57,7 @@ At this point, if you were originally following the eShopOnContainer setup for a
 
 1. **VS 2017 based:** Build and deploy in a single step from Visual Studio 2017 as explained in this page: https://github.com/dotnet/eShopOnContainers/wiki/02.-Setting-eShopOnContainer-solution-up-in-a-Visual-Studio-2017-environment
 
-2. **CLI on Windows:** Build the .NET bits with the dontnet CLI by using the Windows PowerShell script build-bits.ps1, then create the Docker images and deploy to the Docker host with "docker compose up/build", as explained in this page: https://github.com/dotnet/eShopOnContainers/wiki/03.-Setting-the-eShopOnContainers-solution-up-in-a-Windows-CLI-environment-(dotnet-CLI,-Docker-CLI-and-VS-Code)
+2. **CLI on Windows:** Build the .NET bits with the build-container based on dontnet CLI and Docker CLI, as explained in this page: https://github.com/dotnet/eShopOnContainers/wiki/03.-Setting-the-eShopOnContainers-solution-up-in-a-Windows-CLI-environment-(dotnet-CLI,-Docker-CLI-and-VS-Code)
 
-3. **CLI on Mac:** Build the .NET bits with the dontnet CLI by using the Mac Bash script 
+3. **CLI on Mac:** Build the .NET bits with the build-container based on dontnet CLI and Docker CLI, as explained in this page: https://github.com/dotnet/eShopOnContainers/wiki/04.-Setting-eShopOnContainer-solution-up-in-a-Mac,-VS-Code-and-CLI-environment--(dotnet-CLI,-Docker-CLI-and-VS-Code)
-build-bits.sh, then create the Docker images and deploy to the Docker host with "docker compose up/build", as explained in this page: https://github.com/dotnet/eShopOnContainers/wiki/04.-Setting-eShopOnContainer-solution-up-in-a-Mac,-VS-Code-and-CLI-environment--(dotnet-CLI,-Docker-CLI-and-VS-Code)
 

Home.md

@@ -23,3 +23,6 @@ https://microsoft.sharepoint.com/teams/DotNetStrategyTeam/Shared%20Documents/Arc
 ##Issues:
 https://github.com/dotnet/eShopOnContainers/issues
 
+## Sending feedback and pull requests
+We'd appreciate to your feedback, improvements and ideas.
+You can create new issues at the issues section, do pull requests and/or send emails to eshop_feedback@service.microsoft.com