CONFIGURATION.md

RDS-NG configuration

Below is an overview of all available settings of each RDS-NG component. These settings can either be set in config.toml files (located in src/<component>/.config) or via environment variables.

Environment variables

Environment variables are always prefixed with RDS_ and written in capital letters; all dots need to replaced by underscores. A setting like authorization.refresh_attempts_limit, for example, translates to RDS_AUTHORIZATION_REFRESH_ATTEMPTS_LIMIT.

To pass environment variables into the containers, .env files can be used; these are placed inside the deployment/env directory; examples are provided in the examples subdirectory.

IMPORTANT! Environment variables can only be used in the frontend when running in develop mode! If you want to run in release mode, frontend settings must be set in its config.tomlfile (located in src/frontend/static/config).

Settings

Most settings have reasonable defaults and usually don't need to be changed. Mandatory settngs are always listed for each component and must be set in order to be able to run RDS-NG.

IMPORTANT! Always set all mandatory settings in your configuration! Otherwise, the setup will not run.

Serving multiple hosts

bridgit can serve multiple hosts using a single deployment. For this, a bunch of settings need to be set on a per-host basis; these will have a <host_id> placeholder in their setting key. For each individual host, these settings need to be supplied with the placeholder replaced by the actual host identifier.

Backend settings

The backend consists of the server and the various connectors; they all share a set of certain settings but also have their own ones as well.

Mandatory settings

• All components
  • network.api_key
• Server
  • network.server.allowed_origins
• Connectors
  • connector.target (1)
  • network.client.server_address
  • authorization.strategy
  • authorization.oauth2.server.host (2)
  • authorization.oauth2.server.authorization_endpoint (2)
  • authorization.oauth2.server.token_endpoint (2)
  • authorization.oauth2.client.id (2)
  • authorization.oauth2.client.redirect_url (2)
• Frontend
  • <host_id>.integration.host.url

(1) By default, connectors target the test instances of the corresponding service. (2) If the service uses OAUTH2 authorization.

IMPORTANT! By default, data will only be stored in memory and will thus be lost whenever the server is restarted! It is thus highly advised to configure a database for the server in order to persist data.

All components | General

Setting	Description	Type	Default value
general.debug	Whether to run in debug mode, resulting in more textual output and less restrictions.	Boolean	false
general.debug_trace	Whether to log function calls for extensive debugging.	Boolean	false

All components | Network

Setting	Description	Type	Default value
network.api_key	An arbitrary API key to access protected resources; this must be the same value on all components.	String
network.verify_sll	If enabled, SSL certificates will be verified.	Boolean	true
network.transmission_chunk_size	The size (in bytes) for network transmissions.	Number	1048576
network.regular_command_timeout	The maximum time (in seconds) for a command-reply to arrive.	Number	90.0
network.external_requests_timeout	The maximum time (in seconds) for requests to external services; set to 0 to disable.	Number	90.0

Server | Network

Setting	Description	Type	Default value
network.server.allowed_origins	A comma-separated list of allowed origins; use the asterisk (*) to allow all.	String
network.server.idle_timeout	The time (in seconds) until idle clients will be disconnected automatically; set to 0 to disable.	Number	3600

Server | Authorization

Authorization is in most cases performed using OAUTH2. The server takes care of managing and refreshing authorization tokens of external services. Connectors also use OAUTH2 to authorizate against their respective external service.

Setting	Description	Type	Default value
authorization.request_attempts_delay	The delay between token request attempts in seconds.	Number	1.0
authorization.request_attempts_limit	The maximum number of token request attempts.	Number	5
authorization.refresh_attempts_delay	The delay between token refresh attempts in seconds.	Number	30.0
authorization.refresh_attempts_limit	The maximum number of refresh attempts before removing a token; 0 disables removal.	Number	3
<host_id>.authorization.oauth2.secrets.host	The OAUTH2 secret for the host system.	String

Server | Storage

The server needs to store its data; this can either be in-memory (super volatile) or in a database. For production systems, a database should always be used; RDS-NG currently supports SQLite, PostgreSQL, MySQL and MariaDB. Note that all databases except SQLite require additional software not provided by us.

Setting	Description	Type	Default value
storage.driver	The driver to use for the storage; possible values are memory or database.	String	memory
storage.database.engine	The database backend to use; can be sqlite, postgresql, mysql or mariadb.	String	sqlite
storage.database.sqlite.file	The (absolute) filename where SQLite stores its data; if not set, an in-memory database will be used.	String
storage.database.postgresql.host	The host of the database system.	String
storage.database.postgresql.port	The port of the database system; if omitted, the default port will be used.	Number
storage.database.postgresql.database	The name of the database to use.	String	rds_ng
storage.database.postgresql.user	The database username.	String
storage.database.postgresql.password	The password for the database user.	String
storage.database.mysql.host	The host of the database system.	String
storage.database.mysql.port	The port of the database system; if omitted, the default port will be used.	Number
storage.database.mysql.database	The name of the database to use.	String	rds_ng
storage.database.mysql.user	The database username.	String
storage.database.mysql.password	The password for the database user.	String
storage.database.mariadb.host	The host of the database system.	String
storage.database.mariadb.port	The port of the database system; if omitted, the default port will be used.	Number
storage.database.mariadb.database	The name of the database to use.	String	rds_ng
storage.database.mariadb.user	The database username.	String
storage.database.mariadb.password	The password for the database user.	String

