Skip to content

Configuration

Jump to bottom
Dave Bauman edited this page May 18, 2022 · 6 revisions

Configuration

🎯 The default configuration file can be found here: /packages/backend/env/.env.

Configuring Insights Explorer

Configuration of Insights Explorer is done through environment variables. Environment variables can be provided in a few different ways depending on how Insights Explorer is being run.

  • Default configs are provided in the /packages/backend/env/.env file (and environment-specific overrides)
  • Overrides can be included in .env.local files
  • The docker-compose.yml includes a number of configs specific to the local services it runs
  • Environment variables can be provided to docker via -e or --env-file

Running from Source

Environment files are loaded using the dotenv-flow library. Insights Explorer provides base defaults and environment-specific overrides.

Files are loaded in this order, with later values taking precedence:

  • The default .env file provides base defaults
  • If defined, .env.local provides local overrides
  • Environment-specific files load depending on the NODE_ENV environment variable: .env.development, .env.production, .env.test
  • If defined, an environment-specific .env.*.local file provides local environment overrides

The .gitignore is configured to ignore any .env*.local files, so feel free to create .local override files without worrying about accidentally committing them~

Configuration Options

Logging Settings

Options for logging

LOG_REQUESTS

Default Value: true
Possible Values: true/false

If true, incoming web requests will be logged.

LOG_LEVEL

Default Value: info
Possible Values: trace/debug/info/warn/error

Controls which log levels are output and which are ignored. When running in development mode this defaults to trace.

LOG_FORMAT

Default Value: pretty
Possible Values: pretty/json/default (deprecated)

Controls how logs are formatted. The pretty option is colorized and pretty-printed, whereas the json option is suitable for ingestion by log collectors. When running in production mode this defaults to json.

The default value is deprecated, and works the same as pretty.

LOG_TIMESTAMPS

Default Value: true
Possible Values: true/false

When using LOGFORMAT=default, this determines whether or not timestamps are included in the log output.

Server Settings

General settings that don't fit into other categories

PORT

Default Value: 3001

Port number that the IEX service listens on.

ENCRYPTION_KEY

Default Value: none

This key is used to encrypt data at rest in the PostgreSQL database. It must be compatible with TweetNaCL's secretbox.

To obtain a suitable key, run this:

npx ts-node -e "import { generateKey } from './packages/backend/src/shared/crypto'; console.log(generateKey());"

PUBLIC_URL

Default Value: none

Specifies the user-facing URL which should be used to access Insights Explorer. It will be used to configure GitHub webhooks, or displayed in documentation.

APOLLO_SANDBOX

Default Value: true
Possible Values: true/false

Apollo Sandbox is a GraphQL IDE for exploring GraphQL schemas and running queries. This property enables (or disables) a footer link that loads Apollo Sandbox with the IEX schema link configured.

Admin Settings

Settings related to admin access.

ADMIN_USERNAMES

Default Value: ``

Allows one or more user names to be provided, separated by semicolons. If a user's username matches one of the provided names, they will be logged in as an admin.

Applies regardless of how OAUTH_PROVIDER is configured.

OAuth Settings

Configures the OAuth system to provide authorization

OAUTH_PROVIDER

Default Value: github
Possible Values: github/okta

Switches between different available OAuth providers.

OAUTH_SCOPES

Default Value: user:email,read:user
Possible Values: varies

Configures which OAuth scopes are requested. For Okta this should be set to openid,profile,email,groups.

OAUTH_AUTHORIZE_URL

Default Value: https://github.com/login/oauth/authorize
Possible Values: varies

Provides the OAuth provider's authorization URL. IEX will redirect to this URL during the login path.

OAUTH_CLIENT_ID

Default Value: none
Possible Values: varies

Short description of variable

OAUTH_CLIENT_SECRET

Default Value: none
Possible Values: varies

Short description of variable

OAUTH_PKCE_ENABLED

Default Value: false
Possible Values:

Short description of variable

OAUTH_GITHUB_ACCESS_TOKEN_URL

Default Value: https://github.com/login/oauth/access_token
Possible Values:

Short description of variable

OAUTH_OKTA_BASE_URL

Default Value: ``
Possible Values:

Short description of variable

OAUTH_OKTA_ADMIN_GROUPS

Default Value: ``

Allows one or more Okta group names to be provided, separated by semicolons. If Okta indicates a user is a member of one of the listed groups, that user will be logged in as an admin.

Only applies when OAUTH_PROVIDER is set to okta. Requires Okta to be configured to return a groups array.

GitHub Settings

Settings for connecting to GitHub. By default, Insights Explorer uses GitHub.com when no values are configured.

GITHUB_URL

Default Value: ``
Possible Values:

Short description of variable

