eShopOnContainers - Microservices Architecture and Containers based Reference Application (Visual Studio 2017 and CLI environments compatible)

Sample .NET Core reference application, powered by Microsoft, based on a simplified microservices architecture and Docker containers.

Note for Pull Requests: We accept pull request from the community. When doing it, please do it onto the DEV branch which is the consolidated work-in-progress branch. Do not request it onto Master, if possible.

Moved to .NET Core 2.0 "wave"

We have moved to .NET Core 2.0!

• Branch dev is in .NET Core 2.0.
• Branch master is still in .NET Core 1.1 (but it will be updated soon)

To access the .NET Core 1.1 version you can use the netcore1.1 tag (https://github.com/dotnet-architecture/eShopOnContainers/tree/netcore1.1)

PLEASE Read our branch guide to know about our branching policy

DISCLAIMER

IMPORTANT: The current state of this sample application is BETA for the .NET Core 2.0 version, and v1.0 for the .NET Core 1.1.2 version tagged (https://github.com/dotnet-architecture/eShopOnContainers/tree/netcore1.1)

This reference application proposes a simplified microservice oriented architecture implementation to introduce technologies like .NET Core with Docker containers through a comprehensive application. The chosen domain is an eShop/eCommerce but simply because it is a well-know domain by most people/developers. However, this sample application should not be considered as an "eCommerce reference model", at all. The implemented business domain might not be ideal from an eCommerce business point of view. It is neither trying to solve all the problems in a large, scalable 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.

The next step after understanding Docker containers and microservices development with .NET Core, is to select a microservice cluster/orchestrator like Azure Service Fabric or Kubernetes, DC/OS or Docker Swarm (in Azure Container Service). Kubernetes and Service Fabric are being tested with eShopOnContainer. Additional steps already tested in eShopOnContainers are about moving your databases to HA cloud services (like Azure SQL DB), to implement your EventBus with Azure Service Bus or any other production ready Service Bus in the market. Read the planned Roadmap and Milestones for future releases of eShopOnContainers within the Wiki for further info about possible new implementations and provide feedback at the ISSUES section if you'd like to see any specific scenario implemented or improved. Also, feel free to discuss on any current issue.

Architecture overview: This reference application is cross-platform either at 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. The architecture proposes a simplified microservice oriented architecture implementation with multiple autonomous microservices (each one owning its own data/db) and implementing different approaches within each microservice (simple CRUD vs. DDD/CQRS patterns) using Http as the communication protocol between the client apps and the microservices and supports asynchronous communication for data updates propagation across multiple services based on Integration Events and an Event Bus (a light message broker, to choose between RabbitMQ or Azure Service Bus, underneath) plus other features defined at the roadmap.

The microservices are different in type, meaning different internal architecture patterns approaches depending on it purpose, as shown in the image below.

Additional miroservice styles with other frameworks and No-SQL databases will be added, eventually. This is a great opportunity for pull requests from the community, like a new microservice using Nancy, or even other languages like Node, Go, Python or data containers with MongoDB with Azure DocDB compatibility, PostgreSQL, RavenDB, Event Store, MySql, etc. You name it! :)

Important Note on Database Servers/Containers

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 to any cloud or specific server. Each database could also be deployed as a single Docker container, but then you'd need more then 8GB or memory RAM assigned to Docker 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.

A similar case is defined in regards Redis cache running as a container for the development environment.

However, in a real production environment it is recommended to have your databases (SQL Server and Redis, in this case) in HA (High Available) 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 a HA cloud or on-premises.

Related documentation and guidance

While developing this reference application, we've been creating a reference Guide/eBook focusing on architecting and developing containerized and microservice based .NET Applications (download link available below) 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 apps that can also live as Docker containers.

There are also additional eBooks focusing on Containers/Docker lifecycle (DevOps, CI/CD, etc.) with Microsoft Tools, already published plus an additional eBook focusing on Enterprise Apps Patterns with Xamarin.Forms. You can download them and start reviewing these Guides/eBooks here:

Architecting & Developing	Containers Lifecycle & CI/CD	App patterns with Xamarin.Forms
Download (First Edition)	Download (First Edition)	Download (First Edition)

Send feedback to dotnet-architecture-ebooks-feedback@service.microsoft.com

However, we encourage to download and 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 pattern implementations, so you'll understand much better the context, design and decisions taken in the current architecture and internal designs.

Overview of the application code

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 .NET Core and Docker.

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. The screenshot below shows the VS Solution structure for those microservices/containers and client apps.

• (Recommended when getting started) Open eShopOnContainers-ServicesAndWebApps.sln for a solution containing just the server-side projects related to the microservices and web applications.
• Open eShopOnContainers-MobileApps.sln for a solution containing just the client mobile app projects (Xamarin mobile apps only). It works independently based on mocks, too.
• Open eShopOnContainers.sln for a solution containing all the projects (All client apps and services).

Finally, those microservices are consumed by multiple client web and mobile apps, as described below.
MVC Application (ASP.NET Core): Its an MVC 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.
SPA (Single Page Application): Providing similar "eShop business functionality" but developed with Angular 2, Typescript and slightly using ASP.NET Core MVC. 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).
Xamarin Mobile App (For iOS, Android and Windows/UWP): It is a client mobile app supporting the most common mobile 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).

