|
| 1 | +# eShopOnContainers - Microservices Architecture and Containers based Reference Application (**ALPHA state** - VS 2017 and CLI environments compatible) |
| 2 | +Sample .NET Core reference application, powered by Microsoft, based on a simplified microservices architecture and Docker containers. <p> |
| 3 | + |
| 4 | +> ### DISCLAIMER |
| 5 | +> IMPORTANT: The current state of this sample application is ALPHA, therefore, many areas could change significantly while refactoring and getting improvements. Feedback and pull requests from the community will be appreciated. |
| 6 | +> |
| 7 | +> This reference application proposes a simplified microservice oriented architecture implementation (as mentioned, currently in ALPHA state) to introduce technologies like .NET Core with Docker containers through a comprehensive but simplified application. However, this reference application it is not trying to solve all the problems in a large and mission-critical distributed system, it is just a bootstrap for developers to easily get started in the world of Docker containers and microservices with .NET Core. |
| 8 | +> <p>For example, the next step (still not covered here) after understanding Docker containers and microservices is to select a microservice cluster/orchestrator like Docker Swarm, Kubernetes or DC/OS (in Azure Container Service) or Azure Service Fabric which in most of the cases will require additional partial changes to your application's configuration (although the present architecture should work on most orchestrators with small changes). In the future we might fork this project and make multiple versions targeting specific microservice cluster/orchestrators. <p> |
| 9 | +> Read the planned <a href='https://github.com/dotnet/eShopOnContainers/wiki/Roadmap-and-Milestones-for-future-releases'>Roadmap and Milestones for future releases of eShopOnContainers</a> within the Wiki for further info about possible new implementations and provide feedback at the ISSUES level if you'd like to see any specific scenario implemented. |
| 10 | + |
| 11 | +<p> |
| 12 | +This reference application is cross-platform either in the server and client side, thanks to .NET Core services capable of running on Linux or Windows containers depending on your Docker host, and to Xamarin for mobile apps running on Android, iOS or Windows/UWP plus any browser for the client web apps. |
| 13 | +<p> |
| 14 | +<img src="img/eshop_logo.png"> |
| 15 | +<img src="img/eShopOnContainers_Architecture_Diagram.png"> |
| 16 | +<p> |
| 17 | + |
| 18 | +> ### Important Note on Database Servers/Containers |
| 19 | +> In this solution's current configuration for a development environment, the SQL databases are automatically deployed with sample data into a single SQL Server for Linux container (a single shared Docker container for SQL databases) so the whole solution can be up and running without any dependency in the cloud or server. Each database could also be deployed as a single Docker container, but then you'd need more then 8GB or memory RAM in your development machine in order to be able to run 3 SQL Server Docker containers in your Docker Linux host in "Docker for Windows" or "Docker for Mac" development environments. |
| 20 | +> <p> A similar case is defined in regards Redis cache running as a container for the development environment. |
| 21 | +> <p> However, in a real production environment it is recommended to have persistance (SQL Server and Redis) in HA services like Azure SQL Database, Redis as a service or any other clustering system. If you want to change to a production configuration, you'll just need to change the connection strings once you have set up the servers in HA cloud or on-premises. |
| 22 | + |
| 23 | +## Related documentation and guidance |
| 24 | +While developing this reference application, we've been creating a reference Guide/eBook named <b>"Architecting and Developing Containerized and Microservice based .NET Applications"</b> which explains in detail how to develop this kind of architectural style (microservices, Docker containers, Domain-Driven Design for certain microservices) plus other simpler architectural styles, like monolithic that can also live as Docker containers. |
| 25 | +<p> |
| 26 | +There's also an additional eBook focusing on Containers/Docker lifecycle (DevOps, CI/CD, etc.) with Microsoft Tools, already published. |
| 27 | +You can start reviewing these Guides/eBooks here: |
| 28 | +<p> |
| 29 | +You can download both eBooks from here: |
| 30 | + |
| 31 | +| Architecting & Developing | Containers Lifecycle & CI/CD | |
| 32 | +| ------------ | ------------| |
| 33 | +| <a href='docs/architecting-and-developing-containerized-and-microservice-based-net-applications-ebook-early-draft.pdf'><img src="img/ebook_arch_dev_microservices_containers_cover.png"> </a> | <a href='https://aka.ms/dockerlifecycleebook'> <img src="img/ebook_containers_lifecycle.png"> </a> | |
| 34 | +| <a href='docs/architecting-and-developing-containerized-and-microservice-based-net-applications-ebook-early-draft.pdf'>Download (Confidential DRAFT until published)</a> | <a href='https://aka.ms/dockerlifecycleebook'>Download</a> | |
| 35 | + |
| 36 | + |
| 37 | +<p>However, we encourage to review the "Architecting/Developing" eBook because the architectural styles and architectural patterns and technologies explained in the guidance are using this reference application when explaining many sample implementations. |
| 38 | + |
| 39 | + |
| 40 | +## Overview of the application code |
| 41 | +In this repo you can find a sample reference application that will help you to understand how to implement a microservice architecture based application using <b>.NET Core</b> and <b>Docker</b>. |
| 42 | + |
| 43 | +The example business domain or scenario is based on an eShop or eCommerce which is implemented as a multi-container application. Each container is a microservice deployment (like the basket-microservice, catalog-microservice, ordering-microservice and the identity-microservice) which are developed using ASP.NET Core running on .NET Core so they can run either on Linux Containers and Windows Containers. |
| 44 | +The screenshot below shows the VS Solution structure for those microservices/containers and client apps. |
| 45 | +- Open <b>eShopOnContainers.sln</b> for a solution containing all the projects (All client apps and services). |
| 46 | +- Open <b>eShopOnContainers-ServicesAndWebApps.sln</b> for a solution containing just the server-side projects related to the microservices and web applications. |
| 47 | +- Open <b>eShopOnContainers-MobileApps.sln</b> for a solution containing just the client mobile app projects (Xamarin mobile apps only). |
| 48 | + |
| 49 | + |
| 50 | +<img src="img/vs-solution-structure.png"> |
| 51 | + |
| 52 | +Finally, those microservices are consumed by multiple client web and mobile apps, as described below. |
| 53 | + |
| 54 | +<b>*MVC Application (ASP.NET Core)*</b>: Its an MVC 6 application where you can find interesting scenarios on how to consume HTTP-based microservices from C# running in the server side, as it is a typical ASP.NET Core MVC application. Since it is a server-side application, access to other containers/microservices is done within the internal Docker Host network with its internal name resolution. |
| 55 | +<img src="img/eshop-webmvc-app-screenshot.png"> |
| 56 | + |
| 57 | +<b>*SPA (Single Page Application)*</b>: Providing similar "eShop business functionality" but developed with Angular 2, Typescript and slightly using ASP.NET Core MVC 6. This is another approach for client web applications to be used when you want to have a more modern client behavior which is not behaving with the typical browser round-trip on every action but behaving like a Single-Page-Application which is more similar to a desktop app usage experience. The consumption of the HTTP-based microservices is done from TypeScript/JavaScript in the client browser, so the client calls to the microservices come from out of the Docker Host internal network (Like from your network or even from the Internet). |
| 58 | +<img src="img/eshop-webspa-app-screenshot.png"> |
| 59 | + |
| 60 | +<b>*Xamarin Mobile App (For iOS, Android and Windows/UWP)*</b>: It is a client mobile app supporting the most common mobilee OS platforms (iOS, Android and Windows/UWP). In this case, the consumption of the microservices is done from C# but running on the client devices, so out of the Docker Host internal network (Like from your network or even the Internet). |
| 61 | + |
| 62 | +<img src="img/xamarin-mobile-App.png"> |
| 63 | + |
| 64 | +> ### Note on tested Docker Containers/Images |
| 65 | +> The development and testing of this project was (as of January 2017) done <b>only on Docker Linux containers</b> running in development machines with "Docker for Windows" and the default Hyper-V Linux VM (MobiLinuxVM) installed by "Docker for Windows". |
| 66 | +The <b>Windows Containers scenario has not been implemented/tested yet</b>, but the application should be able to run on Windows Containers based on different Docker base images, as well, as the .NET Core services have also been tested running on plain Windows (with no Docker). |
| 67 | +The app was also partially tested on "Docker for Mac" using a development MacOS machine with .NET Core and VS Code installed. However, that is still a scenario using Linux containers running on the VM setup in the Mac by the "Docker for Windows" setup. |
| 68 | + |
| 69 | +## Setting up your development environment for eShopOnContainers |
| 70 | +### Visual Studio 2017 and Windows based |
| 71 | +This is the more straightforward way to get started: |
| 72 | +https://github.com/dotnet/eShopOnContainers/wiki/02.-Setting-eShopOnContainer-solution-up-in-a-Visual-Studio-2017-environment |
| 73 | + |
| 74 | +### CLI and Windows based |
| 75 | +For those who prefer the CLI on Windows, using dotnet CLI, docker CLI and VS Code for Windows: |
| 76 | +https://github.com/dotnet/eShopOnContainers/wiki/03.-Setting-the-eShopOnContainers-solution-up-in-a-Windows-CLI-environment-(dotnet-CLI,-Docker-CLI-and-VS-Code) |
| 77 | + |
| 78 | +### CLI and Mac based |
| 79 | +For those who prefer the CLI on a Mac, using dotnet CLI, docker CLI and VS Code for Mac: |
| 80 | +https://github.com/dotnet/eShopOnContainers/wiki/04.-Setting-eShopOnContainer-solution-up-in-a-Mac,-VS-Code-and-CLI-environment--(dotnet-CLI,-Docker-CLI-and-VS-Code) |
| 81 | + |
| 82 | +> ### Note on Windows Containers |
| 83 | +> As mentioned, the development and testing of this project (January 2017 version) was done on Docker Linux containers running in development machines with "Docker for Windows" and the default Hyper-V Linux VM (MobiLinuxVM) installed by "Docker for Windows". |
| 84 | +In order to run the application on Windows Containers you'd need to change the base images used by each container: |
| 85 | +> - Official .NET Core base-image for Windows Containers, at Docker Hub: https://hub.docker.com/r/microsoft/dotnet/ (Using the Windows Nanoserver tag) |
| 86 | +> - Official base-image for SQL Server on Windows Containers, at Docker Hub: https://hub.docker.com/r/microsoft/mssql-server-windows |
0 commit comments