|
| 1 | +# Configuration |
| 2 | + |
| 3 | +Configuration in FA³ST Service happens primamirly via a single JSON file. |
| 4 | +However, it is also possible to override configuration properties through command-line arguments and environment variables, where command-line arguments have precedence over environment variables while both override properties defined in the configuration file. |
| 5 | + |
| 6 | +The configuration file contains a `core` section as well as multiple sections telling FA³ST Service which implementations to use for the available interfaces and how to configure them. |
| 7 | + |
| 8 | +```{code-block} json |
| 9 | +:caption: Structure of the configuration file. |
| 10 | +:lineno-start: 1 |
| 11 | +{ |
| 12 | + "core" : { }, // core configuration not related to interfaces |
| 13 | + "endpoints" : [ ], // [0..*] default: HTTP |
| 14 | + "persistence" : { }, // [0..1] default: in-memory |
| 15 | + "fileStorage" : {}, // [0..1] default: in-memory |
| 16 | + "messageBus" : { }, // [0..1] default: internal |
| 17 | + "assetConnections": [ ] // [0..*] default: none |
| 18 | +} |
| 19 | +``` |
| 20 | + |
| 21 | +A configuration base is always based on the default configuration, meaning that it only needs to contain properties that differ from the default configuration. |
| 22 | +For example, providing only the `core` section is a valid configuration and will contain default values for all other sections. |
| 23 | +This is a common scenario if you want to quickly setup FA³ST Service for your first experiments. |
| 24 | + |
| 25 | +```{code-block} json |
| 26 | +:caption: Configuration file with only `core` section. All other sections will use default values. |
| 27 | +:lineno-start: 1 |
| 28 | +{ |
| 29 | + "core" : { |
| 30 | + // custom core settings |
| 31 | + } |
| 32 | +} |
| 33 | +``` |
| 34 | + |
| 35 | +## Core Configuration |
| 36 | + |
| 37 | +The `core` configuration block contains properties not related to the implementation of any interface. |
| 38 | + |
| 39 | +:::{table} Configuration properties of `core` configuration section. |
| 40 | +| Name | Allowed Values | Description | Default Value | |
| 41 | +| -------------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | |
| 42 | +| aasRegistries<br>*(optional)* | List<String> | URLs of AAS registries to use (base URL, i.e. without /api/{version}). If not set, no synchronization of AASs with registry happens. | *empty* | |
| 43 | +| assetConnectionRetryInterval<br>*(optional)* | Long | Interval in ms in which to retry establishing asset connections | 1000 | |
| 44 | +| requestHandlerThreadPoolSize<br>*(optional)* | Integer | Number of concurrent thread that can execute API requests | 2 | |
| 45 | +| submodelRegistries<br>*(optional)* | List<String> | URLs of submodels registries to use (base URL, i.e. without /api/{version}). If not set, no synchronization of submodels with registry happens. | *empty* | |
| 46 | +| validationOnLoad<br>*(optional)* | Object | Validation rules to use when loading the AAS model at startup | all enabled | |
| 47 | +| validationOnCreate<br>*(optional)* | Object | Validation rules to use when creating new elements via API | constraints validation disabled | |
| 48 | +| validationOnUpdate<br>*(optional)* | Object | Validation rules to use when updating elements via API | constraints validation disabled | |
| 49 | +::: |
| 50 | + |
| 51 | +```{code-block} json |
| 52 | +:caption: Example `core` configuration |
| 53 | +:lineno-start: 1 |
| 54 | +{ |
| 55 | + "core" : { |
| 56 | + "aasRegistries": [ |
| 57 | + "http://example.com/MyAASRegistry" |
| 58 | + ], |
| 59 | + "assetConnectionRetryInterval": 1000, |
| 60 | + "requestHandlerThreadPoolSize": 2, |
| 61 | + "submodelRegistries": [ |
| 62 | + "http://example.com/MySubmodelRegistry" |
| 63 | + ], |
| 64 | + "validationOnLoad": { |
| 65 | + "validateConstraints": true, // currently ignored because AAS4J does not yet implement validation for AAS v3.0 |
| 66 | + "idShortUniqueness": true, |
| 67 | + "identifierUniqueness": true |
| 68 | + }, |
| 69 | + "validationOnCreate": { |
| 70 | + "validateConstraints": false, // currently ignored because AAS4J does not yet implement validation for AAS v3.0 |
| 71 | + "idShortUniqueness": true, |
| 72 | + "identifierUniqueness": true |
| 73 | + }, |
| 74 | + "validationOnUpdate": { |
| 75 | + "validateConstraints": false, // currently ignored because AAS4J does not yet implement validation for AAS v3.0 |
| 76 | + "idShortUniqueness": true, |
| 77 | + "identifierUniqueness": true |
| 78 | + } |
| 79 | + }, |
| 80 | + // ... |
| 81 | +} |
| 82 | +``` |
| 83 | + |
| 84 | +## Configuring Interface Implementations |
| 85 | + |
| 86 | +For each interface in the architecture, you can choose one (or sometimes multiple) interface(s) to be used. |
| 87 | +As every interface implementation may require different configuration properties which FA³ST does not know about (as the implementation may be developed by 3rd parties at any time), the configuration section for each interface implementation uses the following structure |
| 88 | + |
| 89 | +```{code-block} json |
| 90 | +:caption: Common structure for configuring an interface implementation. |
| 91 | +:lineno-start: 1 |
| 92 | +{ |
| 93 | + "@class" : "...", // fully-qualified Java class name of the class implementing the interface |
| 94 | + // implementation-specific configuration properties |
| 95 | +} |
| 96 | +``` |
| 97 | + |
| 98 | +Which properties are available for each implementation should be documented, e.g., for all default implementations these properties are documented in the corresponding page of the documentation for each of the implementations. |
| 99 | + |
| 100 | +The following shows an example of a configuration using and HTTP endpoint with port 443. |
| 101 | + |
| 102 | +```{code-block} json |
| 103 | +:caption: Example configuration with HTTP endpoint using port 443. |
| 104 | +:lineno-start: 1 |
| 105 | +{ |
| 106 | + "endpoints" : { |
| 107 | + "@class" : "org.eclipse.digitaltwin.fa3st.service.endpoint.http.HttpEndpoint", |
| 108 | + "port" : 443 |
| 109 | + }, |
| 110 | + // ... |
| 111 | +} |
| 112 | +``` |
| 113 | + |
| 114 | +## Using 3rd Party Interface Implementations |
| 115 | + |
| 116 | +For FA³ST to be able to load an implementation that is not pre-packaged with FA³ST, you need to put a JAR file containing the respective class in the same directory as the FA³ST Service JAR. |
| 117 | +Furthermore, all dependencies of that class need also be resolvable. |
| 118 | +This can be achieved by either packaging them into the same JAR (e.g. using the [Maven Shade Plugin](https://maven.apache.org/plugins/maven-shade-plugin/)) or manually providing the required JAR files alongside the implementation. |
| 119 | + |
| 120 | + |
| 121 | +(providing-certificates-in-configuration)= |
| 122 | +## Providing certificates in configuration |
| 123 | + |
| 124 | +Multiple components of FA³ST Service make use of certificates, either by using them for their own services or by trusting the provided certificates. |
| 125 | +The default way to exchange certificates in FA³ST Service is via [Java KeyStore](https://docs.oracle.com/javase/8/docs/api/java/security/KeyStore.html)s. |
| 126 | +To simplify configuration, the same configuration object is re-used across different components, for example in the [HTTP Endpoint](#endpoint-http). |
| 127 | +The structure of the certificate-related configuration object is explained in the following. |
| 128 | + |
| 129 | +:::{table} Configuration properties of generic certificate section. |
| 130 | +| Name | Allowed Values | Description | Default Value | |
| 131 | +| -----------------------------| -------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------- | |
| 132 | +| keyPassword | String | The password for the key.<br>**Warning: may cause unexpected behavior if not set or set to empty string in some cases** | | |
| 133 | +| keyStorePassword | String | The password for the key store | | |
| 134 | +| keyStorePath | String | File containing the key store | | |
| 135 | +| keyAlias<br>*(optional)* | String | The alias to use, e.g. when loading a certificate and the key store contains multiple entries | null, i.e. first entry will be used | |
| 136 | +| keyStoreType<br>*(optional)* | String | Type of the KeyStore, e.g. PKCS12 or JKS | PKCS12 | |
| 137 | +::: |
| 138 | + |
| 139 | +```{code-block} json |
| 140 | +:caption: Example certificate information |
| 141 | +:lineno-start: 1 |
| 142 | +{ |
| 143 | + "keyStoreType": "PKCS12", |
| 144 | + "keyStorePath": "C:\fa3st\MyKeyStore.p12", |
| 145 | + "keyStorePassword": "changeit", |
| 146 | + "keyAlias": "server-key", |
| 147 | + "keyPassword": "changeit" |
| 148 | +} |
| 149 | +``` |
| 150 | + |
| 151 | +## Overriding Config Properties |
| 152 | + |
| 153 | +As indicated by the last row in the above table, any config property can be overridden both via CLI or via environment variables. |
| 154 | + |
| 155 | +### Via CLI |
| 156 | + |
| 157 | +Via CLI this is done by using the JSONPath expression to the property within the config file but without the `$.` part JSONPath expression typically start with. |
| 158 | + |
| 159 | +For example, to override the `requestHandlerThreadPoolSize` property call FA³ST Service like this |
| 160 | + |
| 161 | +```sh |
| 162 | +> java -jar fa3st-service-starter-{version}.jar [any other CLI arguments] core.requestHandlerThreadPoolSize=42 |
| 163 | +``` |
| 164 | + |
| 165 | +To access configuration properties inside an array or list use array notation, e.g., `endpoints[0].port=8081` |
| 166 | + |
| 167 | + |
| 168 | +### Via Environment Variables |
| 169 | + |
| 170 | +Overriding configuration properties via environment variables is similar to overriding them via CLI with two differences |
| 171 | + |
| 172 | +1. Add the prefix *fa3st_config_extension_* |
| 173 | +2. Replace `.` that separate the JSONPath with `_` |
| 174 | + |
| 175 | +Applying the previous examples yields `fa3st_config_extension_core_requestHandlerThreadPoolSize=42` to update the property `requestHandlerThreadPoolSize` and `fa3st_config_extension_endpoints[0]_port=8081` to update the port of the HTTP endpoint. |
| 176 | + |
0 commit comments