update wiki instructions for building and running on the Mac

04.-Setting-eShopOnContainer-solution-up-in-a-Mac,-VS-Code-and-CLI-environment--(dotnet-CLI,-Docker-CLI-and-VS-Code).md

@@ -1,7 +1,16 @@
-## Want to try it out on the Mac using the bash shell?
+# Try it out on the Mac using the bash shell
+
+The quickest path to get eShopOnContainers running on your Mac:
+
+## Prerequisites
+
+1. A Git client. The [git-scm site](https://git-scm.com/download/gui/mac) maintains a great list of clients.
+1. [Docker for Macintosh](https://docs.docker.com/docker-for-mac/install/). The stable channel is fine.
+
+## Building the application
+
+Then, open a bash shell and run the fullowing four commands:
 
-Main steps:
- 
 ```
 $ git clone https://github.com/dotnet-architecture/eShopOnContainers.git
 $ cd eShopOnContainers
@@ -15,21 +24,105 @@ The third command, `docker-compose -f docker-compose.ci.build.yml up` creates a
 
 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 Application*: `http://localhost:5100`
+    - *SPA Application*: `http://localhost:5105`
+    - *Health Status*: `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`
+
+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**
 
 --------------------------------------------------------------------
 --------------------------------------------------------------------
-## 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.
+
+## Detailed procedure - Setting eShopOnContainers up using bash and a Mac development machine
+
+The quick instructions above build all the projects that make up eShopOnContainers in a Docker
+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.
 
 ### 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.
 
+Use the `master` branch from the eShopOnContainers project. It is the most up to date stable
+branch.
+
+However, if you want to look at the very latest features, use the `dev` branch. If you
+want to submit pull requests for eShopOnContainers, start from the `dev` branch and target
+your PR to that branch.
+
+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.
+
+## Building the application locally
+
+You can build the application using your machien, if you prefer.  You'll need the following
+prerequisites installed, in addition to those listed above for building using the CI container.
+
+    - *[.NET Core and SDK](http://dot.net)*
+    - *[Node and NPM](http://nodejs.org)*
+
+ We've included a bash script that runs all the build commands locally. Navigate to your
+ eShopOnContainers directory, and cd into the *cli-mac* directory. Then, run the build script:
+
+ ```bash
+ $ ./build-bits.sh
+ ```
+
+ The script runs a 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 necessary containers using
+`docker-compose`:
+
+```bash
+$ docker-compose build
+```
+
+The above command creates the images for the eShopOnContainers application. To run, you
+use `docker-compose` again:
+
+```bash
+$ docker-compose up
+```
+
+The first time you run this command, it will pull the necessary docker images
+from Docker hub. That will take some time. Once the 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).
 
 ## 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 
+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