Server configuration

The Elimity Insights server supports many configuration options that it reads from different locations. Most of them reside in a configuration file, but this page also lists some environment variables that might be useful.

HJSON configuration file

To configure your Elimity Insights server, mount a HJSON configuration file at /app/config/config.json with the properties listed below. Alternatively, you can pass this entire HJSON object using a single environment variable: INSIGHTS_CONFIG_HJSON. Refer to the following snippet for a starting point:

{
  "baseUrl": "https://example.com:8081",
  "encryptionKey": "place-base64-encoding-of-256-bit-key-here",
  "gatewayOAuth2": {
    "clientId": "gateway-client-id",
    "clientSecret": "gateway-client-secret",
    "tokenUrl": "gateway-token-url"
  },
  "mailFrom": "[e-mail]",
  "oidcClientId": "your-oidc-client-id",
  "oidcClientSecret": "your-oidc-client-secret",
  "oidcIssuer": "your-oidc-issuer",
  "organisationName": "Your company",
  "pgAzureManagedIdentity": false,
  "pgConnStr": "postgres://user:[e-mail]:port",
  "smtpAuth": {
    "mechanism": {
      "password": "example-smtp-password",
      "type": "autoDiscover"
    },
    "username": "example-smtp-user"
  },
  "smtpHostname": "example-smtp-hostname",
  "smtpPort": 1025
}

The table below describes each supported configuration option in more detail:

Configuration option	Value type	Default value	Description
accessReviewToolbarBackgroundColor	string	""	CSS specification for the background color of toolbars in access review wizards. Use "" to stick with the default of Elimity's primary blue color.
accessReviewToolbarLogoPath	string	""	File path for overriding the logo of toolbars in access review wizards. We recommend using an image with a transparent background and a height/width ratio of approximately 1/7. Use "" to stick with the default white Elimity logo.
accessReviewToolbarTextColor	string	""	CSS specification for the text color of toolbars in access review wizards. Defaults to white.
baseUrl	string		URL indicating where the Elimity Insights server is hosted, e.g. http://localhost:8080.
encryptionKey	string		Base64-encoded AES-256 key for encrypting secrets in the configured database. We suggest using a command like openssl rand -base64 32 to generate and encode such a key.
gatewayOAuth2	option[object]		Configuration object describing how Elimity Insights should use OAuth2 for gateway authentication; omit to disable this feature.
gatewayOAuth2.clientId	string		OAuth2 client ID to use when retrieving an access token for gateway authentication.
gatewayOAuth2.clientSecret	string		OAuth2 client secret to use when retrieving an access token for gateway authentication.
gatewayOAuth2.endpointParams	record[string]		Record mapping extra OAuth2 token endpoint parameters to Expr programs; refer to our dedicated documentation for additional information.
gatewayOAuth2.tokenUrl	string		OAuth2 token URL to use when retrieving an access token for gateway authentication.
loginPageBackgroundPath	string	""	File path for overriding the background image on the login page. Use "" to stick with Elimity's default image.
mailFrom	string		Sender address for outgoing emails.
oidcClientId	string		Client identifier to use for OIDC authentication.
oidcClientSecret	string		Client secret to use for OIDC authentication.
oidcIssuer	string		URL of the OIDC provider to use for authentication (search for the issuer property in your OIDC discovery document).
organisationName	string		The name of your organization; only affects the OIDC login button label.
pgAzureManagedIdentity	boolean	false	If set to true, then Elimity Insights will connect to PostgreSQL with Azure Managed Identity.
pgConnStr	string		PostgreSQL connection string that the server should use for its database connections.
readTimeOutMinutes	integer	5	Maximum number of minutes the server should spend on reading incoming requests.
smtpAuth	option[object]		Configuration object describing how Elimity Insights authenticates with the SMTP server; omit to skip authentication entirely.
smtpAuth.mechanism	object		Configuration object describing the SMTP authentication mechanism.
smtpAuth.mechanism.clientId	string		Client ID for OAuth2 authentication to the configured SMTP server.
smtpAuth.mechanism.clientSecret	string		Client secret for OAuth2 authentication.
smtpAuth.mechanism.password	string		Password for authentication to the configured SMTP server.
smtpAuth.mechanism.scope	string		Scope for OAuth2 authentication.
smtpAuth.mechanism.tokenUrl	string		Token URL for OAuth2 authentication.
smtpAuth.mechanism.type	string		Set to "autoDiscover" for password-based authentication, or "xOAuth2" for OAuth2-based authentication.
smtpAuth.username	string		Username for authentication to the configured SMTP server.
smtpHostname	string		The hostname of the SMTP server to which Elimity Insights sends emails.
smtpPort	integer		The port of the SMTP server to which Elimity Insights sends emails.
supportCustomMailServer	boolean	false	Determines whether admins can configure a custom mail server.
supportPageUrl	string	""	Adds an additional support link in the UI toolbar, unless this is set to "".
templatesPath	string	""	The directory path to use for overriding various HTML and plain-text templates in Elimity Insights.
writeTimeOutMinutes	integer	15	Maximum number of minutes the server should spend on writing outgoing responses.

Environment variables

For most customers the aforementioned configuration files should offer all the customization options they need; the following environment variables may be useful in more advanced deployment scenarios:

Environment variable	Description
INSIGHTS_CONFIG_HJSON	If set, then Elimity Insights reads this value instead of reading the config.hjson configuration file.
HTTP_PROXY, HTTPS_PROXY, NO_PROXY	Determine which proxy the server should use for outgoing HTTP(S) requests
GOGC, GOMEMLIMIT	Can be used to tune memory usage
SSL_CERT_DIR, SSL_CERT_FILE	Determine where the server should look for certificates to verify SSL connections; only supported on Linux