LeadCMS - Extendable Headless CMS

• Overview
• Sites powered by LeadCMS
• Getting started
  • Overview of the Solution Structure
  • Pre-requisites for development environment setup
  • Setting up docker containers
  • Secrets management
  • Debugging the project in local environment
  • Running automated test suite
  • Working with Database Migrations
• Plugin integration
  • Default plugins
  • Adding a new plugin
  • Plugin-level migrations

<a id="overview"></a>

Overview

OnlineSale is a light-weight, extendable headless CMS written in .NET 8. It is used to manage content for software product sites as well as automate processes like free trial activation, license generation, automated sales of licenses from website, customer journey tracking and more.

<a id="sites-powered-by-LeadCMS"></a>

Sites powered by LeadCMS

• XLTools Add-in for Excel - powerful Excel add-in designed for business users
• GIAnalyzer Add-in for Excel - turns your Excel into a powerful financial software
• TagPoint - easy-to-use app to take care of your facilities | assets | services

<a id="getting-started"></a>

Getting started

<a id="overview-solution-structure"></a>

Overview of the Solution Structure

• LeadCMS located at /src/LeadCMS folder is the core project which consists of reusable core functionalities described in Project Overview.

• LeadCMS.Tests located at /tests/LeadCMS.Tests folder is the project which consists of automated unit and integration test suite for LeadCMS core project.

• docker-compose folder contains the .yml files to spin up docker containers to provide database and logging services for development and testing environments.

• plugins folder contains a set of projects which can be plugged into core project via a common interface at the runtime.

  • All the generic functionalities are implemented in the core project, while specific requirements are implemented as separate projects which can be plugged into core project.

<a id="prerequisites"></a>

Pre-requisites for development environment setup

1. Install docker desktop for windows

   • Download docker desktop

   • Prerequisites for docker installation:

     • CPU virtualization should be enabled in BIOS settings.
     • Hyper-V and Containers windows features should be enabled.

2. Install .NET 8 SDK

3. Install/Upgrade Visual Studio IDE.

   • Visual Studio Version should be 2022 17.4 or higher, which supports .NET 8

4. Install CLI tools for Entity Framework Core.

<a id="setup-docker-containers"></a>

Setting up docker containers

LeadCMS platform integrates with two databases initially.

1. PostgreSQL
2. Elastic

• Docker containers should be created to run database services for development and testing environments.

Setting up docker containers to run automated test suite.

1. Navigate to docker-compose folder in the solution.

2. Open docker-compose.tests.yml docker file and update if necessary.

3. Open a command line tool in the same folder location.

4. Run docker compose -f docker-compose.tests.yml up command.

5. Open docker desktop and verify Postgres and Elastic containers are up and running.

Setting up docker containers for development environment

1. Navigate to docker-compose folder in the solution.

2. Open docker-compose.develop.yml docker file and update if necessary.

3. Open a command line tool in the same folder location.

4. Run docker compose -f docker-compose.develop.yml up command.

5. Open docker desktop and verify Postgres and Elastic containers are up and running.

<a id="secrets-management"></a>

Secrets management

Any secrets such as user credentials should not be stored in appsettings.json file.

• Ex: Do not store Password for Postgres and Elastic sections of appsettings.json file.

Secrets of the appsettings.json file should hold placeholders for environment variables.

• Ex:

"Email": {
    "Server": "$EMAIL__SERVER",
    "UserName": "$EMAIL__USERNAME",
    "Password": "$EMAIL__PASSWORD"
  }

• Note the format of the placeholder: Nested configuration keys are combined with a double underscore and written in capital letters.
  • Ex: Configuration key Email:Server should be written as $EMAIL__SERVER

Updating appsettings secrets in local environment

Visual Studio in-built Secret Manager tool can be used to manage all secrets in local development environment.

It will maintain a secrets.json file internally to store any configuration.

secret.json file will not be version controlled by default.

• In Visual Studio, by default Secret Manager can be accessed from UI.

• For Visual Studio Code, to enable it from UI, "Manage User Secrets" extension can be used.

• For any tool, Secret Manager can be used with dotnet commands

How to use Secret Manager feature in Visual Studio:

1. Right-click on LeadCMS project and click on Manage User Secrets.

2. Update the secrets.json file with required secrets in the format same as the appsettings.json file.

Secrets of the appsettings.tests.json file can also be managed using Secret Manager in the test project.

At runtime, secrets of appsettings.json file (or appsettings.tests.json) will be replaced by the values of secrets.json.

Updating appsettings secrets in pipeline

Secrets are stored as Variables in the pipeline and can be marked as secrets.

Pipeline variables should be assigned to Environment variables in the pipeline script.

At pipeline runtime, secrets of appsettings.json file (or appsettings.unittest.json) will be replaced by the corresponding environment variables.

<a id="run-project"></a>

Debugging the project in local environment

1. Make sure above pre-requisites and configuration settings are completed.

2. Run the project from toolbar

3. Verify whether the swagger documentation is opened in the default browser window.

<a id="run-test-project"></a>

Running automated test suite

1. Locate the project LeadCMS.Tests.

2. Locate appsettings.tests.json file and verify the database credentials.

   • Configurations available in appsettings.tests.json file will replace the same configurations in appsettings.json file at run time.
   • Refer Secrets Management for more details on storing credentials.

3. Right-click on the project and click on Run Tests or Debug Tests.

<a id="working-with-migrations"></a>

Working with Database Migrations

• Database will be created automatically using generated migration scripts when starting the application.

  • Application will first apply the migrations of core project followed by migrations of plugin projects

• However, migrations can be applied manually if need using entity framework core commands in a command line interface or package manager console.

• When a model is updated, a new migration script should be generated to update the database using entity framework core commands following the existing naming conventions.

<a id="plugin-integration"></a>

Plugin integration

• LeadCMS core project provides more generic and reusable functionalities, while a plugin project can be implemented to cater more specific requirements that may be provided by different clients.

• Core project can be published and run as a CMS without integrating any plugin, but a plugin requires the core project to be up and running.

• A plugin is connected to core project via a common interface called IPlugin.

  • Plugin should be inherited from IPlugin interface so that the core project can load all supported plugins at the application startup.

  • Any plugin-level configurations should be added to a file named pluginsettings.json within the plugin project, which is getting merged with appsettings.json.

  • Plugin loading is enabled by adding the plugin directory name to 'Plugins' section of 'appsettings.json' file

  • PluginManager class of the core project is responsible for loading all supported plugins and merging configurations into appsettings.json

  • Program class of the core project initiates the PluginManager at the application startup.

• Core project should be added as a dependency for a plugin project either as a project reference or nuget package reference so that the plugin can access interfaces and public classes for integrations.

• A plugin can also add new models and migrations with data seeding on top of core database structure.

• Example use cases for plugin integration:

  • Email service is a generic functionality of the core project and a plugin can implement a Contact Us form where it uses core email service to send email notifications.
  • Scheduled task runner is a generic functionality of the core project and a plugin can provide user-specific data, such as schedules, email templates, etc.. as input data to run scheduled tasks.

<a id="default-plugin"></a>

Default plugins

LeadCMS solution consists of a set of plugins that are already implemented.

• LeadCMS.Plugin.AzureAD :

• LeadCMS.Plugin.Email : Implementation of a generic email service that can be