diff --git a/docs/en/Samples/Microservice-Demo.md b/docs/en/Samples/Microservice-Demo.md index 747c733683..8313e2b58e 100644 --- a/docs/en/Samples/Microservice-Demo.md +++ b/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 diff --git a/docs/en/images/microservice-sample-solution.png b/docs/en/images/microservice-sample-solution.png new file mode 100644 index 0000000000..4c8344ed68 Binary files /dev/null and b/docs/en/images/microservice-sample-solution.png differ diff --git a/samples/MicroserviceDemo/README.md b/samples/MicroserviceDemo/README.md index e543d3141a..a1c2de87b7 100644 --- a/samples/MicroserviceDemo/README.md +++ b/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` \ No newline at end of file +See the [documentation](../../docs/en/Samples/Microservice-Demo.md). \ No newline at end of file