Application settings¶

CxReports supports a number of settings that can be configured in the appsettings.json file. The settings are divided into sections, each of which is described below.

Connection settings (required)¶

Database: The connection string to the database where the reports are stored.

Example

"ConnectionStrings": {
    "Database": "Host=localhost;Port=5434;Database=cxreports;Username=cxr;Password=cxr"
}

Encryption (required)¶

Key: The encryption key used to encrypt sensitive data in the database.
Vector: The encryption vector used to encrypt sensitive data in the database.

Example

"Encryption": {
    "Key": "12345678901234567890123456789012",
    "Vector": "1234567890123456"
}

LicenseConfiguration¶

You can set CxReports license key here, without logging into the application. This will also prevent anyone from removing the license key from the application.

Example

"LicenseConfiguration": {
  "Key": "your-license-key",
  "ServerName": "your-license-server-name",
}

AppUrl¶

Used to specify the root URL of the application. This is needed in the process of automatic report generation.

Example

"AppUrl": "https://demo.cx-reports.app",

PathBase¶

Used the specify the base path of the application. This in required if you are hosting CxReports in a subdirectory of a domain. For example, if you are hosting CxReports in https://example.com/reports, you should set the PathBase to /reports. It can be omitted if the application is hosted in the root of the domain.

Example

"PathBase": "/reports",

Password Policy¶

Settings for the password policy. The password policy is used to enforce password complexity rules.

Example

"PasswordPolicy": {
  "RequiredLength": 8,
  "RequireNonAlphanumeric": false,
  "RequireDigit": true,
  "RequireUppercase": true,
  "RequireLowercase": true
}

RootUser¶

Initial user that will be created when the application starts. This user will have the root privileges required to create new users and workspaces. In case you loose access to the app, you can use this setting to create a new user.

Example

"RootUser": {
  "Email": "[email protected]",
  "Password": "[your-password]",
  "DisplayName": "Root User"
  //"ApiToken": "[api-token-for-the-root-user]"
}

Uncomment and set the ApiToken field to allow root access using the API.

Note

The password must meet the required complexity rules - a minimum length and a mix of uppercase letters, lowercase letters, numbers, and special characters.

SmtpServer¶

Settings for the SMTP server that will be used to send emails. This is needed for sending reports via email. Throttling settings can be omitted if you don't want to throttle the number of emails sent in a given interval (in seconds)

Example

"SmtpServer": {
  "From": "[email protected]",
  "ReplyTo": "[email protected]",
  "Host": "localhost",
  "Port": 1025,
  "Username": "",
  "Password": "",
  "EnableSsl": false,
  "DegreeOfParallelism": 10
  "Throttling": {
    "MaxEmailsPerInterval": 2,
    "ThrottleInterval": 1
  }
}

Swagger¶

Settings for the Swagger UI. Swagger is a tool that helps you document and test your API. It is available at /swagger endpoint.

Example

"Swagger": {
  "Enabled": true,
}

Hangfire¶

Settings to enable the Hangfire dashboard. Hangfire is a tool that helps you manage background jobs. It is available at /hangfire endpoint.

Example

"Hangfire": {
  "Dashboard": {
    "Enabled": true
  }
}

Puppeteer¶

Puppeteer is used for report exports. In case you want to use a custom puppeteer executable, you can specify the path to it here.

Example

"Puppeteer": {
  "UsePreinstalledChrome": true,
  "ChromePath": "/path/to/chrome"
},

Serilog¶

Settings for the Serilog logger. Serilog is a logging library that is used to log application events. More information available here

Settings for the Google login. This is used to enable Google login in the application.

Example

"GoogleLogin": {
  "Enabled": true,
  "SupportedDomains": ["your-domain.com"],
  "ClientId": "your-client-id",
  "ClientSecret": "your-client-secret"
}

Settings for the Microsoft login. This is used to enable Microsoft login in the application.

Example

"MicrosoftLogin": {
  "Enabled": true,
  "SupportedDomains": ["your-domain.com"],
  "ClientId": "your-client-id",
  "ClientSecret": "your-client-secret"
}

This settings is used to disable or enable email/password login. By default, email/password login is enabled.

Example

"PasswordLogin": {
  "Enabled": true
}

HTTPS Redirect¶

If you are using HTTPS, you can enable this setting to redirect HTTP requests to HTTPS. This will be automatically detected if you are using Google or Microsoft login.

Example

"ForceHttps": true

Workspace Initialization¶

The Init configuration enables automated workspace setup and data import during application startup, primarily for CI/CD pipelines.

Inline Configuration

"Init": {
  "Enabled": true,
  "Workspaces": {
    "[workspace-code]": {
      "Name": "Default Workspace",
      "Description": "Default workspace created during initialization",
      "Recreate": true,
      "FileSystemImportPath": "[./path-to/filesystem.zip]",
      "ImportFilePath": "[./path-to/CxReportsExport.json]"
    }
  }
}

External Configuration

"Init": {
  "Enabled": true,
  "WorkspacesFilePath": "[./path-to/workspaces.json]"
}

Configuration Properties¶

Root Level:

Enabled: Activates initialization on startup
Workspaces: Inline workspace definitions (object)
WorkspacesFilePath: Path to external JSON/JSONC workspace configuration

Execution Order & Precedence

Both external and inline workspace definitions can be used simultaneously within the same configuration.
External workspace definitions override inline definitions with matching keys when Recreate: true.

Workspace Object:

Name: Workspace display name
Description: Optional workspace description
Recreate: Force recreation if a workspace with the same code exists
FileSystemImportPath: Path to filesystem resources
ImportFilePath: Path to workspace data (JSON files generated via the data export feature)

Note

The file import supports individual files, directory structures, and compressed archives containing supported file types only. Failed imports stop the initialization and prevent the program from starting.

External Configuration File¶

External workspace files use the same syntax as inline workspace objects, enabling configuration decoupling and environment-specific presets:

workspaces.json

{
  "dev": {
    "Name": "Development",
    "Description": "Default workspace created for the development environment created during initialization",
    "Recreate": true,
    "FileSystemImportPath": "[./path-to/dev-filesystem.zip]",
    "ImportFilePath": "[./path-to/CxReportsExport.json]"
  },
  "prod": {
    "Name": "Production",
    "Description": "Default workspace created for the production environment created during initialization",
    "Recreate": false,
    "FileSystemImportPath": "[./path-to/prod-filesystem.zip]",
    "ImportFilePath": "[./path-to/CxReportsExport.json]"
  }
}

Application settings¶

Connection settings (required)¶

Encryption (required)¶

LicenseConfiguration¶

AppUrl¶

PathBase¶

Password Policy¶

RootUser¶

SmtpServer¶

Swagger¶

Hangfire¶

Puppeteer¶

Serilog¶

Google Login (^1.13.0)¶

Microsoft Login (^1.13.0)¶

Password login¶

HTTPS Redirect¶

Workspace Initialization¶

Configuration Properties¶

External Configuration File¶