Skip to main content

​
Overview

This guide will walk you through running the complete AspNetRun Microservices e-commerce application using Docker Compose. The application includes multiple microservices (Catalog, Basket, Discount, Ordering), databases (PostgreSQL, Redis, SQL Server), a message broker (RabbitMQ), an API Gateway (Yarp), and a web UI.
Make sure you have completed all prerequisites before starting this guide.

​
Architecture Overview

The application consists of:
  • Catalog Service - Product catalog management with PostgreSQL
  • Basket Service - Shopping cart with Redis cache
  • Discount Service - gRPC service for discounts with SQLite
  • Ordering Service - Order processing with SQL Server and RabbitMQ
  • Yarp API Gateway - Reverse proxy with rate limiting
  • Shopping Web UI - ASP.NET Core web application
1

Clone the Repository

Clone the repository to your local machine:
git clone https://github.com/aspnetrun/run-aspnetcore-microservices.git
cd run-aspnetcore-microservices
2

Configure Docker Desktop

Before running the application, ensure Docker Desktop has sufficient resources allocated:
  1. Open Docker Desktop
  2. Go to Settings → Resources
  3. Configure the following minimum requirements:
    • Memory: 4 GB (recommended: 8 GB)
    • CPU: 2 cores (recommended: 4 cores)
    • Disk: 20 GB available space
The application requires at least 4 GB of RAM to run all services. Insufficient memory will cause container failures.
  1. Click Apply & Restart to save changes
  2. Ensure Docker Desktop is running before proceeding
3

Navigate to the Source Directory

Navigate to the directory containing the docker-compose files:
cd src
The src directory contains:
  • docker-compose.yml - Service definitions
  • docker-compose.override.yml - Environment-specific configurations
4

Start the Application

Run the following command to start all microservices and databases:
docker-compose -f docker-compose.yml -f docker-compose.override.yml up -d
The -d flag runs containers in detached mode (background).
The initial startup may take 5-10 minutes as Docker downloads all required images and builds the application containers.
5

Verify Container Status

Check that all containers are running:
docker-compose ps
You should see all services with status “Up”:
  • catalogdb
  • basketdb
  • distributedcache
  • orderdb
  • messagebroker
  • catalog.api
  • basket.api
  • discount.grpc
  • ordering.api
  • yarpapigateway
  • shopping.web
If any service shows “Exit” status, view its logs:
docker-compose logs [service-name]
6

Wait for Services to Initialize

Some microservices need additional time to initialize after containers start:
  • Database migrations - The Ordering service runs Entity Framework migrations on startup
  • RabbitMQ initialization - Message broker takes 30-60 seconds to be fully ready
  • Service dependencies - Services wait for their dependencies to be healthy
If the application doesn’t work immediately, wait 2-3 minutes for all services to fully initialize, then refresh your browser.
7

Access the Application

Once all services are running, access the application:

​
Shopping Web UI

The main user interface for the e-commerce application:HTTPS: https://localhost:6065
HTTP: http://localhost:6005

​
Service Endpoints

HTTP: http://localhost:6000
HTTPS: https://localhost:6060
Health Check: http://localhost:6000/health

​
Infrastructure Services

URL: http://localhost:15672
Username: guest
Password: guest
8

Test the Application

Test the complete workflow:
  1. Navigate to https://localhost:6065
  2. Browse the product catalog
  3. Add items to your shopping basket
  4. Proceed to checkout
  5. Monitor the order processing:
    • View RabbitMQ dashboard at http://localhost:15672
    • Check the BasketCheckoutEvent message queue
    • Verify the Ordering service consumes the message
The application demonstrates asynchronous communication: when you checkout, the Basket service publishes an event to RabbitMQ, which the Ordering service consumes to create the order.

​
Stopping the Application

To stop all services: 
docker-compose down
To stop and remove all volumes (database data): 
docker-compose down -v
Using the -v flag will delete all database data. Only use this if you want to completely reset the application.

​
Troubleshooting

​
Containers Keep Restarting

Check the logs for the specific service: 
docker-compose logs -f [service-name]
Common issues:
  • Database connection errors - Wait for database containers to fully initialize
  • Port conflicts - Another service may be using the required ports
  • Memory issues - Increase Docker Desktop memory allocation

​
Application Not Loading

  1. Verify all containers are running: docker-compose ps
  2. Check service health endpoints
  3. Wait 2-3 minutes for full initialization
  4. Clear browser cache and try again

​
Port Already in Use

If you see “port already in use” errors: 
# Windows
netstat -ano | findstr :[PORT]

# Linux/macOS
lsof -i :[PORT]
Stop the conflicting service or modify the port in docker-compose.override.yml.

​
Cannot Connect to Database

Ensure database containers are healthy: 
docker-compose logs catalogdb
docker-compose logs basketdb
docker-compose logs orderdb
Database containers may take 30-60 seconds to be ready for connections.

​
Next Steps

Architecture Overview

Learn about the microservices architecture and design patterns

Catalog Service

Explore the product catalog microservice with Vertical Slice Architecture

API Gateway

Learn about YARP reverse proxy and API gateway patterns

Docker Deployment

Deploy with Docker Compose and container orchestration

​
Visual Studio Alternative

If you prefer using Visual Studio:
  1. Open the solution file in Visual Studio 2022
  2. Set docker-compose as the startup project
  3. Press F5 to run with debugging
This approach allows you to debug the microservices while they run in containers.

Build docs developers (and LLMs) love

Get started for freeTalk to us