GridLab.Gmss

Modular Monolith Solution

This is a layered modular monolith solution based on Domain Driven Design (DDD) practises.

Pre-requirements

• Visual Studio 2026 (v18.2+) or another suitable IDE.
• .NET 10.0+ SDK
• Node v18 or v20
• Docker Desktop v4.0+
• Powershell 5.0+
• Chocolatey v2.4+
• Mkcert v1.4+
• OpenSSL v3.4+

Other dependencies (like PostgreSQL, Valkey and RabbitMQ) come with docker-compose / Aspire container configurations, so no external installation required.

Overall Diagram

The following diagram is an overview of the applications, services, databases, and other components;

• The Authentication Server is a web application serves as openid-provider (can be replace by Keycloak) that is used as a single sign-on authentication server. It hosts the login, register, forgot password, two-factor authentication, profile management... pages, OAuth endpoints and authentication-related APIs. All applications and services use this application as a central authority for authentication.

• There are two web applications in the solution

  • The Web Application is the main UI of the system. It uses the Authentication Server to make users login to the application. UI development can be done MVC (Razor Pages), Angular and Blazor technology.
  • The Public Website is a second web application that can be used as landing page for the application. It uses the Authentication Server to make users login to the application.

• There is only one modular monolith service is coming with the solution. This monolith application consists of the following modules;

  • Identity Module is used to manage users, roles, clients, resources in the system.
  • Tenant Management Module is used to manage tenants for a multi-tenant system.
  • Audit Module is used to persists audit logs to a database.
  • Feature Module is used to persist and manage the features of the GMS² platform.
  • Permission Module is used to persist and manage the permissions of the GMS² platform.
  • Settings Module is used to persist and manage the settings of the GMS² platform.
  • ....

• There are three databases, each is owned by the application. Databases are PostgreSQL with EF Core integrated in the applications. You can switch to another RDBMS or MongoDB for any of them.

• There are some infrastructure services are configured in the solution (they are configured to run with docker-compose);

  • Valkey is used as a distributed cache server.
  • RabbitMQ is used as a distributed event/message bus.
  • PostgreSQL is used for running the database in a container. The default exposed port is 5432.

Solution structure

This is a layered monolith application that consists of the following applications:

• GridLab.Gmss.DbMigrator: A console application which applies the migrations and also seeds the initial data. It is useful on development as well as on production environment.
• GridLab.Gmss.AuthServer: ASP.NET Core MVC / Razor Pages application that is integrated OAuth 2.0(OpenIddict) and account modules. It is used to authenticate users and issue tokens.
• GridLab.Gmss.HttpApi.Host: ASP.NET Core API application that is used to expose the APIs to the clients.
• GridLab.Gmss.Web: ASP.NET Core MVC / Razor Pages application that is the essential web application of the solution.
• GridLab.Gmss.Web.Public: ASP.NET Core MVC / Razor Pages application that is the public web application of the solution.

Run the Solution on IDE

The solution has a few host (GridLab.Gmss.AuthServer, GridLab.Gmss.HttpApi.Host, GridLab.Gmss.Web and GridLab.Gmss.Web.Public) applications to run your modules. These host applications provide fully configured environments for module execution.

Configuration Check

The solution includes default configuration that works immediately. However, review these configurations before running:

• Check appsettings.json files in the GridLab.Gmss.AuthServer, GridLab.Gmss.HttpApi.Host, and GridLab.Gmss.DbMigrator projects and modify as needed.

Generating a Signing Certificate

For production environments, use a production signing certificate. Generate one using:

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

Client-Side Dependencies Setup

If client-side package dependencies are missing (after cloning or adding new packages), follow these steps:

Install the ABP CLI utility:

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

For local tool usage, restore dependencies using the tool manifest file file located in .config

dotnet tool restore

replace version number with the latest available.

• Delete any package-lock.json files in your web UI projects
• Run abp install-libs or install-libs.ps1 in your solution folder to install client-side dependencies

Database Initialization

• Monolith Solution: Database Migrations

• Run the GridLab.Gmss.DbMigrator project to initialize your database. This application:

  • Creates the database schema by applying all pending Entity Framework Core migrations
  • Seeds essential initial data required for the application to run properly
  • First-time setup: Must be executed before the initial application launch
  • After schema changes: Re-run whenever new database migrations are added to the solution

Run 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 — eliminating the need to manually start projects in sequence or run docker-compose separately.

Pre-requirements (Aspire)

In addition to the general pre-requirements, ensure:

• .NET Aspire — as of .NET Aspire 9.2+, Aspire is distributed as a NuGet package (not a workload). The GridLab.Gmss.AppHost project already references the required packages. Simply ensure you have the .NET 10+ SDK installed.

• Docker Desktop must be running (Aspire uses it to spin up containers for PostgreSQL, Valkey, RabbitMQ, etc.)

Authenticate with Docker Registry

Before running the application, authenticate with the private container registry:

Pre-pull Images (Recommended):

docker login
docker pull postgres:18
docker pull valkey/valkey:8
docker pull rabbitmq:4-management

Aspire AppHost Project

The solution includes the GridLab.Gmss.AppHost orchestrator project (located in aspire/GridLab.Gmss.AppHost). It wires up all application hosts and infrastructure:

Databases provisioned:

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 for without debugging), or from the command line:

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

   Aspire will:

   • Start PostgreSQL, Valkey, and RabbitMQ containers automatically
   • Run GridLab.Gmss.DbMigrator first and wait for it to complete
   • Launch GridLab.Gmss.AuthServer, then GridLab.Gmss.HttpApi.Host, then the web apps — in the correct dependency order

4. The Aspire Dashboard opens automatically, providing:

   • Resources — all running projects and containers with their 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

5. Log in to the web application using:

   • Username: platon
   • Password: 1q2w3E*

Tip: With Aspire, you no longer need to manually start each project in sequence or run docker-compose for infrastructure. Everything is orchestrated for you.

Configure User Secrets (Optional)

The AppHost uses .NET User Secrets for sensitive configuration. Secrets are automatically generated on first run, but you can override them:

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"

For more details, see the AppHost README.

Application Startup Sequence (Manual — Without Aspire)

Follow this order to launch the solution successfully:

1. Database & Authentication Setup:

   • First, run GridLab.Gmss.DbMigrator to create the Identity Server database

   • Then run GridLab.Gmss.AuthServer since other applications depend on it for authentication

2. API Layer

   • Run GridLab.Gmss.HttpApi.Host to start the API backend, which is required by the web application

3. Main Application

   • Launch GridLab.Gmss.Web and log in using:
     • Username: platon
     • Password: 1q2w3E*

4. Public Website (Optional)

   • Run GridLab.Gmss.Web.Public to start the application's landing page

Docker Deployment

The solution includes complete Docker support with Dockerfiles, docker-compose configuration, and automation scripts. You can quickly build and run the entire application stack in an isolated Docker network with health monitoring.

Running the Application Stack

Execute the docker-run.ps1 script to:

• Generate developer certificates using mkcert (if not already present) for HTTPS
• Launch the complete application stack via docker-compose in detached mode

Note: Developer certificate is only valid for localhost domain. If you want to deploy to a real DNS in a production environment, use LetsEncrypt or similar tools.

Accessing the Applications

Each proje type has different port. Start your web application from one the following addresses:

• MVC: https://localhost:44344

Default login credentials:

• Username: platon
• Password: 1q2w3E*

Public Web Application

Open https://localhost:44372/ URL in your browser to test the public website application.