ayan.poddar/eShopOnContainers
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

bullets added..

Cesar De la Torre 2017-03-06 17:32:34 -08:00
parent b2ee3ae28c
commit d30f353f74
3 changed files with 3 additions and 274 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
.vs/slnx.sqlite

Binary file not shown.

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

@ -3,9 +3,9 @@
Main steps:
 
```
Git clone https://github.com/dotnet/eShopOnContainers.git
Docker-compose -f docker-compose.build.ci.yml up
Docker-compose up
- 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 detailed instructions, especially if this is the first time you are going to try .NET Core on Docker, see the detailed instructions below.

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

@ -1,271 +0,0 @@
## 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 detailed 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.
### Software requirements
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://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>
## 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">
### 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 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">
## 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 the bits through the build container image
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.
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".
`docker-compose -f docker-compose.ci.build.yml up`
<img src="img/cli-windows/docker-compose-pulling-aspnetbuild-image.png">
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:
<img src="img/cli-windows/docker-compose-ci-compose-file-ending.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:
- **Build images and run your containers in your local host:** Open your favorite command tool (PowerShell od CommandLine in Windows / Bash in Mac) <u> and move to the root directory of the solution</u> 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`
<img src="img/cli-windows/docker-compose-up-1.png">
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.
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):
<img src="img/cli-windows/docker-compose-up-1.1.png">
Finally, you can see how the scripts waits after deploying all the containers:
<img src="img/cli-windows/docker-compose-up-1.2.png">
- 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:
<img src="img/cli-windows/docker-compose-up-2.png">
- <b>Check out the containers running in your Docker host</b>: 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.
<img src="img/cli-windows/docker-ps-with-all-microservices.png">
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`
<img src="img/cli-windows/list-of-images.png">
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.
### 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:
<img src="img/eshop-webmvc-app-screenshot.png">
<br>
### 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:
<img src="img/eshop-webspa-app-screenshot.png">
<br>
### 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:
<img src="img/swagger-catalog-1.png">
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:
<img src="img/swagger-catalog-2.png">
<br>
### Using Visual Code to edit C# code or .yml code
After installing VS code from <a href='https://code.visualstudio.com/'>Visual Studio Code</a> you can edit particular file or "open" the whole solution forlder like in the following screenshots:
`Opening the Solution's folder`
<img src="img/cli-windows/vs-code-1.png">
`Editing a .yml file`
<img src="img/cli-windows/vs-code-2.png">
It is also recommended to install the C# extension and the Docker extension for VS Code:
<img src="img/cli-windows/vs-code-3-extensions.png">
----
### 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:
<a href="" target="top"></a>
- Web MVC: <a href="http://localhost:5100" target="top">http://localhost:5100</a>
- Web Spa: <a href="http://localhost:5104" target="top">http://localhost:5104</a> (Important, check how to set up the SPA app and requirements before building the Docker images. Instructions at https://github.com/dotnet/eShopOnContainers/tree/master/src/Web/WebSPA/eShopOnContainers.WebSPA or the README.MD from eShopOnContainers/src/Web/WebSPA/eShopOnContainers.WebSPA)
- Catalog microservice: <a href="http://localhost:5101" target="top">http://localhost:5101</a> (Not secured)
- Ordering microservice: <a href="http://localhost:5102" target="top">http://localhost:5102</a> (Requires token for authorization)
- Basket microservice: <a href="http://localhost:5103" target="top">http://localhost:5103</a> (Requires token for authorization)
- Identity microservice: <a href="http://localhost:5105" target="top">http://localhost:5105</a>
- Orders database (SQL Server connection string): Server=tcp:localhost,5432;Database=Microsoft.eShopOnContainers.Services.OrderingDb;User Id=sa;Password=Pass@word;
- Catalog database (SQL Server connection string): Server=tcp:localhost,5434;Database=CatalogDB;User Id=sa;Password=Pass@word
- 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
#### 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**
Below you can see the login page when providing those credentials.
<img src="img/login-demo-user.png">
#### Trying the Xamarin.Forms mobile apps for Android, iOS and Windows
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 <b>UseMockServices = false</b> 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. <img src="img/xamarin-settings.png">