Skip to main content
Get your Masar Eagle transportation system up and running locally in minutes. This guide uses .NET Aspire to orchestrate all microservices, databases, and observability tools automatically.

​
Prerequisites

Before you begin, ensure you have the following installed:

.NET 9 SDK

Download from dotnet.microsoft.com

Docker Desktop

Required for PostgreSQL, RabbitMQ, and observability stack

.NET Aspire Workload

Install with: dotnet workload install aspire

Git

For cloning the repository
Make sure Docker Desktop is running before starting the application. Aspire will automatically provision all required containers.

​
Quick Start

1

Clone the Repository

Clone the Masar Eagle repository to your local machine:
git clone https://github.com/your-username/masar-eagle.git
cd masar-eagle
2

Navigate to AppHost

The Aspire AppHost is your orchestration entry point:
cd src/aspire/AppHost
3

Run with Aspire

Start the entire system with a single command:
dotnet run
Aspire will:
  • Build all microservices
  • Start PostgreSQL with 4 databases (users, trips, notifications, auth)
  • Launch RabbitMQ for message queuing
  • Deploy the observability stack (Prometheus, Grafana, Jaeger, Loki)
  • Configure service discovery and health checks
  • Open the Aspire Dashboard
First run may take 5-10 minutes as Docker images are pulled and projects are built.
4

Access the Aspire Dashboard

The dashboard opens automatically at http://localhost:8080Here you can:
  • Monitor all service health and logs in real-time
  • View resource consumption (CPU, memory, network)
  • Access service endpoints
  • Check distributed traces
  • View environment variables and configuration

​
Verify Services

Once Aspire finishes orchestration, verify all services are healthy:

​
Core Microservices

curl http://localhost:<gateway-port>/health
# Expected: {"status":"healthy"}
Port numbers are dynamically assigned by Aspire. Check the Aspire Dashboard at http://localhost:8080 for exact endpoint URLs.

​
Infrastructure Services

PostgreSQL (pgAdmin)

URL: http://localhost:5050View all databases:
  • userdb - User profiles, drivers, passengers
  • tripdb - Trip bookings, routes, seats
  • notificationsdb - Push notification history
  • authdb - Identity and authentication

RabbitMQ Management

URL: http://localhost:15672Credentials: guest/guestMonitor:
  • Message queues and exchanges
  • Message throughput and routing
  • Dead letter queues

Grafana Dashboard

URL: Check Aspire DashboardUnified observability:
  • Service metrics and performance
  • Log aggregation from all services
  • Distributed traces

Jaeger Tracing

URL: http://localhost:16686Visualize:
  • Request flows across services
  • Latency bottlenecks
  • Service dependencies

​
Explore the API

Each service includes Swagger documentation:
1

Find Service Endpoints

Open the Aspire Dashboard at http://localhost:8080 and locate the service endpoints under the “Resources” tab.
2

Access Swagger UI

Navigate to any API service:
http://localhost:<service-port>/swagger
Available for:
  • Users API
  • Trips API
  • Notifications API
  • Gateway API (aggregated routes)
3

Test Endpoints

Use Swagger UI to:
  • Explore available endpoints
  • View request/response schemas
  • Execute test requests
  • See authentication requirements

​
Default Configuration

Aspire automatically configures the system with development defaults:

​
RabbitMQ Credentials

{
  "username": "guest",
  "password": "guest"
}
These credentials are defined in src/aspire/AppHost/appsettings.json and can be customized for different environments.

​
Database Connections

All database connections are automatically injected via Aspire service discovery: 
// Example from Users.Api/Program.cs
builder.AddServiceDefaults(); // Configures service discovery
builder.AddDatabase();         // Auto-injects connection string
Connection strings are managed by Aspire - no manual configuration needed!

​
OpenTelemetry

All services automatically export telemetry to the observability stack: 
// From AppHost.cs - Injected into all services
WithEnvironment("OTEL_EXPORTER_OTLP_ENDPOINT", "http://otelcollector:4317")
WithEnvironment("OTEL_EXPORTER_OTLP_PROTOCOL", "grpc")

​
Troubleshooting

Problem: Aspire can’t connect to DockerSolution:
  • Ensure Docker Desktop is running
  • Check Docker daemon is accessible: docker ps
  • Restart Docker Desktop if needed
Problem: Port already in useSolution: Aspire auto-assigns most ports, but reserved ports include:
  • 8080 (Aspire Dashboard)
  • 5050 (pgAdmin)
  • 15672 (RabbitMQ Management)
  • 16686 (Jaeger UI)
Stop conflicting services or modify port bindings in AppHost.cs
Problem: A specific service fails to startSolution:
  1. Check the Aspire Dashboard logs for the failing service
  2. Verify dependencies are healthy (PostgreSQL, RabbitMQ)
  3. Look for migration errors in database services
  4. Check the console output for build errors
Problem: Database migrations failSolution: Services automatically run migrations on startup using FluentMigrator:
// From Users.Api/Program.cs
builder.Services.AddDatabaseMigrations(
    builder.Configuration,
    Assembly.GetExecutingAssembly(),
    connectionStringName: Components.Database.User);
Check container logs in Aspire Dashboard for migration errors.

​
Next Steps

Architecture Overview

Understand the microservices architecture and technology stack

Development Guide

Set up your development environment and learn the development workflow

API Reference

Explore detailed API documentation for all services

Deployment

Deploy to production with Docker Compose or Kubernetes
The development environment uses insecure defaults (e.g., guest/guest credentials, disabled certificate validation). Never use these settings in production!

Build docs developers (and LLMs) love

Get started for freeTalk to us