Configuration (Connect 2022)

General

The Connect Server is usually configured using JSON files, which are located in the installation directory of the application. In special cases, overriding via environment variables or via command line parameters is possible.

Default configuration

The default configuration is located in the appsettings.Default.json file. This file should not be changed directly, because these changes may be overwritten by a later upgrade.

Installation-specific configuration

If an installation-specific configuration is to be created, it is recommended to copy the file "appsettings.Default.json" into a file with the name "appsettings.json". This file will not be overwritten in case of an upgrade, so the configuration settings stored here will remain.

The default configuration is still taken into account here. The installation-specific configuration must therefore only contain the desired deltas.

Environment-specific configuration

If an installation directory is used in different environments (e.g. in a template for containers), environment-specific configurations can be created. For this purpose, the file "appsettings.Default.json" is converted into a file with the name "appsettings.{environment}.json" copied ({environment} must be replaced by the name of the corresponding environment).

In this scenario, the environment can be specified at runtime using the environment variable "ASPNETCORE_ENVIRONMENT". Usually the values "Development", "Staging" and "Production" are used here, the default value is "Production".

The default configuration and any existing installation-specific configuration are still taken into account. The environment-specific configurations must therefore only contain the desired deltas.

The use of the "Development" environment should be avoided in production environments, as this activates additional debugging functionalities.

Explicit configuration

If required, additional configuration files can be specified in the command line via the argument "settings=...", "-settings=...", "--settings=..." or "/settings=...". This will check if the specified configuration file exists and will print an error message if necessary. This check can be disabled by appending a question mark to the file name. Thus also optional configuration files can be specified in the command line.

The default configuration as well as the installation-specific configuration and the environment-specific configuration(s) are still taken into account. The explicit configurations in this case only have to contain the desired deltas.

Priority of the configuration types

If multiple configurations are available, they are applied in the following order:

1. Default configuration (appsettings.Default.json)

2. Environment-specific configuration (appsettings.{environment}.json)

3. Installation-specific configuration (appsettings.json)

4. Explicit configuration

5. Override via environment variables

6. Override via command line

Structure of the configuration file

The configuration file for the Connect Server is a JSON file with a JSON object as the root element. The corresponding child elements are described in the following chapters.

The AllowedHosts section (JSON value of type String).

This section allows you to restrict the host names to which the web server can be bound. Thus, access via unwanted host names or via IP addresses can be prevented. Multiple values can be separated by a semicolon. For more information, see the following link:

Example

...
  "AllowedHosts": "connect.mycompany.com;localhost",
...

The Debug section (JSON object)

This section contains settings for error analysis.

The section HttpLogging (JSON Object)

In this section, logging of incoming and outgoing HTTP traffic can be enabled. Please note that a considerable amount of data can be written to the logs when this is done and that logging has a noticeable impact on the performance of the overall system. The functionality should only be enabled if the target of the logging is a file or the console. The following values can be stored here:

The EnableBackgroundExceptions section (JSON value of type Boolean).

This value controls the handling of exceptions that occur during background processing. If possible, this option should not be defined or set to the value false. The value true only makes sense during debugging or within unit tests.

Example

...

  "Debug": {
    "HttpLogging": {
      "Enabled": false,
      "Include": [
        ".*"
      ],
      "Exclude": [
        "^(http|https)://[^/]+/_content/",
        "^(http|https)://[^/]+/_framework/",
        "^(http|https)://[^/]+/api/",
        "^(http|https)://[^/]+/css/",
        "^(http|https)://[^/]+/font/",
        "^(http|https)://[^/]+/js/",
        "^(http|https)://[^/]+/lib/",
        "^(http|https)://[^/]+/[sS]erver/",

        "^(http|https)://[^/]+/$",
        "^(http|https)://[^/]+/favicon.ico$",
        "^(http|https)://[^/]+/index.html$",
        "^(http|https)://[^/]+/[sS]erver$",
        "^(http|https)://[^/]+/[^/]+.css$"
      ],
      "ForceHexDump": false
    },
    "EnableBackgroundExceptions": false
  },
  
...

The Endpoints section (JSON Array)

This section is used to configure the integrated web server and contains an array with information about the endpoints. The individual elements of the array have the following properties:

Example

...
  
  "Endpoints": [
    {
      "Uri": "http://*:80"
    },
    {
      "Uri": "https://*:443",
      "Certificate": {
        "Source": "File",
        "Path": "C:\Certificates",
        "Name": "Certificate.pfx",
        "Password": "CertificatePassword"
      }
    },
    {
      "Uri": "https://192.168.100.100:444",
      "Certificate": {
        "Source": "Store",
        "SerialNumber": "0123456789"
      }
    }
  ],
  
...

The "Frontend" section (JSON object)

The SupportedLanguages section (JSON array with string type values).

This section defines the languages that can be selected in the dialog for maintaining language-dependent texts. Both generic language keys (such as "en" or "de") and area-specific language keys (such as "en-US", "en-UK", "de-DE" or "de-AT") are supported.

