Backup of CLI deprecated pages
Cesar De la Torre
parent
d9ceb3aaa1
commit
f5aea0c96d
330
DEPRECATED/03.-Setting-the-eShopOnContainers-solution-up-in-a-Windows-CLI-environment-(dotnet-CLI,-Docker-CLI-and-VS-Code).md
Normal file
330
DEPRECATED/03.-Setting-the-eShopOnContainers-solution-up-in-a-Windows-CLI-environment-(dotnet-CLI,-Docker-CLI-and-VS-Code).md
Normal file
@ -0,0 +1,330 @@
|
||||
## Related readme files (use them for more information after reading this)
|
||||
|
||||
* [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
|
||||
|
||||
## Want to try it out from the CLI?
|
||||
|
||||
Main steps:
|
||||
|
||||
```
|
||||
- Git clone https://github.com/dotnet/eShopOnContainers.git
|
||||
- Docker-compose -f docker-compose.ci.build.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. 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
|
||||
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.
|
||||
|
||||
|
||||
## Prerequisites (Software requirements)
|
||||
|
||||
1. [Docker for Windows](https://docs.docker.com/docker-for-windows/install/). Important, follow the concrete configuration specified in the steps below.
|
||||
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.
|
||||
1. Any code editor, like [Visual Studio Code](https://code.visualstudio.com/)
|
||||
|
||||
*IMPORTANT NOTE:* When building with the Linux build-container (option A explained below) you don't really need to have installed Node, NPM, Bower or not even .NET Core SDK in your local Windows machine, as the Linux build-container has all the needed SDKs to compile the projects. However, we recommend to have it installed on Windows so you can do further development and testing.
|
||||
|
||||
# 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):*
|
||||
|
||||
This is the simplest way to do it from the CLI, but if you get the following error when compiling from the Linux build-container:
|
||||
|
||||
`MSBUILD : error MSB4017: The build stopped unexpectedly because of an unexpected logger failure.`
|
||||
`ci-build_1 | Microsoft.Build.Exceptions.InternalLoggerException: The build stopped unexpectedly because of an unexpected logger failure. ---> System.IO.IOException: The process cannot access the file because it is being used by another process.`
|
||||
|
||||
That is a [bug in .NET CLI when running "dotnet publish" within a container](https://github.com/Microsoft/msbuild/issues/2153#issuecomment-305375162).
|
||||
|
||||
If you get this issue, until the fix is released by the dotnet CLI team in the next version of the .NET CLI, in the meantime, 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.).
|
||||
|
||||
<img src="img/building-bits_from_ci_container.png">
|
||||
|
||||
<p>
|
||||
|
||||
The build container to use is based on the `image: microsoft/aspnetcore-build` 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.
|
||||
|
||||
## Build the bits through the Linux 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.
|
||||
|
||||
If you had issues when trying to build your .NET Core binaries with the build-container, because of the mentioned issue/bug above, then try this second choice: Option B.
|
||||
|
||||
# Option B. Approach building bits from your local Windows dev-machine by using CLI scripts
|
||||
|
||||
Although 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:
|
||||
|
||||
. `build-bits.ps1`: Build all projects and left them published in /obj/Docker/publish. This is more or less the same that using the build container does.
|
||||
. `build-images.ps1`: Build all Docker images. **Images are tagged using the git branch you were when this script is running**. That allows you have docker images for various branches at same time. You can use the parameter `-imageTag myTag` to force use a specific `myTag`.
|
||||
. `delete-images.ps1`: Removes all eShop docker images. Other images used by eShop, but downloaded directly from DockerHub (like sql server) aren't deleted.
|
||||
|
||||
So for building all projects using the CLI:
|
||||
|
||||
```
|
||||
cd cli-windows
|
||||
.\build-bits.ps1
|
||||
```
|
||||
|
||||
This script will **compile and publish all your projects and then delete all docker images**. When this script finishes you should have all projects compiled and no docker images. Then you can run `.\build-images.ps1` to rebuild the Docker images.
|
||||
|
||||
# Build the Docker Images and deploy the containers into Docker
|
||||
|
||||
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">
|
||||
|
||||
## 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
|
||||
|
||||
## Questions
|
||||
[QUESTION] Answer +1 if the solution is working for you (Through VS2017 or CLI environment):
|
||||
https://github.com/dotnet/eShopOnContainers/issues/107
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
380
DEPRECATED/04.-Setting-eShopOnContainer-solution-up-in-a-Mac,-VS-for-Mac-or-with-CLI-environment--(dotnet-CLI,-Docker-CLI-and-VS-Code).md
Normal file
380
DEPRECATED/04.-Setting-eShopOnContainer-solution-up-in-a-Mac,-VS-for-Mac-or-with-CLI-environment--(dotnet-CLI,-Docker-CLI-and-VS-Code).md
Normal file
@ -0,0 +1,380 @@
|
||||
# Global prerequisite: Docker for Mac
|
||||
|
||||
Install [Docker for Mac](https://docs.docker.com/docker-for-mac/install/). The stable channel is fine.
|
||||
|
||||
## Configure Docker for Mac
|
||||
|
||||
### Docker for Mac (Linux VM) memory assigned
|
||||
The SQL Server image for Docker requires more memory to run. You will need to update your Docker settings to allocate at least 4 GB of memory:
|
||||
|
||||
|
||||
|
||||
Depending on how many apps you are running in your Mac you might need to assign more memory to Docker in the Mac. Usually, 4GB should suffice, but we got feedback from devs who needed to assign up to 8GB of ram to Docker in the Mac.
|
||||
|
||||
### Folder shares in Docker for Mac
|
||||
If your projects are placed within the /Users folder, you don't need to configure anything additional, as that is a pre-shared folder. However, if you place your projects under a different path, like /MyRootProjects, then you'd need to add that shared folder to Docker's configuration, here:
|
||||
|
||||
|
||||
|
||||
|
||||
# Option A: Use Visual Studio for Mac
|
||||
The quickest path to get eShopOnContainers running on your Mac is by using VS for Mac which will install most of the pre-requisites you need.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. [Docker for Mac](https://docs.docker.com/docker-for-mac/install/). (You should already have this installed)
|
||||
1. [Visual Studio for Mac](https://www.visualstudio.com/vs/visual-studio-mac/).
|
||||
|
||||
## Install Visual Studio for Mac
|
||||
|
||||
When installing [Docker for Mac](https://docs.docker.com/docker-for-mac/install/), you can select between multiple workloads or platforms.
|
||||
|
||||
Make sure you select the .NET Core platform:
|
||||
|
||||
|
||||
|
||||
Before completing the VS for Mac installation, it will demand you to install XCode, that is needed for multiple dependencies.
|
||||
|
||||
If you install Android as a target platform, Java will also be installed as a dependency for building mobile apps for Android.
|
||||
|
||||
For running just the Docker containers and web apps, you'd just need the .NET Core platform.
|
||||
|
||||
But if you want to try the eShopOnContainers mobile app, that requires Xamarin and therefore, the iOS and Android platforms, too. Those mobile platforms are optional for this Wiki walkthrough, though.
|
||||
|
||||
## Clone the eShopOnContainers repo
|
||||
|
||||
Open a bash shell and run the following command:
|
||||
|
||||
```
|
||||
$ mkdir MyGitRepos
|
||||
$ cd MyGitRepos
|
||||
$ git clone https://github.com/dotnet-architecture/eShopOnContainers.git
|
||||
$ cd eShopOnContainers
|
||||
```
|
||||
|
||||
With that, you'll have the code at /Users/yourUser/MyGitRepos/eShopOnContainers folder.
|
||||
|
||||
## Open the 'eShopOnContainers-ServicesAndWebApps.sln' solution with VS for Mac
|
||||
|
||||
Run Visual Studio for Mac and open the solution `eShopOnContainers-ServicesAndWebApps.sln`.
|
||||
|
||||
If you just want to run the containers/microservices and web apps, do NOT open the other solutions, like `eShopOnContainers.sln` as those solutions will also open the Xamarin projects and that might slow you down when testing due to additional dependencies in VS.
|
||||
|
||||
After opening the `eShopOnContainers-ServicesAndWebApps.sln` solution for the first time, it is recommended to wait for a few minutes as VS will be restoring many NuGet packages and the solution won't be able to compile or run until it gets all the nuGet packages dependencies, in the first place (this time is only needed the first time you open the solution. Next times it is a lot faster).
|
||||
|
||||
This is VS for Mac with the `eShopOnContainers-ServicesAndWebApps.sln` solution.
|
||||
|
||||
|
||||
|
||||
## Run eShopOnContainers from VS for Mac (F5 or Ctrl+F5)
|
||||
|
||||
Make sure that the by default start-up project is the Docker project named `docker-compose`.
|
||||
|
||||
Hit Ctrl+F5 or press the "play" button in VS for Mac.
|
||||
|
||||
IMPORTANT: The first time you run eShopOnContainers, it will take longer than the next time you launch it. Under the covers, Docker is pulling quite a few "heavy" images from Docker Hub (the public image registry), like the SQL Server image, Redis image, RabbitMQ image and the base ASP.NET Core images. That pull/download process will take a few minutes. Then, VS will launch the application custom containers plus the infrastructure containers (SQL, Redis, RabbitMQ and MongoDB), populate sample data in the databases and finally run the microservices and web apps on custom containers.
|
||||
|
||||
Note that you will see normal/controlled Http exceptions caused by our retries with exponential backoff, as the web apps have to wait until the microservices are ready for the first time which need first to run SQL sentences populating sample data, etc.
|
||||
|
||||
Once the solution is up and running, you should be able to see it in the browser at:
|
||||
|
||||
http://localhost:5100
|
||||
|
||||
|
||||
|
||||
If you open a bash window, you can type `docker images` and see the pulled/downloaded images plus the custom images created by VS for Mac:
|
||||
|
||||
|
||||
|
||||
And by typing `docker ps` you can see the containers running in Docker. The infrastructure containers like SQL, Redis, RabbitMQ plus the custom containers running Web API microservices and the web apps.
|
||||
|
||||
|
||||
|
||||
*IMPORTANT:* In order to have the full app working, like being able to login with a user and add items to the basket and create orders, or being able to consume the services from a remote Xamarin or web SPA, you need to configure additional steps for the app, like the IP to be used by the Identity Service because it needs to be redirected, etc. - Check the additional configuration at the end of this post.
|
||||
|
||||
|
||||
# Option B: Use a CLI environment (dotnet CLI, Docker CLI with the bash shell) and VS Code as plain editor
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. [Docker for Mac](https://docs.docker.com/docker-for-mac/install/). You should already have this.
|
||||
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 ($ sudo npm install -g bower) needed by the MVC web app.
|
||||
1. [.NET Core and SDK](http://dot.net). Install the SDK and runtime.
|
||||
|
||||
|
||||
## B.1 - Building the application from a Docker Linux "build container"
|
||||
|
||||
Option B.1 is the recommended way to build your binaries before creating the Docker images as you'd be using the same Linux build-container with the SDKs that you can also use for your CI/CD pipelines in your DevOps system (that is VSTS, TFS, Jenkins, etc.).
|
||||
However, take into account the note below if you have that issue.
|
||||
|
||||
---
|
||||
|
||||
*IMPORTANT NOTE (as of Oct. 2017):*
|
||||
|
||||
This is the simplest way to do it from the CLI, and with the latest tests using the Docker build-container image with SDKs, microsoft/aspnetcore-build:2.0.2 we're not getting this issue, any more.
|
||||
|
||||
But if you get the following error when compiling from the Linux build-container:
|
||||
|
||||
`MSBUILD : error MSB4017: The build stopped unexpectedly because of an unexpected logger failure.`
|
||||
`ci-build_1 | Microsoft.Build.Exceptions.InternalLoggerException: The build stopped unexpectedly because of an unexpected logger failure. ---> System.IO.IOException: The process cannot access the file because it is being used by another process.`
|
||||
|
||||
That is a [bug in .NET CLI when running "dotnet publish" within a container](https://github.com/Microsoft/msbuild/issues/2153#issuecomment-305375162).
|
||||
|
||||
If you get this issue, until the fix is released by the dotnet CLI team in the next version of the .NET CLI, in the meantime, follow the OPTION B.2 explained below, which is building the app's .NET binaries in the local Mac, instead of from a Linux build-container.
|
||||
|
||||
---
|
||||
|
||||
### Simplest and recommended CLI approach in a Mac machine (or Linux machine)
|
||||
|
||||
Open a bash shell and run the following four commands:
|
||||
|
||||
```
|
||||
$ git clone https://github.com/dotnet-architecture/eShopOnContainers.git
|
||||
$ cd eShopOnContainers
|
||||
$ docker-compose -f docker-compose.ci.build.yml up
|
||||
$ docker-compose up
|
||||
```
|
||||
|
||||
The first two commands clone the git repository onto your machine, and changes the current directory to the root directory of the project.
|
||||
|
||||
The third command, `docker-compose -f docker-compose.ci.build.yml up` creates a Docker container based on an image used for Continuous Integration (CI) builds. That image has all the required SDKs and tools loaded on it. These include .NET Core, the .NET Core CLI and SDK, npm, and required npm packages. Once the container starts, it will mount your source directory as a shared drive, then build and publish all the projects that make up the eShopOnContainers application.
|
||||
|
||||
The final command `docker-compose up` pulls all the base Docker images needed, creates the images for each microservice, then launches each container that makes up the application.
|
||||
|
||||
## Running the application
|
||||
|
||||
Once the containers have launched, open a browser and navigate to `http://localhost:5100` to visit the MVC application:
|
||||
|
||||
[[img/eShopOnContainersHomePage.png]]
|
||||
|
||||
You can also try the SPA style application by navigating to `http://localhost:5104`. Here are where all the
|
||||
services can be reached:
|
||||
|
||||
- MVC web app: `http://localhost:5100`
|
||||
- SPA web app: `http://localhost:5105`
|
||||
- Health Status web app: `http://localhost:5107`
|
||||
- Catalog Microservice API: `http://localhost:5101`
|
||||
- Ordering Microservice API: `http://localhost:5102`
|
||||
- Basket Microservice API: `http://localhost:5103`
|
||||
- Identity Microservice API: `http://localhost:5105`
|
||||
- Payment API: `http://localhost:5108`
|
||||
- Marketing API: `http://localhost:5110`
|
||||
- Locations API: `http://localhost:5109`
|
||||
|
||||
To add items to the shopping cart or check out, you'll need to login to the site.
|
||||
The credentials for a demo user are:
|
||||
|
||||
- User: **demouser@microsoft.com**
|
||||
- Password: **Pass@word1**
|
||||
|
||||
--------------------------------------------------------------------
|
||||
|
||||
## B.1.1 - Detailed procedure - Setting eShopOnContainers up using the Docker Linux build-container
|
||||
|
||||
The quick instructions above build all the projects that make up eShopOnContainers in a Docker Linux
|
||||
"build-container". That's the preferred way to build the application. It's easier to make sure all the
|
||||
prerequisites are installed, every developer uses the same version of all the tools, and
|
||||
you have a consistent experience from any build.
|
||||
|
||||
This section (B.1.1) is just a further explanation of that method.
|
||||
|
||||
### The Docker Linux build container
|
||||
|
||||
As mentioned, the recommended approach is to build the .NET bits and Docker images by using an special build
|
||||
container from the CLI or your CI/CD pipeline. What you run and test locally is built using the
|
||||
same process as your CI/CD pipleine. The verions of all tools are the same, the same version of
|
||||
all SDKs are used, and so on. This ensures consistency across all builds.
|
||||
|
||||
<img src="img/building-bits_from_ci_container.png">
|
||||
|
||||
The build container to use is based on the `image: microsoft/aspnetcore-build` ASP.NET Core
|
||||
build image which includes the .NET SDK, NPM and many other Web and ASP.NET dependencies
|
||||
(Gulp, Bower, NPM, etc.) to build your services and web apps.
|
||||
|
||||
Contrast the four commands you ran above, along with the minimal prerequisites, with the
|
||||
list of prerequisites and tools needed to build locally on your machine.
|
||||
|
||||
|
||||
## B.2 - Building the application binaries on the local Mac (local .NET Core in Mac)
|
||||
|
||||
You can build the application using your local Mac machine. You'll need the following
|
||||
prerequisites installed, in addition to those listed above for building using the CI container.
|
||||
|
||||
- Install [.NET Core and SDK](http://dot.net)*
|
||||
- Install [Node LTS](http://nodejs.org)* - Just needed in order to use NPM.
|
||||
- Bower ($ sudo npm install -g bower) needed by the MVC web app.
|
||||
|
||||
### Install .NET Core 2.0 or later
|
||||
|
||||
Install [.NET Core 2.0 SDK or later, for Mac](https://www.microsoft.com/net/core#macos) as shown in the image:
|
||||
|
||||
|
||||
|
||||
### Install Node (needed so it installs 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/
|
||||
|
||||
Install [NodeJS 6.11.5 LTS or latest Long Term Service version](https://nodejs.org/en/)
|
||||
|
||||
You can see the installed NPM version with the command npm -v, as shown below.
|
||||
|
||||
|
||||
|
||||
### Install Bower globally
|
||||
|
||||
In bash, run the following command:
|
||||
|
||||
```bash
|
||||
$ sudo npm install -g bower
|
||||
```
|
||||
As shown in the following screenshot:
|
||||
|
||||
|
||||
|
||||
|
||||
### Build the eShopOnContainers .NET binaries with 'dotnet publish'
|
||||
|
||||
You could generate the binaries manually, with 'dotnet publish', but for your convenience, we've included a bash script that runs all the 'dotnet publish' commands on your local Mac and generates the bits in the right folders expected by Docker and Visual Studio, if you use VS with the same solution, eventually.
|
||||
|
||||
Using the bash windows, navigate to your eShopOnContainers directory, and cd into the *cli-mac* directory. Then, run the build script:
|
||||
|
||||
```bash
|
||||
$ ./build-bits.sh
|
||||
```
|
||||
|
||||
|
||||
This script runs a dotnet restore, build, and publish for each project using the `dotnet` CLI tool.
|
||||
In addition, it runs the client build commands using *npm* to build the SPA application
|
||||
assets. Finally, it will remove old docker containers and images.
|
||||
|
||||
After you've finished the build, you can create the Docker images defined at the docker-compose.yml file within the solution's root directory, by using `docker-compose build`:
|
||||
|
||||
First, move to the solution's root directory with `cd ..`
|
||||
|
||||
Check that you are in the folder where the docker-compose.yml files are, and finally run the following command:
|
||||
|
||||
```bash
|
||||
$ docker-compose build
|
||||
```
|
||||
If you now run `$ docker images` you'll see the eShopOnContainers images are now ready to be used by Docker.
|
||||
|
||||
|
||||
|
||||
To run the containers, you use `docker-compose up` again:
|
||||
|
||||
```bash
|
||||
$ docker-compose up
|
||||
```
|
||||
You could also go ahead and directly run `docker-compose up` and it will first build the Docker images like when you run `docker-compose build`, though.
|
||||
|
||||
|
||||
|
||||
Ignore the warnings about environment variables for Azure, as tyhat is only needed if you were using infrastructure services in Azure (SQL Database, Redis as a service, Azure Service Bus, etc.) which is the "next step" when using eShopOncontainers.
|
||||
|
||||
The first time you run `docker-compose up`, it will pull the necessary docker images from Docker hub. That will take some time. Once the base Docker images have been pulled, the application will start and you can test it out using the browser and the addresses shown [above](#running-the-application).
|
||||
|
||||
For testing the MVC web app, run `http://localhost:5100` in any browser, so you'll see the MVC app running like in the following screenshot:
|
||||
|
||||
|
||||
|
||||
You can also try/test the SPA (Single Page Application), which is based on Angular, by running this URL in a browser: `http://localhost:5104`
|
||||
|
||||
|
||||
|
||||
|
||||
# Configuring the app for Authentication and access from remote client apps (Remote access through the network)
|
||||
|
||||
If you don't configure these further settings, you should get the following error when trying to login in the MVC web app.
|
||||
|
||||
|
||||
|
||||
That is because the by default IP used to redirect to the Identity service/app used by the application (based on IdentityServer4) is the IP 10.0.75.1.
|
||||
That IP is always set up when installing Docker for Windows in a Windows 10 machine. It is also used by Windows Server 2016 when using Windows Containers.
|
||||
|
||||
eShopOnContainers uses that IP as the "by default choice" so anyone testing the app don't need to configure further settings. However, that IP is not used by "Docker for Mac", so you need to change the config.
|
||||
|
||||
If you were to access the Docker containers from remote machines or mobile phones, like when using the Xamarin app or the web apps in remote PCs, then you would also need to change that IP and use a real IP from the network adapter.
|
||||
|
||||
## Setting up the docker-compose file environment variables and settings
|
||||
|
||||
As explained [here by Docker](https://docs.docker.com/docker-for-mac/networking/#use-cases-and-workarounds),
|
||||
the Mac has a changing IP address (or none if you have no network access). From June 2017 onwards our recommendation is to connect to the special Mac-only DNS name docker.for.mac.localhost which will resolve to the internal IP address used by the host.
|
||||
|
||||
In the `docker-compose.override.yml` file, replace the IdentityUrl environment variable (or any place where the IP 10.0.75.1 is used) with:
|
||||
|
||||
```bash
|
||||
IdentityUrl=http://docker.for.mac.localhost:5105
|
||||
```
|
||||
You could also set your real IP at the Mac's network adapter. But that would be a worse solution as it'll depend on the network you are connecting your Mac development machine..
|
||||
|
||||
Therefoire, the WebMVC service definition at the `docker-compose.override.yml` should finally be configured as shown bellow:
|
||||
|
||||
```bash
|
||||
webmvc:
|
||||
environment:
|
||||
- ASPNETCORE_ENVIRONMENT=Development
|
||||
- ASPNETCORE_URLS=http://0.0.0.0:80
|
||||
- CatalogUrl=http://catalog.api
|
||||
- OrderingUrl=http://ordering.api
|
||||
- BasketUrl=http://basket.api
|
||||
- LocationsUrl=http://locations.api
|
||||
- IdentityUrl=http://docker.for.mac.localhost:5105
|
||||
- MarketingUrl=http://marketing.api
|
||||
- CatalogUrlHC=http://catalog.api/hc
|
||||
- OrderingUrlHC=http://ordering.api/hc
|
||||
- IdentityUrlHC=http://identity.api/hc
|
||||
- BasketUrlHC=http://basket.api/hc
|
||||
- MarketingUrlHC=http://marketing.api/hc
|
||||
- PaymentUrlHC=http://payment.api/hc
|
||||
- UseCustomizationData=True
|
||||
- ApplicationInsights__InstrumentationKey=${INSTRUMENTATION_KEY}
|
||||
- OrchestratorType=${ORCHESTRATOR_TYPE}
|
||||
- UseLoadTest=${USE_LOADTEST:-False}
|
||||
ports:
|
||||
- "5100:80"
|
||||
```
|
||||
|
||||
If you re-deploy with `docker-compose up`, now the login page should work properly, as in the screenshot below.
|
||||
|
||||
NOTE: For some reason, if using SAFARI browser, it cannot reach docker.for.mac.localhost but using Chrome in Mac, it works with no issues. Since the usage of docker.for.mac.localhost is just for development purposes, just use Chrome for tests.
|
||||
|
||||
|
||||
|
||||
|
||||
# Configuring the app for external access from remote client apps
|
||||
|
||||
If using the services from remote apps, like the a phone with the Xamarin mobile app in the same Wifi network, or the web apps accessing remotely to the Docker Host, you need to change a few by-default URLs.
|
||||
|
||||
eShopOnContainers app uses the .env file to set certain by-default environment variables used by the multiple docker-compose.override you can have.
|
||||
|
||||
Therefore, the following change must be done in the .env file at the root of the eShopOnContainers folder.
|
||||
If you don't see the .env file, run the following command and re-start the Finder:
|
||||
|
||||
```bash
|
||||
$ defaults write com.apple.finder AppleShowAllFiles TRUE
|
||||
|
||||
$ killall Finder
|
||||
```
|
||||
Then, edit the .env file (with VS code, for instance) and change the ESHOP_EXTERNAL_DNS_NAME_OR_IP variable, and instead of using "localhost" as value, set a real IP or a real DNS name:
|
||||
|
||||
`
|
||||
ESHOP_EXTERNAL_DNS_NAME_OR_IP=192.168.0.25
|
||||
`
|
||||
or
|
||||
`
|
||||
ESHOP_EXTERNAL_DNS_NAME_OR_IP=myserver.mydomain.com
|
||||
`
|
||||
This is something you'll want to do if deploying to a real Docker Host, like in a VM in Azure, where you can use a DNS name for that.
|
||||
|
||||
## 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
|
||||
|
||||
## Questions
|
||||
[QUESTION] Answer +1 if the solution is working for you on the Mac:
|
||||
https://github.com/dotnet/eShopOnContainers/issues/107
|
||||
Loading…
x
Reference in New Issue
Block a user