Connectors | General

Setting	Description	Type	Default value
connector.target	The URL of the connector target (i.e., its external service).	String	(the service's test instance URL)

Connectors | Network

Setting	Description	Type	Default value
network.client.server_address	The address of the server the client should automatically connect to.	String
network.client.connection_timeout	The maximum time (in seconds) for connection attempts.	Number	60.0

Connectors | Authorization

Setting	Description	Type	Default value
authorization.strategy	The authorization strategy (type) the external service uses; currently, oauth2, basic and bearer are supported.	String
authorization.oauth2.server.host	The OAUTH2 host server, as provided by the external service.	String
authorization.oauth2.server.authorization_endpoint	The (relative) authorization endpoint; this is usually documented by the external service provider.	String
authorization.oauth2.server.token_endpoint	The (relative) token endpoint; this is usually documented by the external service provider.	String
authorization.oauth2.server.scope	The (optional) access scope.	String
authorization.oauth2.client.id	The OAUTH2 client ID of the connector.	String
authorization.oauth2.client.secret	The OAUTH2 client secret of the connector.	String
authorization.oauth2.client.redirect_url	The URL OAUTH2 will redirect to; this needs to be set to the full URL of the Domo authorization endpoint (e.g., http://localhost:5500/authorize/oauth2).	String
authorization.basic.user_id_label	The display label of the user ID.	String	User ID
authorization.basic.user_id_optional	Whether the user ID is optional.	Boolean	false
authorization.basic.user_password_label	The display label of the user password.	String	Password
authorization.basic.user_password_optional	Whether the user password is optional.	Boolean	false
authorization.basic.help_link	An external help link shown in the credentials dialog.	String
authorization.bearer.bearer_label	The display label of the bearer token.	String	Bearer token
authorization.bearer.help_link	An external help link shown in the bearer token dialog.	String

Connectors | Transmissions

Setting	Description	Type	Default value
transmission.max_attempts	The maximum number of transmission operation (up-/downloads) attempts.	Number	3
transmission.attempts_delay	The delay (in seconds) between transmission operation (up-/downloads) attempts.	Number	3.0

Frontend settings

Mandatory settings

• network.client.server_address
• integration.<host_id>.host.url
• authorization.<host_id>.oauth2.client.id (1)
• authorization.<host_id>.oauth2.client.redirect_url (1)

(1) If the host uses OAUTH2 authorization.

General

Setting	Description	Type	Default value
general.support_email	The support email address.	String	sciebo.rds@uni-muenster.de
general.verbose_notifications	Whether to display more verbose notifications (good for debugging).	Boolean	false
general.notification_timeout	The timeout for overlay notifications in seconds.	Number	3.0

Theming

Setting	Description	Type	Default value
theme.primary_color	The primary theme color.	String	#29833B
theme.light.surface_color	The surface color when in light mode.	String	Slate
theme.dark.surface_color	The surface color when in dark mode.	String	White

Networking

Setting	Description	Type	Default value
network.regular_command_timeout	The maximum time (in seconds) for a command-reply to arrive.	Number	90.0
network.client.server_address	The address of the server the client should automatically connect to.	String
network.client.connection_timeout	The maximum time (in seconds) for connection attempts.	Number	90.0

Integration

Setting	Description	Type	Default value
<host_id>.integration.scheme	The authorization scheme to use; can be oauth2 or basic.	String	basic
<host_id>.integration.host.url	The full URL of the host.	String
<host_id>.integration.host.endpoints.entrypoint	The relative entrypoint of the host integration application.	String	/
<host_id>.integration.host.endpoints.api	The relative path of the host integration API.	String	/api/v1

Authorization

In order to be properly integrated into its host system, the frontend will authorize against it using OAUTH2. This means that you usually will need to generate a new OAUTH2 client ID and secret for the frontend in your host system.

Setting	Description	Type	Default value
<host_id>.authorization.oauth2.client.id	The OAUTH2 client ID of the frontend.	String
<host_id>.authorization.oauth2.client.redirect_url	The URL OAUTH2 will redirect to; this needs to be set to the full URL of the Domo authorization endpoint (e.g., http://localhost:5500/authorize/oauth2).	String