Updated Microservice-Demo, Added how to run section.

docs/en/Samples/Microservice-Demo.md

@@ -19,7 +19,7 @@ This sample aims to demonstrate a simple yet complete microservice solution;
 * Has a **console application** to show the simplest way of using a service by authenticating.
 * Uses [Redis](https://redis.io/) for **distributed caching**.
 * Uses [RabbitMQ](https://www.rabbitmq.com/) for service-to-service **messaging**.
-* Uses [Kubernates](https://kubernetes.io/) to **deploy** & run all services and applications.
+* Uses docker & [Kubernates](https://kubernetes.io/) to **deploy** & run all services and applications.
 
 The diagram below shows the system:
 
@@ -33,7 +33,139 @@ You can get the source code from [the GitHub repository](https://github.com/abpf
 
 This sample is still in development, not completed yet.
 
-## Microservices
+## How To Run?
+
+You can either run from the **source code** or from the pre-configured **docker-compose** file.
+
+### Using the Docker Containers
+
+#### Pre Requirements
+
+Running as docker containers is easier since all dependencies are pre-configured. You only need to install the latest docker. For Windows, follow [this URL](https://docs.docker.com/docker-for-windows/install/).
+
+#### Running Containers
+
+- Clone or download the [ABP repository](https://github.com/abpframework/abp).
+
+- Open a command line in the `samples/MicroserviceDemo` folder of the repository.
+
+- Restore SQL Server databases:
+
+  ```
+  docker-compose -f docker-compose.yml -f docker-compose.migrations.yml run restore-database
+  ```
+
+- Start the containers:
+
+  ```
+  docker-compose up -d
+  ```
+
+  At the first run, it will take a **long time** because it will build all docker images.
+
+- Add this line to the end of your `hosts` file:
+
+  ```
+  127.0.0.1	auth-server
+  ```
+
+  hosts file is located inside the `C:\Windows\System32\Drivers\etc\hosts` folder on Windows and `/etc/hosts` for Linux/MacOS.
+
+#### Run the Applications
+
+There are a few applications running in the containers you may want to explore:
+
+* Backend Admin Application (BackendAdminApp.Host): `http://localhost:51512`
+  *(Used to manage users & products in the system)*
+* Public Web Site (PublicWebsite.Host): `http://localhost:51513`
+  *(Used to list products and run/manage the blog module)*
+* Authentication Server (AuthServer.Host): `http://localhost:51511`
+  *(Used as a single sign on and authentication server built with IdentityServer4)*
+* Kibana UI: `http://localhost:51510`
+  *(Use to show/trace logs written by all services/applications/gateways)*
+
+### Running From the Source Code
+
+#### Pre Requirements
+
+To be able to run the solution from source code, following tools should be installed and running on your computer:
+
+* [SQL Server](https://www.microsoft.com/en-us/sql-server/sql-server-downloads) 2015+ (can be [express edition](https://www.microsoft.com/en-us/sql-server/sql-server-editions-express))
+* [Redis](https://redis.io/download) 5.0+
+* [RabbitMQ](https://www.rabbitmq.com/install-windows.html) 3.7.11+
+* [MongoDB](https://www.mongodb.com/download-center) 4.0+
+* [ElasticSearch](https://www.elastic.co/downloads/elasticsearch) 6.6+
+* [Kibana](https://www.elastic.co/downloads/kibana) 6.6+ (optional, recommended to show logs)
+
+#### Open & Build the Visual Studio Solution
+
+* Open the `samples\MicroserviceDemo\MicroserviceDemo.sln` in Visual Studio 2017 (15.9.0+).
+* Run `dotnet restore` from the command line inside the `samples\MicroserviceDemo` folder.
+* Build the solution in Visual Studio.
+
+#### Restore Databases
+
+Open `MsDemo_Identity.zip` and `MsDemo_ProductManagement.zip` inside the `samples\MicroserviceDemo\databases` folder and restore to the SQL Server.
+
+> Notice that: These databases have EF Core migrations in the solution, however they don't have seed data, especially required for IdentityServer4 configuration. So, restoring the databases is much more easier.
+
+#### Run Projects
+
+Run the projects with the following order (right click to each project, set as startup project an press Ctrl+F5 to run without debug):
+
+* AuthServer.Host
+* IdentityService.Host
+* BloggingService.Host
+* ProductService.Host
+* InternalGateway.Host
+* BackendAdminAppGateway.Host
+* PublicWebSiteGateway.Host
+* BackendAdminApp.Host
+* PublicWebSite.Host
+
+### Running the Docker Containers
+
+* Clone or download the [ABP repository](https://github.com/abpframework/abp).
+
+* Open a command line in the `samples/MicroserviceDemo` folder of the repository.
+
+* Restore databases:
+
+  ````
+  docker-compose -f docker-compose.yml -f docker-compose.migrations.yml run restore-database
+  ````
+
+* Start the containers:
+
+  ````
+  docker-compose up -d
+  ````
+
+  At the first run, it will take a **long time** because it will build all docker images.
+
+* Add this line to the end of your `hosts` file:
+
+  ````
+  127.0.0.1	auth-server
+  ````
+
+  hosts file is located inside the `C:\Windows\System32\Drivers\etc\hosts` folder on Windows and `/etc/hosts` for Linux/MacOS.
+
+## Exploring the Solution
+
+The Visual Studio solution consists of multiple projects each have different roles in the system:
+
+![microservice-sample-solution](../images/microservice-sample-solution.png)
+
+It has 3 **microservices** with have no UI but exposes REST services:
+
+* **IdentityService.Host**: Host the ABP Identity module which is used to manage users & roles. It has no additional service, but only hosts the Identity module's API.
+* **BloggingService.Host**: Host the ABP Blogging module which is used to manage blog & posts (a typical blog application). It has no additional service, but only hosts the Blogging module's API.
+* **ProductService.Host**: Hosts the Product module (that is inside the solution) which is used to manage products. It also contains the EF Core migrations to create/update the Product Management database schema.
+
+It has 3 **databases**:
+
+* ...
 
 ### Identity Service
 

samples/MicroserviceDemo/README.md

@@ -1,27 +1,3 @@
-# MicroserviceDemo
+# Microservice Demo Solution
 
-Run demo using docker-compose:
-
-First restore mssql database
-```sh
-$ docker-compose -f docker-compose.yml -f docker-compose.migrations.yml run restore-database
-```
-
-Build and start containers
-```sh
-$ docker-compose up -d
-```
-
-Add this line to your `hosts` file
-```
-127.0.0.1	auth-server
-```
-- Windows: `C:\Windows\System32\Drivers\etc\hosts`
-- Linux & macOS: `/etc/hosts`
-
-
-### Accessing the Web User Interfaces
-- Kibana: `http://localhost:51510`
-- AuthServer: `http://localhost:51511`
-- BackendAdminApp: `http://localhost:51512`
-- PublicWebsite: `http://localhost:51513`
+See the [documentation](../../docs/en/Samples/Microservice-Demo.md).