🛠️ Configuration

🛠️ Configuration

🌐 Overview

The application relies on a configuration file to properly initialize and connect all required components. This file defines essential runtime parameters such as service endpoints, authentication details, and integration settings. By externalizing these values, the system remains flexible and can be easily adapted to different environments (e.g., development, staging, production) without changing the application code.

The location of the configuration file must be provided via the environment variable:

RUNTIME_CONFIGURATION_FILE

If this variable is not set, the runtime cannot start correctly.

📑 Configuration Structure

The configuration file is written in JSON format (often stored as .json or .yml) and contains all necessary parameters for connecting the runtime with external services. It is organized into distinct sections, each responsible for a specific system component:

General Setting: Defines the core runtime parameters, such as the AAS identifier and polling interval, required for the application to operate.
Asset Connector settings: These are the connection settings for the Asset Connector micro service's REST API, which handles the connection to an MQTT or OPC UA broker.
AAS Server settings: These are the connection settings for the AAS Server, including authentication, proxy, TLS/SSL verification and timeouts.
InfluxDB Settings (optional): Database connection details for storing time-series data, e.g. host, port, credentials and database name..

A minimal configuration must define at least the AasId, the AssetConnector.BaseUrl and the AasServer.BaseUrl. All other parameters are optional and fall back to reasonable defaults.

Passwords and secrets should be provided via environment variables, not in the configuration file. See the Additional Passwords section for details.

Example Structure for AAS Server with oAuth2 authentication and InfluxDB version 1 integration:

