Configuration

To configure io.Bridge, you can use environment variables or pass the configuration settings as command line arguments depending on your deployment approach. Environment variables can be set by using a .env file or manually via the OS command line tool.

⚠️ Note that, for security reasons, it's not recommended to pass the license key or any credentials as command line arguments when directly executing the @interopio/bridge package via npx. It's best to pass these values to io.Bridge by using the respective environment variables.

⚠️ Note that, currently, the logging mechanism of io.Bridge can be configured only via environment variables.

The following sections describe the available environment variables for configuring io.Bridge.

The following example demonstrates providing the license key by setting the IO_BRIDGE_LICENSE_KEY environment variable in your .env file:

IO_BRIDGE_LICENSE_KEY=<my-license-key>

The following example demonstrates providing the license key by setting the IO_BRIDGE_LICENSE_KEY environment variable via the command prompt on Windows:

set IO_BRIDGE_LICENSE_KEY=<my-license-key>

The following example demonstrates providing the license key by setting the IO_BRIDGE_LICENSE_KEY environment variable on macOS and Linux:

export IO_BRIDGE_LICENSE_KEY=<my-license-key>

General

Use the following environment variables to provide the license key for io.Bridge and configure the host and the port for the io.Bridge server.

⚠️ Note that for io.Bridge to be able to operate, you must provide either the IO_BRIDGE_LICENSE_KEY or the IO_BRIDGE_LICENSE_KEY_FILE environment variable.

Environment Variable	Description
IO_BRIDGE_LICENSE_KEY	License key for io.Bridge. Alternatively, you can use the IO_BRIDGE_LICENSE_KEY_FILE environment variable.
IO_BRIDGE_LICENSE_KEY_FILE	Path to a file containing a license key for io.Bridge. Alternatively, you can use the IO_BRIDGE_LICENSE_KEY environment variable.
IO_BRIDGE_SERVER_HOST	Host on which to bind the io.Bridge server. Defaults to 0.0.0.0, i.e. any local IP address.
IO_BRIDGE_SERVER_PORT	Port on which to bind the io.Bridge server. Defaults to 8383.

The following example demonstrates providing a license key for io.Bridge and setting the host and the port for the io.Bridge server:

# In your `.env` file.
IO_BRIDGE_LICENSE_KEY=<my-license-key>
IO_BRIDGE_SERVER_HOST=127.0.0.1
IO_BRIDGE_SERVER_PORT=4242

Embedded io.Connect Gateway

Use the following environment variables to configure the embedded io.Connect Gateway that comes with io.Bridge.

Environment Variable	Description
IO_BRIDGE_GATEWAY_ENABLED	If true, the embedded io.Connect Gateway will be enabled. Defaults to false.

The following example demonstrates enabling the embedded io.Connect Gateway:

# In your `.env` file.
IO_BRIDGE_GATEWAY_ENABLED=true

CORS

Use the following environment variables to provide settings for CORS requests processed by the io.Bridge server.

