Configuration Parameters

This table lists all configurable parameters of Katalogue, and where they can be set. Secrets can be set both as environment variables (unsafe!) and as Docker Secrets (recommended!).

Caution

In a production scenario, inject all configuration parameters that are secrets as environment variables/secrets in the startup phase of Docker containers. Do not store secrets in the appsettings.json config file nor inject them as environment variables during the Docker build stage, as this will leave the secrets exposed in the built Docker image.

Backend Service (api)

Parameter	Category	Subcategory	Config File	Environment Variable	DB Table	Default Value	Datatype	Description
API_ENDPOINT_BASE_URL			x	x			string	Hostname of the Katalogue Backend API. Used to set the “issuer” property of the authentication tokens issued by Katalogue.
API_ENDPOINT_PATH			x	x		/api	string	Path, relative to API_ENDPOINT_BASE_URL, where the api endpoints are hosted.
COOKIE_NAME_PREFIX			x	x		katalogue	string	Name prefix of all cookies issued by Katalogue.
CORS_ORIGIN			x	x			array/string	CORS Origin whitelist. An array with URLs (or single string) that are allowed to connect to the Katalogue backend API. Normally, this should only contain the URL to the Katalogue frontend app.
ENCRYPTION_KEY			x	x (Docker Secrets)			string	Encryption key used by Katalogue to hash user passwords (local users only) and encrypt config secrets like repository password and connection passwords. This should be a long, random string. Keep it safe, it is not possible to decrypt secrets or authenticate local users if it is lost.
PORT			x	x		8080	string	Port that the Nodejs Express API (i.e. the Katalogue backend application) listens on.
TRUST_PROXY			x	x		FALSE	boolean	Flag to tell if Katalogue should trust requests from a reverse proxy server or not. Set this to TRUE if Katalogue is hosted behind a reverse proxy server.
DATA_FILES_DIRECTORY			x	x		<install_directory>/data	string	Full path to folder on the server where datasource files from e.g. manually uploaded dbt manifests will be stored.
ACCESS_TOKEN_EXPIRATION_TIME	authentication		x			60m	string	Time that an access token is valid
LOCAL_IS_ENABLED	authentication		x	x	x	TRUE	boolean	Flag to tell if Local authentication is enabled
OIDC_IS_ENABLED	authentication		x	x	x	FALSE	boolean	Flag to tell if Azure OpenID Connect authentication is enabled
REFRESH_TOKEN_EXPIRATION_TIME	authentication		x			30d	string	Time that a refresh token is valid
OIDC_APPLICATION_ID	authentication	oidc	x	x	x	NULL	string	Microsoft Azure Application (client) ID, i.e. ID of the Enterprise Application registered in Microsoft Entra ID
OIDC_AUTHORIZE_ENDPOINT	authentication	oidc	x		x	/oauth2/v2.0/authorize	string	Endpoint for OAuth2 authorization requests
OIDC_CLIENT_SECRET	authentication	oidc	x	x (Docker Secrets)	x	NULL	string	Microsoft Azure Client Secret
OIDC_DIRECTORY_ID	authentication	oidc	x	x	x	NULL	string	Microsoft Azure Directory (tenant) ID
OIDC_ENDPOINT_BASE_URL	authentication	oidc	x		x	https://login.microsoftonline.com	string	Base URL of the OAuth2 endpoint
OIDC_JWKS_ENDPOINT	authentication	oidc	x		x	/discovery/v2.0/keys	string	Endpoint to retrieve public keys
OIDC_LOGOUT_ENDPOINT	authentication	oidc	x		x	/oauth2/v2.0/logout	string	Endpoint for OAuth2 logout requests
OIDC_REDIRECT_URI	authentication	oidc	x	x	x	NULL	string	URI that Microsoft Azure should redirect to after completed authentication
OIDC_SCOPE	authentication	oidc	x	x	x	profile user.read offline_access openid	string	Scope that the configured enterprise application need access to
OIDC_TOKEN_ENDPOINT	authentication	oidc	x		x	/oauth2/v2.0/token	string	Endpoint for OAuth2 token requests
OIDC_USER_SOURCE_ID	authentication	oidc	x		x	oid	string	Name of the user unique Id property in the OpenID Connect Id token
OIDC_USER_USERNAME	authentication	oidc	x		x	upn	string	Name of the user Username property in the OpenID Connect Id token
DATABRICKS_BASE_ENDPOINT	connectors	databricks	x		x	/api/2.1/unity-catalog	string	Unity Catalog API Base URL, excluding hostname
DATABRICKS_CATALOG_ENDPOINT	connectors	databricks	x		x	/catalog	string	Unity Catalog API catalog endpoint, relative to the base URL
DATABRICKS_SCHEMA_ENDPOINT	connectors	databricks	x		x	/schema	string	Unity Catalog API schema endpoint, relative to the base URL
DATABRICKS_TABLE_ENDPOINT	connectors	databricks	x		x	/table	string	Unity Catalog API table endpoint, relative to the base URL
DATABRICKS_IS_ENABLED	connectors	databricks	x	x		TRUE	boolean	Flag to enable or disable this connector. If a connector is disabled, it cannot be used in the GUI and all connector-specific nodejs dependencies/librariers are excluded on startup. This means that the the dependency does not have to be installed if the conncetor is disabled.
DBT_DEFAULT_MANIFEST_FILENAME	connectors	dbt	x		x	manifest.json	string	Filename for the Dbt manifest json file that is used as the datasource for the Dbt connector. This property will only be used if no filename is specified in the connection URL
DBT_IS_ENABLED	connectors	dbt	x	x		TRUE	boolean	Flag to enable or disable this connector. If a connector is disabled, it cannot be used in the GUI and all connector-specific nodejs dependencies/librariers are excluded on startup. This means that the the dependency does not have to be installed if the conncetor is disabled.
IBMDB2_CODEPAGE	connectors	ibmdb2	x		x	NULL	integer	IBM DB2 database codepage, i.e. database encoding. Specify this if data imported from IBM DB2 databases display incorrectly. Note that this setting affects all IBM DB2 connectors in Katalogue, specifying a codepage per datasource is currently not supported.
IBMDB2_IS_ENABLED	connectors	ibmdb2	x	x		TRUE	boolean	Flag to enable or disable this connector. If a connector is disabled, it cannot be used in the GUI and all connector-specific nodejs dependencies/librariers are excluded on startup. This means that the the dependency does not have to be installed if the conncetor is disabled.
MSSQL_IS_ENABLED	connectors	mssql	x	x		TRUE	boolean	Flag to enable or disable this connector. If a connector is disabled, it cannot be used in the GUI and all connector-specific nodejs dependencies/librariers are excluded on startup. This means that the the dependency does not have to be installed if the conncetor is disabled.
ODBC_IS_ENABLED	connectors	odbc	x	x		TRUE	boolean	Flag to enable or disable this connector. If a connector is disabled, it cannot be used in the GUI and all connector-specific nodejs dependencies/librariers are excluded on startup. This means that the the dependency does not have to be installed if the conncetor is disabled.
ORACLE_IS_ENABLED	connectors	oracle	x	x		TRUE	boolean	Flag to enable or disable this connector. If a connector is disabled, it cannot be used in the GUI and all connector-specific nodejs dependencies/librariers are excluded on startup. This means that the the dependency does not have to be installed if the conncetor is disabled.
ORACLE_INSTANT_CLIENT_PATH	connectors	oracle	x	x			string	Oracle Instant Client path, if not the default path. See the “oracledb” nodejs package docs for more info.
POSTGRES_ENABLED	connectors	postgres	x	x		TRUE	boolean	Flag to enable or disable this connector. If a connector is disabled, it cannot be used in the GUI and all connector-specific nodejs dependencies/librariers are excluded on startup. This means that the the dependency does not have to be installed if the conncetor is disabled.
SNOWFLAKE_IS_ENABLED	connectors	snowflake	x	x		TRUE	boolean	Flag to enable or disable this connector. If a connector is disabled, it cannot be used in the GUI and all connector-specific nodejs dependencies/librariers are excluded on startup. This means that the the dependency does not have to be installed if the conncetor is disabled.
COOKIE_HTTP_ONLY	cookieHeaders		x	x		TRUE	boolean	Value of the cookie HTTPOnly attribute. Set to true in production.
COOKIE_PATH	cookieHeaders		x	x		/api	string	Value of the cookie Path attribute. Set to the base api endpoint path of the Katalogue backend API.
COOKIE_SAME_SITE	cookieHeaders		x	x		TRUE	boolean/string	Value of the cookie SameSite attribute. Set to “None” in production.
COOKIE_SECURE	cookieHeaders		x	x		FALSE	boolean	Value of the cookie Secure attribute. Set to false in production.
HTTP_LOGGING_IS_ENABLED	logging		x	x	x	FALSE	boolean	Flag to tell if all HTTP requests and their execution time to the backend API should be logged or not. WARNING! Enabling this will reduce performance and quickly fill the http_request log table.
LOG_LEVEL	logging		x	x	x	info	string	Determines the granularity of logging for the backend API service. Available levels are “critical”, “error”, “warning”, “info” and “debug”. The latter two can be set through the GUI, the others must be set in the repository database.
AUDIT_FILENAME	logging		x	x		logs/audit.json	string	Audit filename path. See the “winston” nodejs package docs for more info.
LOG_DIRNAME	logging		x	x		logs	string	Log file directory path. See the “winston” nodejs package docs for more info.
LOG_FILENAME	logging		x	x		application_%DATE%.log	string	Filename pattern for log files. See the “winston” nodejs package docs for more info.
LOG_FILENAME_DATEPATTERN	logging		x	x		YYYY-MM-DD	string	Date format for the date part of the logfile name
LOG_MAXFILES	logging		x	x		14d	string	Determines how many days old logfiles should be retained before getting deleted by the log rotation functionality.
LOG_TO_CONSOLE_IN_PROD	logging		x	x		TRUE	boolean	Flag to tell if logging should be done to console or not. Note that logging to file is always enabled and not affected by this setting. Set this to true when using managed servers, Docker etc with external monitoring tools to let them pick up the logs.
LOG_USE_UTC	logging		x	x		FALSE	boolean	Flag to tell if the log file dates should be in UTC format or the server´s timezone.
MAIL_FROM	mail		x	x	x	NULL	string	Email address that all emails will be sent from. If Email Server Type is Azure, this must be the email address of a real user account with a license that provides the account with a mailbox
MAIL_FRONTEND_URL	mail		x		x	NULL	string	Full URL to the Katalogue frontend, used to create relevant links in all emails. Example: https://katalogue.your-company.com
MAIL_HOST	mail		x	x	x	NULL	string	Hostname of the SMTP mail server
MAIL_IS_ENABLED	mail		x	x	x	FALSE	boolean	Flag to tell if the application should send emails or not
MAIL_IS_SECURE	mail		x	x	x	FALSE	boolean	Flag to tell if a secure connection should be used to the SMTP mail server or not. If true the connection will use TLS when connecting to server. If false (the default) then TLS is used if server supports the STARTTLS extension.
MAIL_PASSWORD	mail		x	x (Docker Secrets)	x	NULL	string	Password to authenticate against the SMTP mail server
MAIL_PORT	mail		x	x	x	NULL	string	Port of the SMTP mail server
MAIL_SEND_WELCOME_EMAILS	mail		x		x	TRUE	boolean	Send a welcome email with login instructions to new users when they are added to Katalogue for the first time
MAIL_SERVER_TYPE	mail		x	x	x	msgraph	string	Use Azure Microsoft Graph API or custom SMTP configuration for sending emails. Allowed values are “smtp” or “msgraph”.
MAIL_SUPPORT_EMAIL	mail		x		x	NULL	string	Email address to the Katalogue support team, used in the footer in all emails
MAIL_SUPPORT_NAME	mail		x		x	NULL	string	Name of the Katalogue support team, used in the footer in all emails
MAIL_SYSTEM_EMAILS_TO	mail		x		x	NULL	string	List of email addresses, separated by a comma, that will receive system emails such as task failure notifications. These emails are typically sent to Katalogue administrators or other IT admins.
MAIL_USERNAME	mail		x	x	x	NULL	string	Username to authenticate against the SMTP mail server
AZURE_KEY_VAULT_IS_ENABLED	passwordManagers	azureKeyVault	x		x	FALSE	boolean	Flag to tell if Microsoft Azure Key Vault is enabled
AZURE_KEY_VAULT_NAME	passwordManagers	azureKeyVault	x		x	NULL	string	Microsoft Azure Key vault name. Can be extracted from the Vault URI like so: “https://<KEY-VAULT-NAME>.vault.azure.net”
REPOSITORY_BATCH_INSERT_CHUNK_SIZE	repository		x	x		1000	integer	Number of rows that is inserted in each batch when doing batch inserts. Batch inserts are performed by some endpoints. Change this only if there are performance issues related to batch inserts.
REPOSITORY_BATCH_UPDATE_CHUNK_SIZE	repository		x	x		10000	integer	Number of rows that is updated in each batch when doing batch updates. Batch updates are performed by some endpoints. Change this only if there are performance issues related to batch inserts.
REPOSITORY_DATABASE	repository		x	x		katalogue	string	Database of the Katalogue PostgreSQL repository database
REPOSITORY_HOSTNAME	repository		x	x		localhost	string	Hostname of the Katalogue PostgreSQL repository database
REPOSITORY_PASSWORD	repository		x	x (Docker Secrets)			string	Password of the Katalogue repository database service account.
REPOSITORY_PORT	repository		x	x		5432	string	Port of the Katalogue PostgreSQL repository database
REPOSITORY_USE_SSL	repository		x	x		FALSE	boolean	Flag to enable SSL for the Katalogue PostgreSQL repository database connection.
REPOSITORY_USERNAME	repository		x	x		katalogue_superuser	string	Username of the Katalogue repository database service account.
REPOSITORY_POOL_MAX	repository	repositoryPool	x	x		300	integer	Maximum number of connections in the connection pool for the Katalogue PostgreSQL repository database connection.
REPOSITORY_POOL_MIN	repository	repositoryPool	x	x		2	integer	Minimum number of connections in the connection pool for the Katalogue PostgreSQL repository database connection.
SYNC_NESTED_USER_GROUPS	userProvisioning		x		x	TRUE	boolean	Flag to tell if the Microsoft Entra ID user group sync includes users in nested user groups or only direct members
GROUP_DESCRIPTION	userProvisioning	groupAttributeMapping	x		x	description	string	Name of the user group Description property in the user provisioning system
GROUP_EMAIL	userProvisioning	groupAttributeMapping	x		x	mail	string	Name of the user group Email name property in the user provisioning system
GROUP_NAME	userProvisioning	groupAttributeMapping	x		x	displayName	string	Name of the user group Name property in the user provisioning system
GROUP_SOURCE_ID	userProvisioning	groupAttributeMapping	x		x	id	string	Name of the user group unique Id property in the user provisioning system
MSGRAPH_ENDPOINT_BASE_URL	userProvisioning	msgraph	x		x	https://graph.microsoft.com/v1.0	string	Base URL of the Microsoft Graph API
MSGRAPH_GROUP_BASE_FILTER	userProvisioning	msgraph	x		x	NULL	string	Filter expression used in the Microsoft Graph GET request to get user groups
MSGRAPH_SCOPE	userProvisioning	msgraph	x		x	https://graph.microsoft.com/.default	string	Scope that the configured enterprise application need access to
MSGRAPH_USER_BASE_FILTER	userProvisioning	msgraph	x		x	userType eq ”Member” and surName ge ” ” and accountEnabled eq true	string	Filter expression used in the Microsoft Graph GET request to get users
USER_DEPARTMENT	userProvisioning	userAttributeMapping	x		x	department	string	Name of the user Department property in the user provisioning system
USER_EMAIL	userProvisioning	userAttributeMapping	x		x	mail	string	Name of the user Email property in the user provisioning system
USER_FULLNAME	userProvisioning	userAttributeMapping	x		x	displayName	string	Name of the user Full name property in the user provisioning system
USER_SOURCE_ID	userProvisioning	userAttributeMapping	x		x	id	string	Name of the user unique Id property in the user provisioning system
USER_TITLE	userProvisioning	userAttributeMapping	x		x	jobTitle	string	Name of the user Title property in the user provisioning system
USER_USERNAME	userProvisioning	userAttributeMapping	x		x	userPrincipalName	string	Name of the user Username property in the user provisioning system
REST_API_IS_ENABLED	restApi		x	x	x	FALSE	boolean	Flag to enable the REST API service
REST_API_OIDC_PATH	restApi		x	x	x	/oidc	string	Path, relative to API_ENDPOINT_BASE_URL, where the REST API authentication endpoints /token, /jwks etc should be hosted.
REST_API_DOCS_PATH	restApi		x	x	x	/swagger	string	Path, relative to API_ENDPOINT_BASE_URL, where the REST API documentation (swagger / OpenAPI Specification) should be hosted.
REST_API_ACCESS_TOKEN_TTL_IN_MINUTES	restApi		x	x	x	5	integer	Duration in minutes that an access token is valid. This resolves to the “exp” attribute of the access token.
REST_API_OIDC_SIGNING_KEY	restApi		x	x (Docker Secrets)	x	NULL	string	Private key used to sign access tokens for the REST API authentication endpoint. This is automatically generated if no external key (through environment variable or config file) is provided. The easiest way to generate externally provided keys is with the services/api/utils/initialize.js utility tool. The value of this parameter must be a key that is a stringified JSON object.
REST_API_CLIENT_SECRET_TTL_IN_DAYS	restApi		x	x	x	365	integer	Duration in days that a client secret is valid. Expired client secrets cannot be used to retrieve access tokens from the token endpoint. Set this to null to never expire client secrets.

Frontend Service (spa)

Note

The environment variables must be set at the Docker build stage, they cannot be injected in the Docker container startup phase due to the nature of Reactjs.

Parameter	Category	Config File	Environment Variable	Default Value	Datatype	Description
API_URL	api	x	x	http://localhost:8080/api	string	URL to the Katalogue Backend API. Used to connect the frontend service to the backend.