Setting up your development environment for eShopOnContainers

Visual Studio 2017 and Windows based

This is the more straightforward way to get started: https://github.com/dotnet-architecture/eShopOnContainers/wiki/02.-Setting-eShopOnContainers-in-a-Visual-Studio-2017-environment

CLI and Windows based

For those who prefer the CLI on Windows, using dotnet CLI, docker CLI and VS Code for Windows: https://github.com/dotnet/eShopOnContainers/wiki/03.-Setting-the-eShopOnContainers-solution-up-in-a-Windows-CLI-environment-(dotnet-CLI,-Docker-CLI-and-VS-Code)

CLI and Mac based

For those who prefer the CLI on a Mac, using dotnet CLI, docker CLI and VS Code for Mac (Instructions still TBD, but similar to Windows CLI): 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)

Note on tested Docker Containers/Images

Most of the development and testing of this project was (as of early March 2017) 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". The Windows Containers scenario is currently being implemented/tested yet. The application should be able to run on Windows Nano 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). The app was also partially tested on "Docker for Mac" using a development MacOS machine with .NET Core and VS Code installed, which is still a scenario using Linux containers running on the VM setup in the Mac by the "Docker for Windows" setup. But further testing and feedback on Mac environments and Windows Containers, from the community, will be appreciated.

Kubernetes

The k8s directory contains Kubernetes configuration for the eShopOnContainers app and a PowerShell script to deploy it to a cluster. Each eShopOnContainers microservice has a deployment configuration in deployments.yaml, and is exposed to the cluster by a service in services.yaml. The microservices are exposed externally on individual routes (/basket-api, /webmvc, etc.) by an nginx reverse proxy specified in frontend.yaml and nginx.conf.

Prerequisites

• A Kubernetes cluster. Follow Azure Container Service's walkthrough to create one.
• A private Docker registry. Follow Azure Container Registry's guide to create one.
• A Docker development environment with docker and docker-compose.
  • Visit docker.com to download the tools and set up the environment. Docker's installation guide covers verifying your Docker installation.
• The Kubernetes command line client, kubectl.
  • This can be installed with the az tool as described in the Azure Container Service walkthrough. az is also helpful for getting the credentials kubectl needs to access your cluster. For other installation options, and information about configuring kubectl yourself, see the Kubernetes documentation.

Deploy the application with the deployment script

1. Open a PowerShell command line at the k8s directory of your local eShopOnContainers repository.
2. Ensure docker, docker-compose, and kubectl are on the path, and configured for your Docker machine and Kubernetes cluster.
3. Run deploy.ps1 with your registry information. The Docker username and password are provided by Azure Container Registry, and can be retrieved from the Azure portal. For example:

./deploy.ps1 -registry myregistry.azurecr.io -dockerUser User -dockerPassword SecretPassword

The script will build the code and corresponding Docker images, push the latter to your registry, and deploy the application to your cluster. You can watch the deployment unfold from the Kubernetes web interface: run kubectl proxy and open a browser to http://localhost:8001/ui

Sending feedback and pull requests

As mentioned, 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): dotnet-architecture#107