{                                                                   # General Setting
    "AasId": "https://fluid40.de/ids/shell/8547_5433_6140_7422",
    "PollingInterval": 5,
    "AssetConnector": {                                             # Asset Connector Settings
        "BaseUrl": "http://mqtt_connector:8000",
        "TimeOut": 200,
        "ConnectionTimeOut": 100,
        "TrustEnv": true,
    },
    "AasServer": {                                                  # AAS Server Settings
        "BaseUrl": "http://javaserver:8077/",
        "ConnectionTimeOut": 100,
        "SslVerify": true,
        "TrustEnv": true,
        "AuthenticationSettings": {                                 # AAS Server Authentication Settings
            "OAuth": {
            "ClientId": "my-client-id",
            "TokenUrl": "https://auth-server.example.com/oauth/token",
            "GrantType": "client_credentials"
        }
    },
    "InfluxDbVersion": "1",                                         # InfluxDB Version Setting
    "InfluxDb": {                                                   # InfluxDB Settings
        "Host": "influx_database",
        "Port": 8086,
        "Username": "fluid40",
        "Database": "submodel-db",
        "TrustEnv": true,
    }
}

⚙️ General Settings

Required

The General Settings section defines the core parameters required for the runtime to operate. These include the unique identifier for the Asset Administration Shell (AAS) and the polling interval for retrieving values from the broker. Proper configuration of these fields ensures the runtime can identify itself and function at the desired update frequency.

Field	Description	Required	Default
AasId	Unique identifier of the Asset Administration Shell (AAS).	✅ Yes	–
PollingInterval	Interval (in seconds) for retrieving values from the broker.	❌ No	`5`

Example:

"AasId": "https://fluid40.de/ids/shell/8547_5433_6140_7422",
"PollingInterval": 5

🔗 Asset Connector Settings

Required

The Asset Connector Settings section defines how the runtime communicates with the REST API of the Asset Connector micro service. These parameters specify the API endpoint, timeouts, and proxy handling, ensuring reliable and configurable integration with external asset data sources.

Field	Description	Required	Default
AssetConnector.BaseUrl	Base URL of the Asset Connector REST API.	✅ Yes	–
AssetConnector.TimeOut	API call timeout in seconds.	❌ No	`200`
AssetConnector.ConnectionTimeOut	Connection establishment timeout in seconds.	❌ No	`100`
AssetConnector.TrustEnv	Disable proxy usage from environment.	❌ No	`true`

Example:

"AssetConnector": {
    "BaseUrl": "http://mqtt_connector:8000",
    "TimeOut": 200,
    "ConnectionTimeOut": 100,
    "TrustEnv": true,
}

🖥️ AAS Server Settings

Required

The AAS Server Settings section defines how the runtime connects to and interacts with the Asset Administration Shell (AAS) server. These parameters include the server endpoint, timeouts, proxy settings, and SSL verification, ensuring secure and reliable communication with the AAS server for all core operations.

References: For the connection to the AAS Server the aas-http-client package is used. For detailed information about the AAS Server configuration, see the aas-http-client documentation.

Field	Description	Required	Default
AasServer.BaseUrl	Base URL of the AAS server.	✅ Yes	–
AasServer.HttpsProxy	HTTPS proxy.	❌ No	`null`
AasServer.HttpProxy	HTTP proxy.	❌ No	`null`
AasServer.TimeOut	API call timeout in seconds.	❌ No	`200`
AasServer.ConnectionTimeOut	Connection establishment timeout in seconds.	❌ No	`100`
AasServer.SslVerify	Verify TLS/SSL certificates.	❌ No	`true`
AasServer.TrustEnv	Disable proxy usage from environment.	❌ No	`true`

Example (with Basic Authentication): Example:

"AasServer": {
    "BaseUrl": "http://javaserver:8077/",
    "HttpsProxy": "",
    "HttpProxy": "",
    "TimeOut": 200,
    "ConnectionTimeOut": 100,
    "SslVerify": true,
    "TrustEnv": true,
    "AuthenticationSettings": {
        "BasicAuth": {
            "Username": "admin"
        }
    }
}

🛡️ AAS Server Authentication Settings

Optional

The runtime supports multiple authentication methods for connecting to the AAS Server, allowing secure integration in a variety of environments. Authentication credentials should be provided using environment variables whenever possible to avoid storing sensitive information in configuration files.

Supported Authentication Methods:

Basic Authentication
- Set the username in the configuration under AasServer.AuthenticationSettings.BasicAuth.Username.
- Provide the password via the RUNTIME_BASIC_AUTH_PW environment variable.
OAuth2 Client Credentials
- Set the client ID, token URL, and grant type in the configuration under AasServer.AuthenticationSettings.OAuth.
- Provide the client secret via the RUNTIME_OAUTH_SECRET environment variable.
Bearer Token Authentication
- No username is required in the configuration.
- Provide the token via the RUNTIME_BEARER_TOKEN environment variable.

If Bearer Token or no authentication is used, the AuthenticationSettings node can be omitted.

Passwords and secrets should be provided via environment variables, not in the configuration file. See the Additional Passwords section for details.

🔒 Basic Authentication Settings

Field	Description	Required	Default
AasServer.AuthenticationSettings.BasicAuth.Username	Username for HTTP Basic Authentication.	✅ Yes	-

Provide the password via the RUNTIME_BASIC_AUTH_PW environment variable.

Example:

"AuthenticationSettings": {
    "BasicAuth": {
        "Username": "admin"
    }
}

🗝️ oAuth2 Settings

Field	Description	Required	Default
AasServer.AuthenticationSettings.OAuth.ClientId	OAuth2 client identifier.	✅ Yes	-
AasServer.AuthenticationSettings.OAuth.TokenUrl	OAuth2 token endpoint URL.	✅ Yes	-
AasServer.AuthenticationSettings.OAuth.GrantType	OAuth2 grant type (`client_credentials` or `password`).	❌ No	`"client_credentials"`

Provide the client secret via the RUNTIME_OAUTH_SECRET environment variable.

Example:

"AuthenticationSettings": {
    "OAuth": {
        "ClientId": "my-client-id",
        "TokenUrl": "https://auth-server.example.com/oauth/token",
        "GrantType": "client_credentials"
    }
}

🪪 Bearer Token Settings

Provide the token via the RUNTIME_BEARER_TOKEN environment variable. The AuthenticationSettings node can be omitted.

📊 InfluxDB Settings

Optional

The InfluxDB integration enables the runtime to store time-series data for later analysis and visualization. This database connection is optional. If the InfluxDb section is omitted from your configuration file, the runtime will operate normally but will not persist any data to a database.

Behavior:

If the InfluxDb node is not set in the configuration file, no data will be written to a database. InfluxDbVersion
If the InfluxDb node is present but the specified database cannot be found or accessed, the runtime will continue operating, but data will not be written to the database. No critical errors will be raised, ensuring robust operation even if the database is temporarily unavailable.

InfluxDB version 1 and version 2 is supported. Set 'InfluxDbVersion' to:

1 for InfluxDB version 1
2 for InfluxDB version 2

📊1️⃣ InfluxDB version 1 Settings

Field	Description	Required	Default
InfluxDbVersion	Set the version of the Influx DB	✅ Yes	-
InfluxDb.Host	Hostname or IP address of the InfluxDB server.	✅ Yes	–
InfluxDb.Port	Port number of the InfluxDB server.	✅ Yes	–
InfluxDb.Username	Username for the InfluxDB server.	❌ No	`""`
InfluxDb.Database	Database name to use in InfluxDB.	❌ No	`""`
InfluxDb.ConnectionTimeOut	Connection establishment timeout in seconds.	❌ No	`100`
InfluxDb.TrustEnv	Disable proxy usage from environment.	❌ No	`true`

The property 'InfluxDbVersion' must be set to the value 1. Provide the database password via the RUNTIME_INFLUX_PW environment variable.

Example:

"InfluxDbVersion": "1",
"InfluxDb": {
    "Host": "influx_database_v1-rt",
    "Port": 8086,
    "Username": "fluid40",
    "Database": "submodel-db",
    "ConnectionTimeOut": 60,
    "TrustEnv": false
}

📊2️⃣ InfluxDB version 2 Settings

Field	Description	Required	Default
InfluxDbVersion	Set the version of the Influx DB	✅ Yes	-
InfluxDb.Url	URL of the InfluxDB server.	✅ Yes	–
InfluxDb.Organization	Organization name to use in InfluxDB.	✅ Yes	–
InfluxDb.Bucket	Bucket name to use in InfluxDB.	✅ Yes	-
InfluxDb.ConnectionTimeOut	Connection establishment timeout in seconds.	❌ No	`100`

The property 'InfluxDbVersion' must be set to the value 2. Provide the database token via the RUNTIME_INFLUX_PW environment variable.

Example:

"InfluxDbVersion": "2",
"InfluxDb": {
    "Url": "http://influx_database_v2-rt:8086/",
    "Organization": "fluid40-org",
    "Bucket": "submodel-db",
    "ConnectionTimeOut": 60
}

🔑 Additional Passwords

Some components may require authentication. Instead of storing sensitive information in the configuration file, passwords must be provided via environment variables:

Component	Environment Variable	Description
AAS Server	`RUNTIME_BASIC_AUTH_PW`	Password used to authenticate with the AAS Server by basic auth
AAS Server	`RUNTIME_OAUTH_SECRET`	Secret used to authenticate with the AAS Server by oAuth
AAS Server	`RUNTIME_BEARER_TOKEN`	Bearer Token used to authenticate with the AAS Server by Token
InfluxDB	`RUNTIME_INFLUX_PW`	Password (v1) or token (v2) used to authenticate with the InfluxDB

This approach keeps credentials secure and ensures they can be easily managed across different environments (development, staging, production).

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

🛠️ Configuration

🌐 Overview

📑 Configuration Structure

⚙️ General Settings

🔗 Asset Connector Settings

🖥️ AAS Server Settings

🛡️ AAS Server Authentication Settings

🔒 Basic Authentication Settings

🗝️ oAuth2 Settings

🪪 Bearer Token Settings

📊 InfluxDB Settings

📊1️⃣ InfluxDB version 1 Settings

📊2️⃣ InfluxDB version 2 Settings

🔑 Additional Passwords

Uh oh!

FilesExpand file tree

configuration.md

Latest commit

History

configuration.md

File metadata and controls

🛠️ Configuration

🌐 Overview

📑 Configuration Structure

⚙️ General Settings

🔗 Asset Connector Settings

🖥️ AAS Server Settings

🛡️ AAS Server Authentication Settings

🔒 Basic Authentication Settings

🗝️ oAuth2 Settings

🪪 Bearer Token Settings

📊 InfluxDB Settings

📊1️⃣ InfluxDB version 1 Settings

📊2️⃣ InfluxDB version 2 Settings

🔑 Additional Passwords