Example

...

  "Frontend": {
    "SupportedLanguages": [ "de", "en", "es", "fr", "it", "nl" ]
  },

...

The Logging section (JSON object)

This section contains another JSON object called "LogLevel" which defines the level of detail of the log output. The property "Default" contains the default setting, other properties may define different settings for specific .NET namespaces. The following values are supported for the level of detail: "Trace", "Debug", "Information", "Warning" and "Error".

Example

...

  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "IdentityServer4": "Warning",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },

...

If required, the level of detail can be specified depending on the logging target (console, event log, etc.). Further information can be found under the following link:

The Security section (JSON object)

The IpFiltering section (JSON object)

In this section, access to the Connect Server can be restricted to specific IP addresses. The following values can be stored here:

The JsonEncryption section (JSON object)

To avoid important informations (e.g. passwords) in plain text, they can be encrypted before being stored in files or in the database. The exact behavior is defined by the following properties:

Example

...

  "Security": {
    "IpFiltering": {
      "Enabled": false,
      "Blacklist": [
      ],
      "Whitelist": [
        "::1",
        "127.0.0.1",
        "192.168.0.0/16"
      ]
    },
    "JsonEncryption": {
      "Enabled": true,
      "Key": "MySecretKey!"
    }
  },

...

The Workspace section (JSON object)

This section contains configuration data for the connection to a specific data store (workspace). The following values can be stored here:

Example

...
  
  "Workspace": {
    "Id": "connect",
    "DataSource": {
      "DbType": "SqlServer",
      "ConnectionString": "Data Source=.\\SQLEXPRESS;Initial Catalog=connect;Integrated Security=True;Connect Timeout=30;Encrypt=False;TrustServerCertificate=False;ApplicationIntent=ReadWrite;MultiSubnetFailover=False"
      "RetentionPeriods": {
        "OpenContexts": 3,
        "CompletedContexts": 1
      }
    },
    "ConnectObjects": {
      "Provider": "Database",
      "RootPath": ""
    },
    "DbLogging": {
      "LogLevel": "Warning",
      "EnableSensitiveDataLogging": false,
      "EnableDetailedErrors": true
    }
  }

...

Example configuration

The following example shows the possible Connect-specific configuration settings:

{
  "AllowedHosts": "*",

  "Debug": {
    "HttpLogging": {
      "Enabled": false,
      "Include": [
        ".*"
      ],
      "Exclude": [
        "^(http|https)://[^/]+/_content/",
        "^(http|https)://[^/]+/_framework/",
        "^(http|https)://[^/]+/api/",
        "^(http|https)://[^/]+/css/",
        "^(http|https)://[^/]+/font/",
        "^(http|https)://[^/]+/js/",
        "^(http|https)://[^/]+/lib/",
        "^(http|https)://[^/]+/[sS]erver/",

        "^(http|https)://[^/]+/$",
        "^(http|https)://[^/]+/favicon.ico$",
        "^(http|https)://[^/]+/index.html$",
        "^(http|https)://[^/]+/[sS]erver$",
        "^(http|https)://[^/]+/[^/]+.css$"
      ],
      "ForceHexDump": false
    }
  },

  "Endpoints": [
    {
      "Uri": "http://*:80"
    }
  ],

  "Frontend": {
    "SupportedLanguages": [ "de", "en", "es", "fr", "it", "nl" ]
  },

  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },

  "Security": {
    "IpFiltering": {
      "Enabled": false,
      "Blacklist": [
      ],
      "Whitelist": [
        "::1",
        "127.0.0.1",
        "192.168.0.0/16"
      ]
    },
    "JsonEncryption": {
      "Enabled": true,
      "Key": "MySecretKey!"
    }
  },

  "Workspace": {
    "Id": "connect",
    "DataSource": {
      "DbType": "sqlite",
      "RetentionPeriods": {
        "OpenContexts": 14,
        "CompletedContexts": 7
      }
    },
    "ConnectObjects": {
      "Provider": "filesystem",
      "RootPath": "Workspaces/connect"
    },
    "DbLogging": {
      "LogLevel": "Warning",
      "EnableSensitiveDataLogging": false,
      "EnableDetailedErrors": true
    }
  }
}

Override configuration settings

The configuration settings stored in the JSON files can be overridden if necessary. This approach makes sense especially when automating Docker-based environments.

Override with the help of environment variables

To override the value of a configuration setting an environment variable can be defined with the prefix "DOTNET_" or "ASPNETCORE_" followed by the path of the setting in the JSON file. A double underscore (__) should be used as path separator here.

You can find more information on this topic at the following link:

Example:

SET DOTNET_Logging__LogLevel__Default=Debug

Override via the command line

If required, configurations can also be overridden using key-value pairs as command line parameters. The name here corresponds to the path of the setting, using the ":" character as the path separator. Key-value pairs can be specified as follows:

<name1>=<value1> <name2>=<value2> ...

Example:

GalileoGroup.Connect.Server.exe Logging:LogLevel:Default=Debug