Installation Guide - Masar Eagle

Overview

This guide walks you through the complete installation process for Masar Eagle. Choose between local development or production deployment based on your needs.

Before proceeding, ensure you have completed the Prerequisites setup.

Quick Start

Get Masar Eagle running in under 5 minutes:

Clone the Repository

git clone https://github.com/your-org/masar-eagle.git
cd masar-eagle

Run with .NET Aspire

cd src/aspire/AppHost
dotnet run

This will:

Start the Aspire orchestration dashboard
Launch all microservices
Provision PostgreSQL, RabbitMQ, and monitoring tools
Open the dashboard at http://localhost:8080

Access Services

Aspire Dashboard: http://localhost:8080
API Gateway: http://localhost:8080/api
pgAdmin: http://localhost:5050
RabbitMQ Management: http://localhost:15672
Grafana: http://localhost:3000
Jaeger: http://localhost:16686

Installation Methods

Local Development

Run with .NET Aspire for development

Docker Deployment

Deploy using Docker Compose

Aspire Deployment

Deploy with .NET Aspire publish

Kubernetes

Deploy to Kubernetes cluster

Local Development

Step 1: Clone and Navigate

git clone https://github.com/your-org/masar-eagle.git
cd masar-eagle

Step 2: Restore Dependencies

# Restore all NuGet packages
dotnet restore

# Verify restoration
dotnet build --no-restore

Step 3: Configure AppHost

The AppHost is pre-configured but can be customized:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Aspire.Hosting.Dcp": "Warning"
    }
  },
  "Parameters": {
    "username": "guest",
    "password": "guest"
  }
}

Step 4: Run the Application

Using .NET CLI
Using Visual Studio
Using Rider
Using VS Code

cd src/aspire/AppHost
dotnet run

Open MasarEagle.sln in Visual Studio 2022
Set AppHost as the startup project
Press F5 or click Start

Open the solution in JetBrains Rider
Select the AppHost run configuration
Click the Run button

# Install C# Dev Kit extension first
cd src/aspire/AppHost
dotnet run

Step 5: Verify Installation

Check Aspire Dashboard

Open http://localhost:8080 to see the Aspire orchestration dashboard.You should see:

All services in “Running” state
PostgreSQL and RabbitMQ healthy
No error logs

Test API Gateway

# Health check
curl http://localhost:8080/health

# Expected response
{"status":"Healthy"}

Check Database Connectivity

# Access pgAdmin at http://localhost:5050
# Default credentials are set by Aspire

# You should see 4 databases:
# - user
# - trip
# - notifications
# - auth

Verify Message Queue

# Access RabbitMQ Management UI
# http://localhost:15672
# Username: guest
# Password: guest

# Check that exchanges and queues are created

Service Configuration

Architecture Overview

Masar Eagle consists of the following services:

Gateway

YARP-based API Gateway

Routes requests to services
Service discovery
Load balancing

Identity

Authentication Service

OpenIddict integration
JWT token generation
User authentication

Users

User Management

Driver profiles
Passenger profiles
Company management

Trips

Trip Management

Booking system
Wallet management
Trip scheduling

Notifications

Notification Service

Firebase Cloud Messaging
Push notifications
Device token management

Service Dependencies

The AppHost configures service dependencies and startup order:

AppHost.cs (excerpt)

// PostgreSQL with 4 databases
var postgres = builder.AddPostgres("postgres")
    .WithDataVolume("masar-postgres-data")
    .WithPgAdmin();

var usersDb = postgres.AddDatabase("user");
var tripsDb = postgres.AddDatabase("trip");
var notificationsDb = postgres.AddDatabase("notifications");
var authDb = postgres.AddDatabase("auth");

// RabbitMQ with management plugin
var rabbitmq = builder.AddRabbitMQ("rabbitmq")
    .WithDataVolume("rabbitmq-data")
    .WithManagementPlugin();

// Services with dependencies
builder.AddProject<User>("user")
    .WithReference(usersDb)
    .WithReference(rabbitmq)
    .WaitFor(usersDb)
    .WaitFor(rabbitmq);

All services automatically wait for their dependencies to be healthy before starting.

Database Migrations

Automatic Migrations

Masar Eagle uses FluentMigrator for database migrations. Migrations run automatically on service startup:

# Migrations are applied when each service starts
# Check logs for migration status:

[Information] Running migrations for database: user
[Information] Migration 20240101000000_InitialSchema completed
[Information] Database is up to date

Manual Migration Control

Apply Migrations
Rollback Migrations
View Migration Status

# Run migrations for a specific service
cd src/services/Users/Users.Api
dotnet run -- --migrate