Environment Variable	Description
IO_BRIDGE_SERVER_CORS_ALLOW_CREDENTIALS	If true, credentials in CORS requests will be allowed (e.g., you can use this if you want to connect io.Connect Browser to io.Bridge and your authentication mechanism is cookie-based). Defaults to false. Can't be set to true if the IO_BRIDGE_SERVER_CORS_ALLOW_ORIGINS environment variable is set to *.
IO_BRIDGE_SERVER_CORS_ALLOW_HEADERS	Comma-separated list of HTTP request headers to allow for CORS requests. Providing * as a value will allow all headers. Defaults to *.
IO_BRIDGE_SERVER_CORS_ALLOW_METHODS	Comma-separated list of HTTP request methods to allow for CORS requests. Providing * as a value will allow all methods. Defaults to GET,POST.
IO_BRIDGE_SERVER_CORS_ALLOW_ORIGINS	Comma-separated list of origins from which to allow CORS requests. You can use regular expressions (e.g., /http:\/\/localhost(:d+)?/ will match all http://localhost and http://localhost:[port] origins; /file:\/\/.*/ will match all file URLs). Providing null as a value will enable support for the specific null origin set by the client (e.g., like about:blank in a web browser). Providing * as a value will allow all origins. It's highly recommended to set this to the specific domain(s) used by your organization. Defaults to *.
IO_BRIDGE_SERVER_CORS_ALLOW_PRIVATE_NETWORK	If true, private network access (PNA) will be allowed for CORS requests. Defaults to false. Can't be set to true if the IO_BRIDGE_SERVER_CORS_ALLOW_ORIGINS environment variable is set to *.
IO_BRIDGE_SERVER_CORS_EXPOSE_HEADERS	Comma-separated list of HTTP response headers to allow for responses to CORS requests.
IO_BRIDGE_SERVER_CORS_MAX_AGE	Interval in seconds that clients will be allowed to cache the responses for CORS preflight requests. Defaults to 3600.

The following example demonstrates enabling CORS requests for origins from a specific domain (e.g., the domain which hosts your io.Connect Browser project) and allowing cookie-based credentials:

# In your `.env` file.
IO_BRIDGE_SERVER_CORS_ALLOW_ORIGINS=/https:\/\/(.*)\.my-browser-platform\.com/
IO_BRIDGE_SERVER_CORS_ALLOW_CREDENTIALS=true

Logging

⚠️ Note that, currently, the logging mechanism of io.Bridge can be configured only via environment variables.

Use the following environment variables to provide settings for the logging mechanism of io.Bridge.

Environment Variable	Description
LOGGING_LAYOUT	Layout to use for the log entries. io.Birdge supports the Logstash and Elastic Common Schema layout formats. Accepts ecs or logstash as values. Defaults to ecs.
LOGGING_LEVEL	Global logging level to use. Supported levels are trace, debug, info, warn, and error. Defaults to info.
LOGGING_LEVEL_GATEWAY_SERVER	Logging level to use for the io.Bridge server. Supported levels are trace, debug, info, warn, and error. Set to debug to troubleshoot any problems with the connection to io.Bridge (e.g., problems with CORS requests).

The following example demonstrates setting the global logging level and the log entry format:

# In your `.env` file.
LOGGING_LEVEL=warn
LOGGING_LAYOUT=logstash

The following sections describe the command line arguments you can use to configure io.Bridge when directly executing the @interopio/bridge package via npx.

The following example demonstrates setting the host and the port for the io.Bridge server:

npx @interopio/bridge --server.host=127.0.0.1 --server.port=4242

⚠️ Note that, for security reasons, it's not recommended to pass the license key or any credentials as command line arguments when directly executing the @interopio/bridge package via npx. It's best to pass these values to io.Bridge by using the respective environment variables.

General

Use the following command line arguments to configure the host and the port for the io.Bridge server.

Command Line Argument	Description
server.host	Host on which to bind the io.Bridge server. Defaults to 0.0.0.0, i.e. any local IP address.
server.port	Port on which to bind the io.Bridge server. Defaults to 8383.

The following example demonstrates setting the host and the port for the io.Bridge server:

npx @interopio/bridge --server.host=127.0.0.1 --server.port=4242

Embedded io.Connect Gateway

Use the following command line arguments to configure the embedded io.Connect Gateway that comes with io.Bridge.

Command Line Argument	Description
gateway.enabled	If true, the embedded io.Connect Gateway will be enabled. Defaults to false.

The following example demonstrates enabling the embedded io.Connect Gateway:

npx @interopio/bridge --gateway.enabled=true

CORS

Use the following command line arguments to provide settings for CORS requests processed by the io.Bridge server.

Command Line Argument	Description
server.cors.allow.credentials	If true, credentials in CORS requests will be allowed (e.g., you can use this if you want to connect io.Connect Browser to io.Bridge and your authentication mechanism is cookie-based). Defaults to false. Can't be set to true if the server.cors.allow.origins command line argument is set to *.
server.cors.allow.headers	Comma-separated list of HTTP request headers to allow for CORS requests. Providing * as a value will allow all headers. Defaults to *.
server.cors.allow.methods	Comma-separated list of HTTP request methods to allow for CORS requests. Providing * as a value will allow all methods. Defaults to GET,POST.
server.cors.allow.origins	Comma-separated list of origins from which to allow CORS requests. You can use regular expressions (e.g., /http:\/\/localhost(:d+)?/ will match all http://localhost and http://localhost:[port] origins; /file:\/\/.*/ will match all file URLs). Providing null as a value will enable support for the specific null origin set by the client (e.g., like about:blank in a web browser). Providing * as a value will allow all origins. It's highly recommended to set this to the specific domain(s) used by your organization. Defaults to *.
server.cors.allow.private.network	If true, private network access (PNA) will be allowed for CORS requests. Defaults to false. Can't be set to true if the server.cors.allow.origins command line argument is set to *.
server.cors.expose.headers	Comma-separated list of HTTP response headers to allow for responses to CORS requests.
server.cors.max.age	Interval in seconds that clients will be allowed to cache the responses for CORS preflight requests. Defaults to 3600.

The following example demonstrates enabling CORS requests for origins from a specific domain (e.g., the domain which hosts your io.Connect Browser project) and allowing cookie-based credentials:

npx @interopio/bridge --server.cors.allow.origins=/https:\/\/(.*)\.my-browser-platform\.com/ --server.cors.allow.credentials=true