Readme.md

Lombiq Hosting - Tenant Maintenance for Orchard Core

About

With the help of this module you can execute maintenance tasks on tenants. These tasks can be anything that you want to run on tenants, like updating the tenants' URL based on the app configuration.

Documentation

Please see the below features for more information.

Lombiq.Hosting.Tenants.Maintenance

This is the core functionality required to execute maintenance tasks on tenants. It is available on any tenant. To make your application execute maintenance tasks, you need to add the following to your Startup.cs:

public void ConfigureServices(IServiceCollection services) =>
    services.AddOrchardCms(
        builder => builder.AddTenantFeatures(Lombiq.Hosting.Tenants.Maintenance.Constants.FeatureNames.Maintenance));

To add new maintenance tasks, you need to implement the IMaintenanceProvider interface and register it as a service.

Lombiq.Hosting.Tenants.Maintenance.AddSiteOwnerPermissionToRole

It's a maintenance task that adds the SiteOwner permission to a role set in the app configuration. It is available on any tenant.

The following configuration options are available to set the role:

{
  "OrchardCore": {
    "Lombiq_Hosting_Tenants_Maintenance": {
      "AddSiteOwnerPermissionToRole": {
        "IsEnabled": true,
        "RoleName": "NameOfTheRole"
      }
    }
  }
}

Lombiq.Hosting.Tenants.Maintenance.UpdateSiteUrl

It's a maintenance task that updates the site's base URL in the site settings based on the app configuration. It is available on any tenant.

To make your application execute this task, you need to add the following to your Startup.cs:

public void ConfigureServices(IServiceCollection services) =>
    services.AddOrchardCms(
        builder => builder.AddTenantFeatures(Lombiq.Hosting.Tenants.Maintenance.Constants.FeatureNames.UpdateTenantUrl));

The following configuration options are available to set the site URL:

{
  "OrchardCore": {
    "Lombiq_Hosting_Tenants_Maintenance": {
      "UpdateSiteUrl": {
        "IsEnabled": true,
        "SiteUrl": "https://domain.com/{TenantName}",
        "DefaultTenantSiteUrl": "https://domain.com"
      }
    }
  }
}

NOTE: The {TenantName} placeholder will be replaced with the actual tenant name automatically.

Defining each tenant's URL separately is also an option, in this case, you have to use the SiteUrlFromTenantName property instead of SiteUrl and add your tenants' name and URL:

{
  "OrchardCore": {
    "Lombiq_Hosting_Tenants_Maintenance": {
      "UpdateSiteUrl": {
        "IsEnabled": true,
        "DefaultTenantSiteUrl": "https://domain.com",
        "SiteUrlFromTenantName": {
          "Tenant1": "https://domain.com/custom-url",
          "Tenant2": "https://custom-domain.com"
        }
      }
    }
  }
}

Lombiq.Hosting.Tenants.Maintenance.UpdateShellRequestUrls

It's a maintenance task that updates the shell's request URLs in each tenant's shell settings based on the app configuration. It is available only for the default tenant.

The following configuration options are available to set the shell request URLs:

{
  "OrchardCore": {
    "Lombiq_Hosting_Tenants_Maintenance": {
      "UpdateShellRequestUrl": {
        "IsEnabled": true,
        "DefaultShellRequestUrl": "domain.com",
        "RequestUrl": "{TenantName}.domain.com",
        "DefaultShellRequestUrlPrefix": "",
        "RequestUrlPrefix": "{TenantName}"
      }
    }
  }
}

NOTE: The {TenantName} placeholder will be replaced with the actual tenant name automatically.

Lombiq.Hosting.Tenants.Maintenance.RemoveUsers

It's a maintenance task that removes users from the database with the given email domain. It is available only for the default tenant. Useful if you have Azure AD enabled in your production environment and you want to reset staging to the production database. Then you would get "System.InvalidOperationException: Provider AzureAD is already linked for userName" error, so deleting those users will solve the error.

The following configuration should be used to allow the maintenance to run:

{
  "OrchardCore": {
    "Lombiq_Hosting_Tenants_Maintenance": {
      "RemoveUsers": {
        "IsEnabled": true,
        "EmailDomain": "example.com"
      }
    }
  }
}

Lombiq.Hosting.Tenants.Maintenance.ChangeUserSensitiveContent

It's a maintenance task that depersonalizes the user-names, e-mail addresses and passwords, so they are changed to realistic but random values. The maintenance task runs only on the tenants that are added to the TenantNames property.

The following configuration should be used to allow the maintenance to run:

{
  "OrchardCore": {
    "Lombiq_Hosting_Tenants_Maintenance": {
      "ChangeUserSensitiveContent": {
        "IsEnabled": true,
        "TenantNames": "Default, Tenant1, Tenant2",
        "EmailExcludePattern": ".+@(lombiq.com|example.com)$"
      }
    }
  }
}

Any user accounts with an e-mail matching the EmailExcludePattern regex will not be depersonalized.

Lombiq.Hosting.Tenants.Maintenance.DeleteElasticsearchIndices

This contains a maintenance task that deletes all Elasticsearch indices related to the tenant that is being activated, and another one that rebuilds them.

It also contains a middleware that deletes all Elasticsearch indices related to the tenant, but it does that before the tenant setup. This is useful when you want to delete the indices before the tenant setup, so you can create indices from a recipe during setup. To be able to use the middleware before setup this feature must be added as a setup feature. You can do this with OrchardCoreBuilder.AddSetupFeatures(Lombiq.Hosting.Tenants.Maintenance.Constants.FeatureNames.DeleteElasticsearchIndicesBeforeSetup);

The following configuration should be used to allow the maintenance to run and for the middleware to be added:

{
  "OrchardCore": {
    "Lombiq_Hosting_Tenants_Maintenance": {
      "ElasticsearchIndicesOptions": {
          "DeleteMaintenanceIsEnabled": true,
          "RebuildMaintenanceIsEnabled": true,
          "BeforeSetupMiddlewareIsEnabled": true
      }
    }
  }
}