# Overview Source: https://docs.interop.io/desktop/developers/configuration/overview/index.html ## Overview **io.Connect Desktop** is highly configurable. You can apply custom system-wide, as well as app-specific settings. Among the configurable features are system settings, app settings, io.Connect Windows, logging and more. ### Schemas The following JSON schemas describe the available options for configuring **io.Connect Desktop**: - The [system configuration schema](https://docs.interop.io/desktop/assets/configuration/system.json) describes all global platform settings. - The [io.Connect Gateway configuration schema](https://docs.interop.io/desktop/assets/configuration/gw.json) describes the `"gw"` key in the `system.json` file which contains configuration for the io.Connect Gateway [port](https://docs.interop.io/desktop/developers/configuration/system/index.md#ioconnect_gateway-dynamic_port) and more, [security](https://docs.interop.io/desktop/getting-started/security/index.md#ioconnect_gateway), and more. - The [**io.Insights** configuration schema](https://docs.interop.io/desktop/assets/configuration/otel.json) describes the available settings for configuring the available [**io.Insights**](https://docs.interop.io/insights/general-overview/index.md) features - metrics, traces, and logs. - The [app definition schema](https://docs.interop.io/desktop/assets/configuration/application.json) describes the available settings for defining interop-enabled apps. #### 9.0 Version Stream If you are still using the **io.Connect Desktop** 9.0 version stream, use the following schemas relevant to the 9.0 version stream: - The [system configuration schema](https://docs.interop.io/desktop/assets/configuration/9-0/system.json) describes all global platform settings. - The [io.Connect Gateway configuration schema](https://docs.interop.io/desktop/assets/configuration/9-0/gw.json) describes the `"gw"` key in the `system.json` file which contains configuration for the io.Connect Gateway [port](https://docs.interop.io/desktop/developers/configuration/system/index.md#ioconnect_gateway-dynamic_port) and more, [security](https://docs.interop.io/desktop/getting-started/security/index.md#ioconnect_gateway), and more. - The [app definition schema](https://docs.interop.io/desktop/assets/configuration/9-0/application.json) describes the available settings for defining interop-enabled apps. - The [io.Connect Windows configuration schema](https://docs.interop.io/desktop/assets/configuration/9-0/stickywindows.json) describes the available settings for configuring the global behavior of io.Connect Windows. - The [themes configuration schema](https://docs.interop.io/desktop/assets/configuration/9-0/themes.json) describes the available settings for configuring the io.Connect themes when using [classic groups](https://docs.interop.io/desktop/capabilities/windows/window-management/overview/index.md#window_groups-classic_groups). > ⚠️ *Note that a JSON schema for the `gilding.json` [configuration file](https://docs.interop.io/desktop/developers/configuration/system/index.md#gilding_configuration) isn't available.* ## Location ### System Configuration Files The `system.json` file containing system-wide settings for **io.Connect Desktop** is located in the `/config` folder. #### 9.0 Version Stream If you are still using the **io.Connect Desktop** 9.0 version stream, you can find all configuration files for **io.Connect Desktop** in the `/interop.io/io.Connect Desktop/Desktop/config` folder. There you can find the `system.json` file for system-wide settings, the `stickywindows.json` file for configuring the default behavior of [io.Connect Windows](https://docs.interop.io/desktop/capabilities/windows/window-management/overview/index.md), the `themes.json` file for configuring the **io.Connect Desktop** [Themes](https://docs.interop.io/desktop/capabilities/windows/themes/index.md), the `channels.json` file for configuring the io.Connect [Channels](https://docs.interop.io/desktop/capabilities/data-sharing/channels/overview/index.md), and the `logger.json` file for configuring the [logging](https://docs.interop.io/desktop/developers/configuration/system/index.md#logging) for **io.Connect Desktop**. ### App Definition Files The definitions of the **io.Connect Desktop** system and demo apps are located in the `/config/apps` folder. You can add your own app definition files in the `%LocalAppData%/interop.io/io.Connect Desktop/UserData/-/apps` folder on Windows and in the `~Library/Application Support/interop.io/io.Connect Desktop/UserData/-/apps` folder on macOS where `-` represents the environment and region of **io.Connect Desktop** (e.g., `DEMO-INTEROP.IO`). The `/UserData` [folder](https://docs.interop.io/desktop/developers/configuration/system/index.md#folders) is preserved between installations allowing you to keep your custom files in case you decide to upgrade or reinstall **io.Connect Desktop**. > ⚠️ *Note that the app definitions are monitored dynamically, which means that it isn't necessary to restart **io.Connect Desktop** when you modify an app definition. You can also define custom locations for the [app definition stores](https://docs.interop.io/desktop/developers/configuration/system/index.md#app_stores) and the `/UserData` [folder](https://docs.interop.io/desktop/developers/configuration/system/index.md#folders) via the `system.json` file.* #### 9.0 Version Stream If you are still using the **io.Connect Desktop** 9.0 version stream, you can find the definitions of the **io.Connect Desktop** system and demo apps in the `/interop.io/io.Connect Desktop/Desktop/config/apps` folder. ## Environment Variables **io.Connect Desktop** registers a set of environment variables which you can use in all properties of all configuration files that require a URL or a file path as a value. > ⚠️ *Note that when specifying URLs or file paths in the **io.Connect Desktop** configuration files, you can use both io.Connect environment variables and OS environment variables (such as `%LocalAppData%` on Windows).* > ℹ️ *For details on how to access environment variables programmatically from your interop-enabled apps, see the [Capabilities > More > APIs > Environment Variables](https://docs.interop.io/desktop/capabilities/more/apis/index.md#environment_variables) section.* ### Platform Variables The following table lists the environment variables registered by **io.Connect Desktop**: | Environment Variable | Description | |----------------------|-------------| | `DesktopFolder` | Points to the desktop directory for the current user (e.g., `"C:\Users\\Desktop"`). | | `DownloadsFolder` | Points to the downloads directory for the current user (e.g., `"C:\Users\\Downloads"`). | | `HomeFolder` | Points to the profile directory for the current user (e.g., `"C:\Users\"`). | | `IO_CD_APP_DATA_DIR` | Points to `%LocalAppData%` on Windows and to `~/Library/Application Support` on macOS. *Available since **io.Connect Desktop** 10.0.* | | `IO_CD_ASSETS_DIR` | Points to the **io.Connect Desktop** `/assets` folder. *Available since **io.Connect Desktop** 10.0.* | | `IO_CD_CONFIG_DIR` | Points to the **io.Connect Desktop** `/config` folder. *Available since **io.Connect Desktop** 10.0.* | | `IO_CD_CRASH_DUMPS_DIR` | Points to the `%LocalAppData%/interop.io/io.Connect Desktop/UserData/-/crashes` folder on Windows and the `~Library/Application Support/interop.io/io.Connect Desktop/UserData/-/crashes` folder on macOS where `-` represents the environment and region of **io.Connect Desktop** (e.g., `DEMO-INTEROP.IO`). *Available since **io.Connect Desktop** 10.0.* | | `IO_CD_ENV` | The environment in which **io.Connect Desktop** is running (e.g., `"DEMO"`). *Available since **io.Connect Desktop** 10.0.* | | `IO_CD_LOGS_DIR` | Points to the `%LocalAppData%/interop.io/io.Connect Desktop/UserData/-/logs` folder on Windows and the `~Library/Application Support/interop.io/io.Connect Desktop/UserData/-/logs` folder on macOS where `-` represents the environment and region of **io.Connect Desktop** (e.g., `DEMO-INTEROP.IO`). *Available since **io.Connect Desktop** 10.0.* | | `IO_CD_REGION` | The region in which **io.Connect Desktop** is running (e.g., `"INTEROP.IO"`). *Available since **io.Connect Desktop** 10.0.* | | `IO_CD_ROOT_DIR` | Points to the root folder of **io.Connect Desktop** where the executable file is located. *Available since **io.Connect Desktop** 10.0.* | | `IO_CD_USER_DATA_DIR` | Points to the `%LocalAppData%/interop.io/io.Connect Desktop/UserData` folder on Windows and the `~Library/Application Support/interop.io/io.Connect Desktop/UserData` folder on macOS. *Available since **io.Connect Desktop** 10.0.* | To use any of the environment variables in the **io.Connect Desktop** configuration files, wrap it with `%` symbols. The following example demonstrates using environment variables to specify a location for storing user-specific data per environment and region via the `system.json` [system configuration](https://docs.interop.io/desktop/developers/configuration/system/index.md) file of **io.Connect Desktop**: ```json { "folders": { "userData": "%IO_CD_ROOT_DIR%/my-data/UserData/%IO_CD_ENV%-%IO_CD_REGION%" } } ``` Currently, the following legacy environment variables are also supported. It's highly recommended to migrate to the environment variables introduced in **io.Connect Desktop** 10.0 as the legacy environment variables may be removed in a future version: | Environment Variable | Description | |----------------------|-------------| | `GDDIR` | Set to the root directory where the **io.Connect Desktop** executable file is located (e.g., `"C:\Users\\AppData\Local\interop.io\io.Connect Desktop\Desktop"`). | | `GLUE-ENV` | Set to the [environment](https://docs.interop.io/desktop/developers/configuration/system/index.md#environments__regions) in which **io.Connect Desktop** is running (e.g., `"DEMO"`). | | `GLUE-REGION` | Set to the region in which **io.Connect Desktop** is running (e.g., `"INTEROP.IO"`). | | `GLUE-USER-DATA` | Set to the location of the `/UserData` [folder](https://docs.interop.io/desktop/developers/configuration/system/index.md#folders) of **io.Connect Desktop** (e.g., `"C:\Users\\AppData\Local\interop.io\io.Connect Desktop\UserData\DEMO-INTEROP.IO"`). | Available since io.Connect Desktop 9.7.1 For testing and PoC purposes, you can set the `IO_CD_BASIC_AUTH_USERNAME` and `IO_CD_BASIC_AUTH_PASSWORD` environment variables with default username and password to be used for authentication. If these variables are set, **io.Connect Desktop** will extract their values and pass them to the [login screen](https://docs.interop.io/desktop/getting-started/how-to/rebrand-io-connect/functionality/index.md) displayed by the SSO app and to all interop-enabled apps that require basic authentication. The username and password fields will be prepopulated with the extracted values and the user will be automatically authenticated. The following example demonstrates setting the `IO_CD_BASIC_AUTH_USERNAME` and `IO_CD_BASIC_AUTH_PASSWORD` environment variables for the io.Connect platform process: ```cmd set "IO_CD_BASIC_AUTH_USERNAME=my-username" && set "IO_CD_BASIC_AUTH_PASSWORD=my-password" && io-connect-desktop.exe ``` ### Custom Variables Available since io.Connect Desktop 10.0.3 **io.Connect Desktop** allows you to define your own custom environment variables that will be registered by the platform on startup. These variables can be used throughout all other configuration files (e.g., in the [system configuration](https://docs.interop.io/desktop/developers/configuration/system/index.md) or in [app definitions](https://docs.interop.io/desktop/developers/configuration/application/index.md)). To define a custom environment variable, use the `"set"` property of the `"envVars"` top-level key in the `system.json` file. It accepts an object with key/value pairs holding the names and the values of the environment variables to register. Environment variables can also be defined in [multiple local and remote configuration sources](https://docs.interop.io/desktop/developers/configuration/system/index.md#multiple_local__remote_configuration_sources). The variables specified in the configuration source with the highest priority will override the values of the variables with the same names in all other lower priority configuration files. The following example demonstrates registering environment variables that hold different app URLs for the different [environments and regions](https://docs.interop.io/desktop/developers/configuration/system/index.md#environments__regions) in which the app will run: ```json { "envVars": { "set": { "MY_APP_PROD": "https://my-app.com", "MY_APP_DEV": "https://dev.my-app.com" } } } ``` Using the custom environment variables in an app definition: ```json { "name": "my-app", "title": "My App", "icon": "%MY_APP_PROD%/icon.ico", "type": "window", "details": { "url": "%MY_APP_DEV%/index.html" } } ``` To clear the value of an environment variable, set it to an empty string: ```json // In system configuration file with higher priority. { "envVars": { "set": { // This will override the value of an existing environment variable with the same name in a lower priority configuration file, // or will set a new environment variable with an empty string as a value. "MY_EMPTY_VAR": "" } } } ``` #### 9.0 Version Stream If you are still using the **io.Connect Desktop** 9.0 version stream, the `gilding.json` [configuration file](https://docs.interop.io/desktop/developers/configuration/system/index.md#gilding_configuration) of **io.Connect Desktop** allows you to define your own custom environment variables that will be registered by the platform on startup. These variables can be used throughout all other configuration files (e.g., in the [system configuration](https://docs.interop.io/desktop/developers/configuration/system/index.md) or in [app definitions](https://docs.interop.io/desktop/developers/configuration/application/index.md)). To define a custom environment variable, use the `"set"` property of the `"envVars"` top-level key in the `gilding.json` file. It accepts an object with key/value pairs holding the names and the values of the environment variables to register. The following example demonstrates registering environment variables that hold different app URLs for the different [environments and regions](https://docs.interop.io/desktop/developers/configuration/system/index.md#environments__regions) in which the app will run: ```json { "envVars": { "set": { "MY_APP_PROD": "https://my-app.com", "MY_APP_DEV": "https://dev.my-app.com" } } } ``` Using the custom environment variables in an app definition: ```json { "name": "my-app", "title": "My App", "icon": "%MY_APP_PROD%/icon.ico", "type": "window", "details": { "url": "%MY_APP_DEV%/index.html" } } ```