Skip to main content
This guide walks you through setting up and running the AspNetRun Microservices project locally using Docker Compose.

​
Prerequisites

Before you begin, ensure you have the following tools installed:
Make sure Docker Desktop is running before proceeding with the setup.

​
Docker Configuration

For optimal performance, configure Docker Desktop with the following minimum resources:
  1. Open Docker Desktop settings (click the Docker icon in system tray)
  2. Navigate to Settings > Resources
  3. Set the following minimum values:
    • Memory: 4 GB
    • CPU: 2 cores
These are minimum requirements. If you have more resources available, allocating additional memory and CPU cores will improve performance.

​
Step-by-Step Setup

​
1. Clone the Repository

git clone https://github.com/aspnetrun/run-aspnetcore-microservices.git
cd run-aspnetcore-microservices

​
2. Navigate to Source Directory

cd src

​
3. Start All Services

Run the following command to start all microservices and their dependencies: 
docker-compose -f docker-compose.yml -f docker-compose.override.yml up -d
This command will:
  • Pull all required Docker images
  • Build microservice containers
  • Start all databases (PostgreSQL, SQL Server, Redis)
  • Start RabbitMQ message broker
  • Launch all microservices
  • Start the API Gateway and Web UI
The first run will take several minutes as Docker needs to download base images and build containers.

​
4. Wait for Services to Initialize

Some microservices need extra time to initialize, especially databases and the Ordering service which runs migrations. Wait 2-3 minutes after all containers start before accessing the application.
You can monitor the startup process by viewing logs: 
docker-compose logs -f
Press Ctrl+C to stop viewing logs (containers will continue running).

​
5. Verify Services are Running

Check that all containers are up and healthy: 
docker-compose ps
You should see all services with Up status.

​
Accessing the Application

​
Web UI (Shopping Application)

The main shopping web interface is available at: https://localhost:6065 This is the primary interface where you can:
  • Browse products from the Catalog
  • Add items to the Basket
  • Complete checkout (which triggers RabbitMQ messaging)
  • View orders

​
Individual Microservices

Each microservice exposes HTTP endpoints on the following ports:
ServiceHTTP PortHTTPS PortPurpose
Catalog API60006060Product catalog management
Basket API60016061Shopping basket operations
Discount gRPC60026062Discount calculation service
Ordering API60036063Order processing
API Gateway60046064YARP reverse proxy
Shopping Web60056065Web UI

​
API Endpoints

The microservices use Carter for minimal API endpoints. Example endpoints:

​
Catalog API Endpoints

# Get all products (with pagination)
GET http://localhost:6000/products?PageNumber=1&PageSize=10

# Get product by ID
GET http://localhost:6000/products/{id}

# Get products by category
GET http://localhost:6000/products/category/{category}

# Create product
POST http://localhost:6000/products

# Update product
PUT http://localhost:6000/products

# Delete product
DELETE http://localhost:6000/products/{id}

​
Basket API Endpoints

# Get basket by username
GET http://localhost:6001/basket/{username}

# Store/Update basket
POST http://localhost:6001/basket

# Delete basket
DELETE http://localhost:6001/basket/{username}

# Checkout basket
POST http://localhost:6001/basket/checkout

​
Ordering API Endpoints

# Get orders by customer
GET http://localhost:6003/orders?customerId={customerId}

# Get orders by name
GET http://localhost:6003/orders/{orderName}

​
Via API Gateway

You can also access microservices through the YARP API Gateway: 
# Catalog through Gateway
GET http://localhost:6004/catalog-service/products

# Basket through Gateway
GET http://localhost:6004/basket-service/basket/{username}

# Ordering through Gateway
GET http://localhost:6004/ordering-service/orders
The Ordering service has rate limiting enabled through the API Gateway using a fixed window limiter.

​
Infrastructure Services

​
RabbitMQ Management Console

Access the RabbitMQ dashboard to monitor message queues: Here you can:
  • View active queues and exchanges
  • Monitor BasketCheckout events
  • Track message flow between Basket and Ordering services

​
Database Access

Connect to databases using your preferred database client: PostgreSQL (Catalog Database)
  • Host: localhost
  • Port: 5432
  • Database: CatalogDb
  • Username: postgres
  • Password: postgres
PostgreSQL (Basket Database)
  • Host: localhost
  • Port: 5433
  • Database: BasketDb
  • Username: postgres
  • Password: postgres
SQL Server (Order Database)
  • Host: localhost
  • Port: 1433
  • Database: OrderDb
  • Username: sa
  • Password: SwN12345678
Redis (Distributed Cache)
  • Host: localhost
  • Port: 6379

​
Testing the Complete Flow

  1. Browse Products: Open https://localhost:6065 and view the product catalog
  2. Add to Basket: Click on products to add them to your shopping basket
  3. Checkout: Complete the checkout process
  4. Verify Messaging: Open RabbitMQ console (http://localhost:15672) and observe the BasketCheckout queue activity
  5. Check Orders: The Ordering microservice consumes the message and creates an order

​
Stopping the Application

To stop all running containers: 
docker-compose down
To stop and remove all volumes (this will delete all data): 
docker-compose down -v

​
Running Individual Services

If you want to debug a specific microservice in your IDE while keeping infrastructure services running:

​
1. Start only infrastructure services:

docker-compose up -d catalogdb basketdb distributedcache orderdb messagebroker

​
2. Run the microservice from your IDE:

  • Open the solution in Visual Studio
  • Set the desired microservice project as startup project
  • Press F5 to run with debugging
Make sure to use the appsettings.Development.json configuration which points to localhost for database connections.

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us