GITHUB_REST_API_URL

Default Value: ``
Possible Values:

Short description of variable

GITHUB_GRAPHQL_API_URL

Default Value: ``
Possible Values:

Short description of variable

GITHUB_SERVICE_ACCOUNT

Default Value: ``
Possible Values:

Short description of variable

GITHUB_ACCESS_TOKEN

Default Value: ``
Possible Values:

Short description of variable

GITHUB_DEFAULT_ORG

Default Value: ``
Possible Values:

Short description of variable

GITHUB_USE_WEBHOOK

Default Value: true
Possible Values:

Short description of variable

Convertbot Settings

Settings for using Convertbot. Note: Convertbot's own settings are not documented here.

CONVERSION_SQS_URL

Default Value: ``
Possible Values:

Short description of variable

Elasticsearch Settings

Settings for connecting to Elasticsearch.

ELASTICSEARCH_NODE

Default Value: ``

Short description of variable

ELASTICSEARCH_MAX_RETRIES

Default Value: 3

Short description of variable

ELASTICSEARCH_REQUEST_TIMEOUT

Default Value: 60000

Short description of variable

ELASTICSEARCH_INIT_ON_STARTUP

Default Value: true
Possible Values: true/false

When true, the backend service will attempt to create or update Elasticsearch indices whenever it starts. This can be disabled between updates to improve startup speed. However this is not recommended as the startup performance benefit is minimal.

ELASTICSEARCH_SEARCH_TYPE

Default Value: query_then_fetch
Possible Values: query_then_fetch/dfs_query_then_fetch

In situations when few documents are distributed across many Elasticsearch shards, relevance scoring may be inaccurate. This can be improved by using dfs_query_then_fetch, which uses a pre-query to calculate global frequencies. This is not recommended for most situations.

For more details please refer to https://www.elastic.co/blog/understanding-query-then-fetch-vs-dfs-query-then-fetch.

Database Settings

Settings for connecting to the database.

DB_HOST

Default Value: ``

Short description of variable

DB_USERNAME

Default Value: ``

Short description of variable

DB_PASSWORD

Default Value: ``

Short description of variable

DB_DATABASE

Default Value: iex

Short description of variable

DB_INIT_ON_STARTUP

Default Value: true
Possible Values: true/false

When true, the backend service will attempt to apply the latest database migrations whenever it starts. This can be disabled between upgrades to improve startup speed. However this is not recommended as the startup performance benefit is minimal.

DB_DEBUG

Default Value: false
Possible Values:

Short description of variable

S3 Settings

Settings for connecting to S3 or S3-compatible object storage.

S3_BUCKET

Default Value: ``

Short description of variable

S3_REGION

Default Value: ``

Short description of variable

S3_ENDPOINT

Default Value: ``

Short description of variable

S3_FORCE_PATH_STYLE

Default Value: false
Possible Values: false/true

Path-style requests are deprecated in S3, but some S3-compatible APIs may require them (e.g. MinIO)

S3_CONCURRENCY_LIMIT

Default Value: 10
Possible Values:

Short description of variable

External Settings

Settings that link to external content, e.g. help documentation, chat support.

IEX_SCM_URL

Default Value: https://github.com/ExpediaGroup/insights-explorer

Contains a link to the source code for Insights Explorer.

EXTERNAL_DOC_URL

Default Value: ``
Possible Values:

Short description of variable

EXTERNAL_VIDEOS_URL

Default Value: ``
Possible Values:

Short description of variable

CHAT_PROVIDER

Default Value: ``
Possible Values:

Short description of variable

CHAT_CHANNEL

Default Value: ``
Possible Values:

Short description of variable

CHAT_URL

Default Value: ``
Possible Values:

Short description of variable

Insight Settings

Settings related to Insights.

INSIGHT_IGNORE_AUTHORS

Default Value: ``

Allows one or more usernames or email addresses to be provided, separated by semicolons. When syncing an Insight's authors, any authors that match username/email will be ignored.

These authors are ignored globally, in addition to any Insight-specific list of authors to ignore.

Note: changes to this value only take effect when syncing an Insight, so removing an author from an Insight requires a re-sync.

EXAMPLES_INIT_ON_STARTUP

Default Value: false
Possible Values: true/false

When true, the backend service will sync Insights from the packages/examples/insights folder. These example Insights are intended for demo or testing purposes. The sync does not skip existing Insights, and slows down startup significantly, so it's recommended to disable after the initial startup.

Not recommended for production use.

Activity Settings

Settings related to activities.

ACTIVITIES_IGNORE_LOGIN

Default Value: false
Possible Values: false/true

If true, login activities will not be tracked. When running in development mode this defaults to true to avoid unnecessary activity spam.

Clone this wiki locally