+### .NET Core SDK setup
+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:
+
### Node, Bower and Gulp installation
(These steps about installing bower and gulp might not be needed anymore as these are being triggered from the .csproj file in the MVC project at the "PrepublishScript" section). 
-- NOTE: After installing Node, if you are also using 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.+- 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.
**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) @@ -67,50 +74,117 @@ Below you can see how those commands are run in Windows: ## Build, Ship, Run -In the global directory you will find the scripts needed to build, deploy and run the application into your local Docker development machine. The steps are the following: +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.
+The steps are the following: + +### Build the SPA web app Angular/TypeScript/JavaScript code +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:
+**Setting up the SPA web application** +https://github.com/dotnet/eShopOnContainers/wiki/06.-Setting-the-Web-SPA-application-up +
(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 -These steps are easily performed by running a script. -- Open a PowerShell window in Windows, move to the root folder of your solution and run the build-bits.ps1 script file like in the following screenshot. - +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). +- Open a PowerShell window in Windows. Make sure that you have permission to run scripts by running the following command: + - **Set-ExecutionPolicy Unrestricted -Scope LocalMachine** +
+
+- There is a Power-Shell script that you will find in the root directory of the solution named build-bits.ps1 which is responsible for building the .NET applications and copy the binaries into multiple publish folder.
+
+ Move to the root folder of your solution (like yourPath\eShopOnContainers) and run the build-bits.ps1 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.
+
+ PowerShell to run:
+ 
+
+ Below you see the **build-bits.ps1** execution after compiling the .NET Core projects and publishing the bits into the publish folders:
+ 
+
+ 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:
+
+ 
+### Buil 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:
+- **Build images and run your containers in your local host:** Open your favorite command tool (PowerShell od CommandLine in Windows / Bash in Mac) and move to the root directory of the solution where the docker-compose.yml files are located and run the command `docker-compose up`. If this is the first time you run it, it will also build the docker images. Other than that, you could also force to build the images by running `docker-compose build` previously.
+When running `docker-compose up` you should see something similar to the following screenshot in the PowerShell command window, although it will much longer than that, building the images the first time and showing many internal SQL commands from the services when populating sample data for your application.
+ `docker-compose up`
+ 
-TBD
+ Note that the first time you try to build any image or run any container (with docker run or docker-compose) it detects that it needs the base images you are using, like the SQL Server image and the Redis image, so it will pull or download those base images from the Internet, from the public repo at the Docker registry named DOCKER HUB, by pulling the "microsoft/mssql-server-linux" which is the base image for the SQL Server for Linux on containers, and the "library/redis" which is the base Redis image. Therefore, the first time you run docker-compose it might take a few minutes pulling those images before it spins up your custom containers.
+ The next time you run docker-compose up, since it'll have those base images already pulled/downloaded, it will be much faster.
-IMPORTANT: This script deletes all the Docker images registered in your local dev machine repository before creating the new images, so it is starting from a 100% clean state. If you don't want your local images in your PC to be deleted, edit and change the build-images.ps1 script file before you run it.
+ Because in eShopOnContainers' docker-compose.yml files it is also specified to build the custom Docker images, it is building it, like in the screenshot below (part of the same command execution):
+ 
-- This Power-Shell script that you will find in the root directory of the solution is responsible for building the .NET applications, copy the binaries in a pub folder and use Docker CLI commands to build the custom Docker images needed to run the containers. You can see how to run that PowerShell script in the screenshot below:
-
+ Finally, you can see how the scripts waits after deploying all the containers:
+ 
-- Once it finishes, you can check it out with Docker CLI if the images were generated correctly by typing in the PowerShell console the command: `docker images`
-
-Those Docker images are the ones you have available in your local image repository in your machine.
+- The next time you run "docker-compose up" again (you don't need to repeat it now), because now you already have all the base images downloaded and registered in your local repo and your custom images built and ready to go, it'll be much faster since it just needs to deploy the containers, like the following screenshot:
+
+
+- Check out the containers running in your Docker host: Once docker-compose up finishes, you will have the original PowerShell window busy and showing the execution's output in a "wait state", so in order to ask to Docker about "how it went" and see what containers are running, you need to open a second PowerShell window and type "docker ps" so you'll see all the running containers, as shown in the following screenshot.
+
+
+ You can see the 6 custom containers running the 4 microservices plus the 2 web applications. In addition you have the SQL container with the databases (if you had a lot of memory, you could put one database per SQL container, too) and the Redis cache for the basket microservice data.
+
+- You can also check out with Docker CLI the images generated by typing in the PowerShell console the command: `docker images`
+
+
+ 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.
-### Deploy containers into your Docker host
-You can deploy Docker containers to a regularDocker host either by using the `docker run` command which need to be executed once per microservice, or by using the CLI tool `docker-compose up` which is very convenient for multi-container applications as it can spin-up all the multiple containers in your application with a single command. These are the steps:
-- Run your containers in your local host: Open your favorite command tool (PowerShell od CommandLine in Windows / Bash in Mac) and move to the root directory of the solution where the docker-compose.yml file is located and run the command `docker-compose up`. When running "docker-compose up" you should see something similar to the following screenshot in the PowerShell command window, although it will much longer than that, also showing many internal SQL commands from the services when populating the first time the sample data.
-`docker-compose up`
-
+### Test the MVC Web app
+Open a browser and type `http://localhost:5100/` and hit enter.
+You should see the MVC application like in the following screenshot:
-- Note that the first time you run any container (with docker run or docker-compose) it detects that it needs the base images we are using, like the SQL Server image and the Redis image, so it will pull or download those base images from the Internet, from the public repo at the Docker registry named DOCKER HUB, by pulling the "microsoft/mssql-server-linux" which is the base image for the SQL Server for Linux on containers, and the "library/redis" which is the base Redis image. Therefore, the first time you run docker-compose it might take a few minutes pulling those images before it spins up your custom containers.
-The next time you run docker-compose up, since it'll have those base images already pulled/downloaded, it will just start the containers, like in the following screenshot:
-
-
-- Check out the containers running in your Docker host: Once docker-compose up finishes after a few minutes, you will have that PowerShell showing the execution's output in a "wait state", so in order to ask to Docker about "how it went" and see what containers are running, you need to open a second PowerShell window and type "docker ps" so you'll see all the running containers, as shown in the following screenshot.
-
-You can see the 6 custom containers running the microservices plus the 2 web applications. In adition you have the containers with the SQL databases and the Redis cache for the basket microservice data.
+
+- +### Test the SPA Web app +Open a browser and type `http://localhost:5104/` and hit enter. +You should see the SPA application like in the following screenshot: + +
+-### Test the applications and microservices -Once the deploy process of docker-compose finishes you should be able to access the services in the following URLs or connection string, from your dev machine: +### Test a microservice's Swagger interface (i.e. the Catalog microservice) +Open a browser and type `http://localhost:5101` and hit enter. +You should see the Swagger page for that microservice that allows you to test the Web API, like in the following screenshot: + +
+
+Then, after providing the size (i.e. 10) and the current page (i.e. 1) for the data of the catalog, you can run the service hitting the "Try it out!" button and see the returned JSON Data:
+
+
++ +### Using Visual Code to edit C# code or .yml code +After installing VS code from Visual Studio Code you can edit particular file or "open" the whole solution forlder 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:
+
+
+
+----
+
+### Testing all the applications and microservices
+Once the containers are deployed, you should be able to access any of the services in the following URLs or connection string, from your dev machine:
- Web MVC: http://localhost:5100
@@ -124,22 +198,22 @@ Once the deploy process of docker-compose finishes you should be able to access
- ASP.NET Identity database (SQL Server connection string): Server=localhost,5433;Database=aspnet-Microsoft.eShopOnContainers;User Id=sa;Password=Pass@word
- Basket data (Redis): listening at localhost:6379
-#### Trying the Web MVC application with the DemoUser@microsoft.com user account
-When you try the Web MVC application by using the url http://localhost:5100, you'll be able to test the home page which is also the catalog page. But when trying to add any article to the basket you will get redirected to the login page which is handled by the STS microservice (Security Token Service). At this point, you could register your own user/customer or you can also use a convenient default user/customer named DemoUser@microsoft.com so you don't need to register your own user and it'll be easier to test.
+#### Creating and Order and Authenticating on the Web MVC application with the DemoUser@microsoft.com user account
+When you try the Web MVC application by using the url http://localhost:5100, you'll be able to test the home page which is also the catalog page. But if you want to add articles to the basket you need to login first at the login page which is handled by the STS microservice/container (Security Token Service). At this point, you could register your own user/customer or you can also use a convenient default user/customer named **demoUser@microsoft.com** so you don't need to register your own user and it'll be easier to test.
The credentials for this demo user are:
-- User: demouser@microsoft.com
-- Password: Pass@word1
+- User: **demouser@microsoft.com**
+- Password: **Pass@word1**
Below you can see the login page when providing those credentials.
#### Trying the Xamarin.Forms mobile apps for Android, iOS and Windows
-By default, this app shows fake data from mock-services. In order to really access the microservices/containers in Docker from the mobile app, you need to:
+You can deploy the Xamarin app to real iOS, Android or Windows devices.
+You can also test it on an Android Emulator based on Hyper-V like the Visual Studio Android Emulator (Do NOT install the Google's Android emulator or it will break Docker and Hyper-V, as mentioned aboce).
+
+By default, the Xamarin app shows fake data from mock-services. In order to really access the microservices/containers in Docker from the mobile app, you need to:
- Disable mock-services in the Xamarin app by setting the UseMockServices = false in the App.xaml.cs and specify the host IP in BaseEndpoint = "http://10.106.144.28" at the GlobalSettings.cs. Both files in the Xamarin.Forms project (PCL).
- Another alternative is to change that IP through the app UI, by modifying the IP address in the Settings page of the App as shown in the screenshot below.
- In addition, you need to make sure that the used TCP ports of the services are open in the local firewall. 
-### Deploying individiual services into Docker
-Under each project root you will find a readme.md file which describes how to run and deploy the service individually into a docker host.
-
diff --git a/06.-Setting-the-Web-SPA-application-up.md b/06.-Setting-the-Web-SPA-application-up.md
index 8bd7bb7..c3ea41b 100644
--- a/06.-Setting-the-Web-SPA-application-up.md
+++ b/06.-Setting-the-Web-SPA-application-up.md
@@ -15,12 +15,13 @@ You can see the installed NPM version with the command npm -v, as shown b
### Set NPM path into Visual Studio
-NPM will be usually installed under this path:
-C:\Program Files (x86)\nodejs.
-You need to update that path in Visual Studio under the "External Web Tools" location paths, as shown below:
+This step is only required if you are also using the full Visual Studio 2017.
+NPM (just instelled by you) will be usually installed under this path:
+C:\Program Files\nodejs.
+You need to update that path in Visual Studio under the "External Web Tools" location paths, as shown below:
-If you don't do this step you might have issues because of using different versions from VS or command line.
+If you don't do this step you might have issues because of using different versions from VS versus the command line accessing the same JavaScript code from both environments.
See:
http://www.hanselman.com/blog/VisualStudio2015FixingDependenciesNpmNotInstalledFromFseventsWithNodeOnWindows.aspx
@@ -28,20 +29,23 @@ http://www.hanselman.com/blog/VisualStudio2015FixingDependenciesNpmNotInstalledF
### Build the SPA app with NPM
Now, you need to build the SPA app (TypeScript and Angular 2 based client app) with NPM.
* Open a command-prompt window and move to the root of the SPA application (src\Web\WebSPA\eShopOnContainers.WebSPA)
-* Run the command npm run build:prod as shown below:
+* Run the command npm install as shown below:
+* Then, run the command npm run build:prod as shown below:
+
If you get an error like "Node Sass could not find a binding for your current environment: Windows 64-bit with Node.js 6.x", then run the command npm rebuild node-sass as in the following screenshot:
Then, run again the npm run build:prod command that should finish with no errors.
+
+
### Build the Docker images and Deploy the containers
-At this point you can choose between any of the two following options to build and deploy the Docker containers:
-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/Setting-eShopOnContainer-solution-up-in-a-Visual-Studio-2017-environment
-2. CLI in 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/Setting-the-eShopOnContainers-solution-up-in-a-Windows-CLI-environment-(dotnet-CLI,-Docker-CLI-and-VS-Code)
-3. CLI in Mac: Build the .NET bits with the dontnet CLI by using the Mac Bash script
+At this point, if you were originally following the eShopOnContainer setup for any environment and came to this page just to setup the SPA app, now go back to your original setup instructions page. Other than that, you can in any case choose between any of the following options to build and deploy the Docker containers:
+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/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/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
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/Setting-eShopOnContainer-solution-up-in-a-Mac,-VS-Code-and-CLI-environment
diff --git a/img/cli-windows/build-bits-1.png b/img/cli-windows/build-bits-1.png
new file mode 100644
index 0000000..28689c5
Binary files /dev/null and b/img/cli-windows/build-bits-1.png differ
diff --git a/img/cli-windows/build-bits-2.png b/img/cli-windows/build-bits-2.png
new file mode 100644
index 0000000..d1261d7
Binary files /dev/null and b/img/cli-windows/build-bits-2.png differ
diff --git a/img/cli-windows/build-bits-3-catalog-bits.png b/img/cli-windows/build-bits-3-catalog-bits.png
new file mode 100644
index 0000000..e637696
Binary files /dev/null and b/img/cli-windows/build-bits-3-catalog-bits.png differ
diff --git a/img/cli-windows/docker-compose-up-1.1.png b/img/cli-windows/docker-compose-up-1.1.png
new file mode 100644
index 0000000..0a2b7bc
Binary files /dev/null and b/img/cli-windows/docker-compose-up-1.1.png differ
diff --git a/img/cli-windows/docker-compose-up-1.2.png b/img/cli-windows/docker-compose-up-1.2.png
new file mode 100644
index 0000000..08bfa51
Binary files /dev/null and b/img/cli-windows/docker-compose-up-1.2.png differ
diff --git a/img/cli-windows/docker-compose-up-1.png b/img/cli-windows/docker-compose-up-1.png
new file mode 100644
index 0000000..649719c
Binary files /dev/null and b/img/cli-windows/docker-compose-up-1.png differ
diff --git a/img/cli-windows/docker-compose-up-2.png b/img/cli-windows/docker-compose-up-2.png
new file mode 100644
index 0000000..fb086d2
Binary files /dev/null and b/img/cli-windows/docker-compose-up-2.png differ
diff --git a/img/cli-windows/docker-ps-with-all-microservices.png b/img/cli-windows/docker-ps-with-all-microservices.png
new file mode 100644
index 0000000..ad9757a
Binary files /dev/null and b/img/cli-windows/docker-ps-with-all-microservices.png differ
diff --git a/img/cli-windows/list-of-images.png b/img/cli-windows/list-of-images.png
new file mode 100644
index 0000000..1937f1b
Binary files /dev/null and b/img/cli-windows/list-of-images.png differ
diff --git a/img/cli-windows/powershell-set-execution-policy.png b/img/cli-windows/powershell-set-execution-policy.png
new file mode 100644
index 0000000..b1aa25b
Binary files /dev/null and b/img/cli-windows/powershell-set-execution-policy.png differ
diff --git a/img/cli-windows/vs-code-1.png b/img/cli-windows/vs-code-1.png
new file mode 100644
index 0000000..62f661f
Binary files /dev/null and b/img/cli-windows/vs-code-1.png differ
diff --git a/img/cli-windows/vs-code-2.png b/img/cli-windows/vs-code-2.png
new file mode 100644
index 0000000..ff93b7e
Binary files /dev/null and b/img/cli-windows/vs-code-2.png differ
diff --git a/img/cli-windows/vs-code-3-extensions.png b/img/cli-windows/vs-code-3-extensions.png
new file mode 100644
index 0000000..e5d6773
Binary files /dev/null and b/img/cli-windows/vs-code-3-extensions.png differ
diff --git a/img/docker-compose-up-1.png b/img/docker-compose-up-1.png
deleted file mode 100644
index 6aa3b1c..0000000
Binary files a/img/docker-compose-up-1.png and /dev/null differ
diff --git a/img/docker-compose-up-2.png b/img/docker-compose-up-2.png
deleted file mode 100644
index 705d839..0000000
Binary files a/img/docker-compose-up-2.png and /dev/null differ
diff --git a/img/spa/npm-run-build-prod-no-errors.png b/img/spa/npm-run-build-prod-no-errors.png
new file mode 100644
index 0000000..31cc9ee
Binary files /dev/null and b/img/spa/npm-run-build-prod-no-errors.png differ
diff --git a/img/spa/npm-run-build-prod.png b/img/spa/npm-run-build-prod.png
new file mode 100644
index 0000000..3aede95
Binary files /dev/null and b/img/spa/npm-run-build-prod.png differ
diff --git a/img/swagger-catalog-1.png b/img/swagger-catalog-1.png
new file mode 100644
index 0000000..03538dc
Binary files /dev/null and b/img/swagger-catalog-1.png differ
diff --git a/img/swagger-catalog-2.png b/img/swagger-catalog-2.png
new file mode 100644
index 0000000..ff30a37
Binary files /dev/null and b/img/swagger-catalog-2.png differ