GridLab.GMSS

Microservices Solution

This is a distributed microservices application built on Domain Driven Design (DDD) practices, orchestrated by .NET Aspire.

Pre-requirements

• Visual Studio 2026 (v18.2+) or another suitable IDE
• .NET 10.0+ SDK
• Node v18 or v20
• Docker Desktop v4.0+

All infrastructure dependencies (PostgreSQL, Valkey, RabbitMQ, Elasticsearch, Prometheus, Grafana, Jaeger, etc.) are containerized and orchestrated via .NET Aspire—no external installation required.

Quick Start

TL;DR — Start Everything

cd aspire\GridLab.Gmss.AppHost
dotnet run

That's it! The Aspire AppHost will:

1. ✅ Start all infrastructure containers (PostgreSQL, Valkey, RabbitMQ, Elasticsearch, etc.)
2. ✅ Start observability stack (Prometheus, Grafana, Jaeger, Kibana)
3. ✅ Start microservices in the correct dependency order
4. ✅ Automatically run database migrations and seed initial data
5. ✅ Wait for each service's health check before starting dependents
6. ✅ Open the Aspire Dashboard

Default Credentials

After startup, log in with:

• Username: platon
• Password: 1q2w3E*

Architecture Overview

System Diagram

Solution Structure

GridLab.Gmss/
├── apps/                           # Web Applications
│   ├── auth-server/                # OAuth 2.0 Authentication Server
│   ├── web/                        # Main Web Application (MVC/Razor Pages)
│   └── public/                     # Public Website / Landing Page
│
├── gateways/                       # API Gateways
│   ├── web/                        # Web Gateway (internal services)
│   └── public/                     # Public Gateway (external APIs)
│
├── services/                       # Microservices
│   ├── identity/                   # Users, Roles, OpenIddict
│   ├── administration/             # Permissions, Features, Settings
│   ├── audit-logging/              # Audit Logs
│   ├── tenant-management/          # Tenant definitions and management
│   ├── background-jobs/            # Hangfire Background Jobs
│   ├── data-management/            # Data Import/Export
│   └── .../                        # Business-specific services (e.g. CIM Service)
│
├── aspire/                         # .NET Aspire Orchestration
│   └── GridLab.Gmss.AppHost/       # Aspire AppHost (startup orchestrator)
│
├── etc/                            # Infrastructure Configuration Files
│   ├── elastic/                    # Elasticsearch configuration
│   ├── grafana/                    # Grafana dashboards & config
│   ├── otel/                       # OpenTelemetry Collector config
│   ├── prometheus/                 # Prometheus configuration
│   ├── rabbitmq/                   # RabbitMQ configuration
│   └── valkey/                     # Valkey (Redis) configuration

Infrastructure Components

Core Infrastructure

Observability Stack

Configuration files are located in the etc/ directory:

etc/
├── elastic/           # Elasticsearch configuration
├── grafana/
│   ├── config/        # Grafana settings
│   └── dashboards/    # Pre-configured dashboards
├── otel/              # OpenTelemetry Collector configuration
│   └── otel-collector-config.yaml
├── prometheus/        # Prometheus configuration
│   └── prometheus.yml
├── rabbitmq/          # RabbitMQ configuration
│   ├── rabbitmq.conf
│   └── enabled_plugins
├── valkey/            # Valkey (Redis) configuration
│   └── valkey.conf
└── secrets/           # Secret management

Database Schema

Each microservice owns its own database following the Database-per-Service pattern:

AuthServer Role

Important: The AuthServer does NOT create any databases. It only:

• Reads from databases created by the services above
• Handles authentication/authorization
• Issues tokens using OpenIddict

How Automatic Migration Works

Each service has a RuntimeDatabaseMigrator that runs during OnPreApplicationInitializationAsync:

// Example from IdentityService
public override async Task OnPreApplicationInitializationAsync(ApplicationInitializationContext context)
{
    using var scope = context.ServiceProvider.CreateScope();
    await scope.ServiceProvider
        .GetRequiredService<IdentityServiceRuntimeDatabaseMigrator>()
        .CheckAndApplyDatabaseMigrationsAsync();
}

The migrator:

1. ✅ Acquires a distributed lock (prevents concurrent migrations)
2. ✅ Checks if database exists (creates if not)
3. ✅ Applies EF Core migrations (creates/updates tables)
4. ✅ Runs data seeders (creates initial data)
5. ✅ Releases lock

Running with .NET Aspire (Recommended)

.NET Aspire is the recommended way to run the solution locally. It orchestrates all services, databases, and infrastructure dependencies with a single launch.

Pre-requirements (Aspire)

• Docker Desktop must be running (Aspire uses containers for infrastructure)
• .NET 10+ SDK installed

Authenticate with Docker Registry

Before running, authenticate with the container registry:

docker login
docker pull postgres:18
docker pull valkey/valkey:8
docker pull rabbitmq:4-management
docker pull docker.elastic.co/elasticsearch/elasticsearch:8.11.3
docker pull docker.elastic.co/kibana/kibana:8.11.3
docker pull prom/prometheus:v3
docker pull grafana/grafana:12.0
docker pull jaegertracing/jaeger:2.17.0
docker pull ghcr.io/open-telemetry/opentelemetry-collector-releases/opentelemetry-collector-contrib:0.123.0

Running with Aspire

1. Ensure Docker Desktop is running

2. Set GridLab.Gmss.AppHost as the startup project in Visual Studio

3. Press F5 (or Ctrl+F5), or from the command line:

   dotnet run --project aspire/GridLab.Gmss.AppHost