# Rollback to a specific version
dotnet run -- --migrate --version=20240101000000

# List applied migrations
dotnet run -- --migrate --list

Monitoring Setup

OpenTelemetry Configuration

All services are configured with OpenTelemetry for observability:

// Each service sends telemetry to the collector
services.WithEnvironment("OTEL_EXPORTER_OTLP_ENDPOINT", "http://otelcollector:4317")
    .WithEnvironment("OTEL_EXPORTER_OTLP_PROTOCOL", "grpc")
    .WithEnvironment("OTEL_SERVICE_NAME", serviceName);

Access Monitoring Tools

Prometheus - Metrics

URL: http://localhost:9090

# Example queries
rate(http_requests_total[5m])
up{job="user"}

Grafana - Dashboards

URL: http://localhost:3000Pre-configured dashboards for:

Service metrics
Database performance
RabbitMQ statistics
Business metrics

Jaeger - Distributed Tracing

URL: http://localhost:16686View request traces across all services:

Request flow visualization
Performance bottlenecks
Error tracking

Loki - Log Aggregation

URL: http://localhost:3100Access via Grafana Explore:

Centralized logs from all services
Log filtering and searching
Log correlation with traces

Troubleshooting

Port Conflicts

If you encounter port conflicts:

# Check which process is using a port
lsof -i :8080  # Linux/macOS
netstat -ano | findstr :8080  # Windows

# Modify AppHost.cs to use different ports
builder.AddProject<Gateway>("gateway")
    .WithHttpEndpoint(port: 8081);  // Change port

Database Connection Errors

If services can’t connect to PostgreSQL:

# Check PostgreSQL container status
docker ps | grep postgres

# View PostgreSQL logs
docker logs <container-id>

# Restart PostgreSQL
docker restart <container-id>

Service Not Starting

Check the Aspire dashboard logs:

# Services log startup issues to console
# Common issues:
# - Missing environment variables
# - Database migration failures
# - Port conflicts

RabbitMQ Connection Issues

# Verify RabbitMQ is running
docker ps | grep rabbitmq

# Check RabbitMQ logs
docker logs <rabbitmq-container-id>

# Verify credentials in appsettings.json

If you encounter persistent issues, try cleaning and rebuilding:

# Clean solution
dotnet clean

# Remove containers and volumes
docker compose down -v

# Rebuild and run
dotnet build
cd src/aspire/AppHost
dotnet run

Environment-Specific Setup

Development Environment

# Use mock services for external dependencies
export ASPNETCORE_ENVIRONMENT=Development

# SMS Provider: Mock (no real SMS sent)
# Email Provider: Resend (test mode)
# Payment Provider: Moyasar (test keys)

Staging Environment

export ASPNETCORE_ENVIRONMENT=Staging

# Use staging databases
# Enable full telemetry
# Use test payment gateways

Production Environment

See Aspire Deployment or Docker Deployment for production setup.

Next Steps

Configuration

Configure environment variables and settings

Docker Deployment

Deploy using Docker Compose

Aspire Deployment

Production deployment with Aspire

Additional Resources

.NET Aspire Docs

Official .NET Aspire documentation

Architecture Overview

Learn about Masar Eagle architecture

Getting Started

Setup & Deployment

Core Concepts

Services

Features

Development

Operations

​Overview

​Quick Start

​Installation Methods

Local Development

Docker Deployment

Aspire Deployment

Kubernetes

​Local Development

​Step 1: Clone and Navigate

​Step 2: Restore Dependencies

​Step 3: Configure AppHost

​Step 4: Run the Application

​Step 5: Verify Installation

​Service Configuration

​Architecture Overview

Gateway

Identity

Users

Trips

Notifications

​Service Dependencies

​Database Migrations

​Automatic Migrations

​Manual Migration Control

​Monitoring Setup

​OpenTelemetry Configuration

​Access Monitoring Tools

​Troubleshooting

​Environment-Specific Setup

​Development Environment

​Staging Environment

​Production Environment

​Next Steps

Configuration

Docker Deployment

Aspire Deployment

​Additional Resources

.NET Aspire Docs

Architecture Overview

Build docs developers (and LLMs) love

Overview

Quick Start

Installation Methods

Local Development

Step 1: Clone and Navigate

Step 2: Restore Dependencies

Step 3: Configure AppHost

Step 4: Run the Application

Step 5: Verify Installation

Service Configuration

Architecture Overview

Service Dependencies

Database Migrations

Automatic Migrations

Manual Migration Control

Monitoring Setup

OpenTelemetry Configuration

Access Monitoring Tools

Troubleshooting

Environment-Specific Setup

Development Environment

Staging Environment

Production Environment

Next Steps

Additional Resources