> 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.42.3/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.

## Configuration files

By default, the Elimity Insights server reads configuration options from files at `config/elimity.yml` and `config/secrets.yml`. For container-based installations 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>AccessReviewRequestedChangesEmail</code></td><td><code>string</code></td><td><code>""</code></td><td>Email address to which notifications should be sent for every change request. Use <code>""</code> to skip sending these emails.</td></tr><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>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>EnableOIDCAuthentication</code></td><td><code>boolean</code></td><td><code>false</code></td><td>If enabled, the Elimity Insights server allows users to register and log in using OIDC. We highly encourage enabling this option for production deployments.</td></tr><tr><td><code>EnablePasswordAuthentication</code></td><td><code>boolean</code></td><td><code>false</code></td><td>If enabled, the Elimity Insights server allows users to register and log in using passwords. We highly discourage enabling this option for production deployments.</td></tr><tr><td><code>HttpsEnabled</code></td><td><code>boolean</code></td><td><code>true</code></td><td>If enabled, the Elimity Insights will additionally listen for HTTPS traffic on <code>TLSListeningPort</code>. It will also redirect HTTP requests arriving at <code>ListeningPort</code>. We discourage enabling this option, please deploy <a href="/reference-manual/v3.42.3/installation/http-s-proxy.md">a dedicated HTTPS proxy</a> instead. </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; only required if <code>EnableOIDCAuthentication</code> is <code>true</code>.</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); only required if <code>EnableOIDCAuthentication</code> is <code>true</code>.</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>TLSCertificate</code></td><td><code>string</code></td><td></td><td>File path where the server should read the TLS certificate for serving HTTPS; only required if <code>HttpsEnabled</code> is <code>true</code>.</td></tr><tr><td><code>TLSCertificateKey</code></td><td><code>string</code></td><td></td><td>File path where the server should read the TLS private key for serving HTTPS; only required if <code>HttpsEnabled</code> is <code>true</code>.</td></tr><tr><td><code>TLSListeningPort</code></td><td><code>number</code></td><td><code>8081</code></td><td>The Elimity Insights server will listen for HTTPS traffic on this port; only required if <code>HttpsEnabled</code> is <code>true</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="/reference-manual/v3.42.3/server-configuration/template-overrides.md">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>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="/reference-manual/v3.42.3/server-configuration/oauth2-endpoint-parameters-for-gateway-authentication.md">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; only required if <code>EnableOIDCAuthentication</code> is <code>true</code>.</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                                                                                                |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `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.42.3/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.