4. The Aspire Dashboard opens automatically at http://localhost:15888, providing:

   • Resources — all running projects and containers with endpoints and status
   • Console Logs — aggregated, searchable logs from every service
   • Structured Logs — filterable structured/semantic log entries
   • Traces — distributed traces showing request flow across services
   • Metrics — runtime and application-level metrics

Viewing Logs

• Aspire Dashboard: http://localhost:15888 → Structured Logs
• Elasticsearch/Kibana: http://localhost:5601
• Container logs: docker logs <container-id>
• Service logs: Check output in terminal or Aspire Console Logs

Service Startup Order

Aspire enforces the following startup order to ensure proper database migrations:

This order is enforced in aspire/GridLab.Gmss.AppHost/Program.cs using .WaitFor() dependencies.

Configure User Secrets (Optional)

Override default credentials using .NET User Secrets:

cd aspire/GridLab.Gmss.AppHost

# PostgreSQL credentials
dotnet user-secrets set "Parameters:postgres-user" "postgres"
dotnet user-secrets set "Parameters:postgres-password" "your-secure-password"

# RabbitMQ credentials
dotnet user-secrets set "Parameters:rabbitMQ-user" "user"
dotnet user-secrets set "Parameters:rabbitMQ-user-password" "your-secure-password"

Application Endpoints

Web Applications

API Gateways

Microservices

Observability

Building the Solution

This workspace uses the .slnx solution format (supported in .NET SDK 9.0.200+ and .NET 10).

Build with Graph

dotnet build GridLab.Gmss.slnx /graph

The /graph switch constructs a Directed Acyclic Graph (DAG) of all project dependencies:

• Improves parallel scheduling for faster builds
• Avoids double-building projects referenced by multiple entry points
• Detects circular or missing dependency issues upfront

Useful Commands

Configuration

Configuration Check

Review these configurations before running:

• appsettings.json files in each application/service project
• Connection strings for PostgreSQL
• Redis/Valkey connection settings
• RabbitMQ credentials
• Elasticsearch URLs

Key Configuration Files

Generating a Signing Certificate

For production environments:

dotnet dev-certs https -v -ep openiddict.pfx -p 17bd45f0-e7c8-4350-a745-66c4d501ed8b

Client-Side Dependencies Setup

If client-side packages are missing:

# Install ABP CLI
dotnet tool install --global Volo.Abp.Studio.CLI --version X.Y.Z

# Or restore from local tool manifest
dotnet tool restore

# Install client-side libraries
abp install-libs

Health Checks

Each service exposes health checks at /health-status:

http://localhost:{port}/health-status

Use these to verify services are fully initialized before making requests.

Observability Guide

Metrics (Prometheus + Grafana)

1. Access Grafana at http://localhost:3001

2. Default credentials: admin / admin

3. Pre-configured dashboards available in etc/grafana/dashboards/

4. Prometheus data source auto-configured

Adding a New Service to Prometheus

To enable metrics scraping for a new microservice, add a job entry to etc/prometheus/prometheus.yml:

scrape_configs:
  # ... existing jobs ...

  - job_name: 'your-new-service'
    scheme: http
    metrics_path: 'metrics'
    static_configs:
      - targets: ['host.docker.internal:<PORT>']

Example: Adding a new reporting service on port 44399:

  - job_name: 'reporting'
    scheme: http
    metrics_path: 'metrics'
    static_configs:
      - targets: ['host.docker.internal:44399']

Note: Use host.docker.internal to access services running on the host from within Docker containers.

After updating, restart the Aspire AppHost to apply changes.

Current configured services:

Tracing (Jaeger)

1. Access Jaeger at http://localhost:16686

2. Select a service from the dropdown

3. View distributed traces across microservices

4. Analyze request latency and bottlenecks

Logging (Elasticsearch + Kibana)

1. Access Kibana at http://localhost:5601

2. Create index pattern for logs-*

3. Explore logs in Discover tab

4. Build visualizations and dashboards

OpenTelemetry Collector

The OTel Collector receives telemetry from all services and exports to:

• Metrics → Prometheus
• Traces → Jaeger
• Logs → Elasticsearch

Configuration: etc/otel/otel-collector-config.yaml

Troubleshooting

Manual Database Reset (Development Only)

# Connect to PostgreSQL
docker exec -it <postgres-container-id> psql -U postgres

# Drop databases (they will be recreated on service startup)
DROP DATABASE "Gmss_Identity";
DROP DATABASE "Gmss_Administration";
DROP DATABASE "Gmss_AuditLogging";
DROP DATABASE "Gmss_TenantManagement";
DROP DATABASE "Gmss_BackgroundJobs";
DROP DATABASE "Gmss_AbpBlobStoring";
DROP DATABASE "Gmss_Cim";
\q

# Restart Aspire AppHost
cd aspire\GridLab.Gmss.AppHost
dotnet run

Helpful Commands

# Check running containers
docker ps

# View container logs
docker logs <container-id>

# Reset all databases (development only)
docker exec -it <postgres-container> psql -U postgres -c "DROP DATABASE \"Gmss_Identity\";"
# ... repeat for other databases

# Restart the entire stack
cd aspire\GridLab.Gmss.AppHost
dotnet run

Production Deployment

For production environments:

1. Pre-create databases on your PostgreSQL server
2. Run migrations manually using CI/CD pipeline
3. Configure connection strings via environment variables or secrets
4. Disable auto-migration in production configuration
5. Use proper SSL certificates (not dev-certs)
6. Configure external observability (cloud-based monitoring)

Example migration command:

dotnet ef database update --project services/identity/GridLab.Gmss.IdentityService
dotnet ef database update --project services/administration/GridLab.Gmss.AdministrationService
# ... repeat for other services

Summary

Need Help? Check the logs in each service's output or the Aspire Dashboard for detailed migration progress and errors