> For the complete documentation index, see [llms.txt](https://docs.elimity.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.elimity.com/reference-manual/v3.44.2/server-configuration.md).

# Server configuration

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

## HJSON configuration file

We recommend mounting a directory containing this file at `/app/config`. Alternatively, you can pass this entire HJSON object using a single environment variable: `INSIGHTS_CONFIG_HJSON`.

{% hint style="warning" %}
An important note for users migrating from YAML configuration files: the `ListeningPort`, `LogFile` and `PrefillCache` options are not available here. More specifically, Elimity Insights will always listen on port 80, log to `stderr` and never prefill caches when using HJSON configuration files.
{% endhint %}

### The `config.hjson` configuration file

Refer to the following attachment as a starting point:

```hjson
{
  "baseUrl": "https://example.com:8081",
  "defaultAccountEmail": "admin@example.com",
  "encryptionKey": "place-base64-encoding-of-256-bit-key-here",
  "gatewayOAuth2": {
    "clientId": "gateway-client-id",
    "clientSecret": "gateway-client-secret",
    "tokenUrl": "gateway-token-url"
  },
  "mailFrom": "noreply@elimity.com",
  "oidcClientId": "your-oidc-client-id",
  "oidcClientSecret": "your-oidc-client-secret",
  "oidcIssuer": "your-oidc-issuer",
  "organisationName": "Your company",
  "pgAzureManagedIdentity": false,
  "pgConnStr": "postgres://user:password@db.yourdomain.com: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:

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

## YAML configuration files

{% hint style="danger" %}
Please note that this will be the last release to support YAML file configuration. We strongly recommend migrating to the unified `config.hjson` format or the `INSIGHTS_CONFIG_HJSON` environment variable.
{% endhint %}

By default, the Elimity Insights server reads configuration options from files at `config/elimity.yml` and `config/secrets.yml`. We recommend simply mounting a directory containing these files at `/app/config`.

### The `elimity.yml` configuration file

Most configuration options for Elimity Insights servers reside in the `elimity.yml` file. Refer to the following attachment as a starting point:

{% file src="/files/tXsaGz4P4fP4EGDGy0Z2" %}

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

<table data-full-width="true"><thead><tr><th>Configuration option</th><th>Value type</th><th>Default value</th><th>Description</th></tr></thead><tbody><tr><td><code>AccessReviewToolbarBackgroundColor</code></td><td><code>string</code></td><td><code>""</code></td><td>CSS specification for the background color of toolbars in access review wizards. Use <code>""</code> to stick with the default of Elimity's primary blue color.</td></tr><tr><td><code>AccessReviewToolbarLogoPath</code></td><td><code>string</code></td><td><code>""</code></td><td>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 <code>""</code> to stick with the default white Elimity logo.</td></tr><tr><td><code>AccessReviewToolbarTextColor</code></td><td><code>string</code></td><td><code>""</code></td><td>CSS specification for the text color of toolbars in access review wizards. Defaults to white.</td></tr><tr><td><code>BaseURL</code></td><td><code>string</code></td><td></td><td>URL indicating where the Elimity Insights server is hosted, e.g. <code>http://localhost:8080</code>.</td></tr><tr><td><code>DefaultAccountEmail</code></td><td><code>string</code></td><td><code>""</code></td><td>If this value is not set to <code>""</code> and there are no user accounts or invites in the database, then the Elimity Insights server will send an invite to this email address.</td></tr><tr><td><code>ListeningPort</code></td><td><code>number</code></td><td><code>8080</code></td><td>The Elimity Insights server will listen for HTTP traffic on this port.</td></tr><tr><td><code>LogFile</code></td><td><code>string</code></td><td><code>""</code></td><td>The Elimity Insights server will write logs to the file at this path. Use <code>""</code> to let the server log to the standard error stream.</td></tr><tr><td><code>LoginPageBackgroundPath</code></td><td><code>string</code></td><td><code>""</code></td><td>File path for overriding the background image on the login page. Use <code>""</code> to stick with Elimity's default image.</td></tr><tr><td><code>MailSender</code></td><td><code>string</code></td><td></td><td>Sender address for outgoing emails.</td></tr><tr><td><code>OIDCClientID</code></td><td><code>string</code></td><td></td><td>Client identifier to use for OIDC authentication.</td></tr><tr><td><code>OIDCProvider</code></td><td><code>string</code></td><td></td><td>URL of the OIDC provider to use for authentication (search for the <code>issuer</code> property in your OIDC discovery document).</td></tr><tr><td><code>OrganisationName</code></td><td><code>string</code></td><td></td><td>The name of your organization; only affects the OIDC login button label.</td></tr><tr><td><code>PrefillCache</code></td><td><code>boolean</code></td><td><code>false</code></td><td>Enable this option if you want to prefill the relationship cache for faster queries at the cost of a slow startup and high memory usage.</td></tr><tr><td><code>ReadTimeOutMinutes</code></td><td><code>number</code></td><td><code>5</code></td><td>Maximum number of minutes the server should spend on reading incoming requests.</td></tr><tr><td><code>SupportCustomMailServer</code></td><td><code>boolean</code></td><td><code>false</code></td><td>Determines whether admins can configure a custom mail server.</td></tr><tr><td><code>SupportPageUrl</code></td><td><code>string</code></td><td><code>""</code></td><td>Adds an additional support link in the UI toolbar, unless this is set to <code>""</code>.</td></tr><tr><td><code>TemplatesPath</code></td><td><code>string</code></td><td><code>""</code></td><td>The directory path to use for overriding various HTML and plain-text templates in Elimity Insights; stick to the default of <code>""</code> to use standard built-in templates. Refer to <a href="/pages/oLVwgLHKsskp2YDBP4L4">our official documentation</a> for additional information.</td></tr><tr><td><code>WriteTimeOutMinutes</code></td><td><code>number</code></td><td><code>15</code></td><td>Maximum number of minutes the server should spend on writing outgoing responses.</td></tr></tbody></table>

### The `secrets.yml` configuration file

Elimity Insights servers read the more sensitive configuration options from a separate `secrets.yml` file. Again you can refer to the following attachment as a starting point:

{% file src="/files/OHLJ3okpvF4xPb38UrfI" %}

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

<table data-full-width="true"><thead><tr><th>Configuration option</th><th>Value type</th><th>Default value</th><th>Description</th></tr></thead><tbody><tr><td><code>DatabaseAzureManagedIdentity</code></td><td><code>boolean</code></td><td><code>false</code></td><td>If set to <code>true</code>, then Elimity Insights will connect to PostgreSQL with Azure Managed Identity; refer to <a href="https://learn.microsoft.com/en-us/azure/postgresql/security/security-connect-with-managed-identity">the official documentation</a> for additional information.</td></tr><tr><td><code>DatabaseURL</code></td><td><code>string</code></td><td></td><td>PostgreSQL connection string that the server should use for its database connections.</td></tr><tr><td><code>EnableGatewayOAuth2</code></td><td><code>boolean</code></td><td><code>false</code></td><td>Determines whether Elimity Insights should use OAuth2 for authentication to gateways.</td></tr><tr><td><code>EncryptionKey</code></td><td><code>string</code></td><td></td><td>Base64-encoded AES-256 key for encrypting secrets in the configured database. We suggest using a command like <code>openssl rand -base64 32</code> to generate and encode such a key.</td></tr><tr><td><code>GatewayOAuth2ClientId</code></td><td><code>string</code></td><td></td><td>OAuth2 client ID to use when retrieving an access token for gateway authentication; only required if <code>EnableGatewayOAuth2</code> is <code>true</code>.</td></tr><tr><td><code>GatewayOAuth2ClientSecret</code></td><td><code>string</code></td><td></td><td>OAuth2 client secret to use when retrieving an access token for gateway authentication; only required if <code>EnableGatewayOAuth2</code> is <code>true</code>.</td></tr><tr><td><code>GatewayOAuth2EndpointParams</code></td><td><code>record[string]</code></td><td></td><td>Record mapping extra OAuth2 token endpoint parameters to <a href="https://expr-lang.org/">Expr</a> programs; refer to <a href="/pages/heQKEFKnXvtOWkbZzqDe">our dedicated documentation</a> for additional information.</td></tr><tr><td><code>GatewayOAuth2TokenUrl</code></td><td><code>string</code></td><td></td><td>OAuth2 token URL to use when retrieving an access token for gateway authentication; only required if <code>EnableGatewayOAuth2</code> is <code>true</code>.</td></tr><tr><td><code>OIDCClientSecret</code></td><td><code>string</code></td><td></td><td>Client secret to use for OIDC authentication.</td></tr><tr><td><code>SMTPEnableAuth</code></td><td><code>boolean</code></td><td><code>true</code></td><td>Determines whether Elimity Insights should authenticate to the configured SMTP server.</td></tr><tr><td><code>SMTPEnableOAuth2</code></td><td><code>boolean</code></td><td><code>false</code></td><td>Determines whether Elimity Insights should use OAuth2 for authentication to the configured SMTP server.</td></tr><tr><td><code>SMTPHostname</code></td><td><code>string</code></td><td></td><td>The hostname of the SMTP server to which Elimity Insights sends emails.</td></tr><tr><td><code>SMTPOAuth2ClientId</code></td><td><code>string</code></td><td></td><td>Client ID for OAuth2 authentication to the configured SMTP server; only required if <code>SMTPEnableAuth</code> and <code>SMTPEnableOAuth2</code> are <code>true</code>.</td></tr><tr><td><code>SMTPOAuth2ClientSecret</code></td><td><code>string</code></td><td></td><td>Client secret for OAuth2 authentication to the configured SMTP server; only required if <code>SMTPEnableAuth</code> and <code>SMTPEnableOAuth2</code> are <code>true</code>.</td></tr><tr><td><code>SMTPOAuth2Scope</code></td><td><code>string</code></td><td></td><td>Scope for OAuth2 authentication to the configured SMTP server; only required if <code>SMTPEnableAuth</code> and <code>SMTPEnableOAuth2</code> are <code>true</code>.</td></tr><tr><td><code>SMTPOAuth2TokenUrl</code></td><td><code>string</code></td><td></td><td>Token URL for OAuth2 authentication to the configured SMTP server; only required if <code>SMTPEnableAuth</code> and <code>SMTPEnableOAuth2</code> are <code>true</code>.</td></tr><tr><td><code>SMTPPassword</code></td><td><code>string</code></td><td></td><td>Password for direct authentication to the configured SMTP server; only required if <code>SMTPEnableAuth</code> is <code>true</code> and <code>SMTPEnableOAuth2</code> is <code>false</code>.</td></tr><tr><td><code>SMTPPort</code></td><td><code>number</code></td><td></td><td>The port of the SMTP server to which Elimity Insights sends emails.</td></tr><tr><td><code>SMTPUser</code></td><td><code>string</code></td><td></td><td>Username for authentication to the configured SMTP server; only required if <code>SMTPEnableAuth</code> is <code>true</code>.</td></tr></tbody></table>

## 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 |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.elimity.com/reference-manual/v3.44.2/server-configuration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.