Configuration

Mounting a config file

Create a config file in JSON format in a folder of your choice.
Fill the config file with your desired configuration (it’s sufficient to add values you want to change; the Connector will merge your config file with the default configuration) Example:
```
{
  "infrastructure": {
    "httpServer": {
      "enabled": true,
      "apiKey": "an-api-key"
    }
  }
}
```
Mount the created config file into the Docker container (e.g. to /config.json). See the official documentation for more information on how to mount files into a Docker container. This is also possible using docker compose.
Set the environment variable CUSTOM_CONFIG_LOCATION to the path you mounted your config file to (e.g. CUSTOM_CONFIG_LOCATION="/config.json").

There is also an example config file available. It sets some default values, please only use the fields you require

Environment variables

The configuration can also be done using environment variables. This feature is included in the Connector since version 2.2.1.

Parsing rules

Nested fields can be represented using a colon (:) as a separator.

The : separator doesn’t work with environment variable hierarchical keys on all platforms. The double underscore (__) is supported on all platforms (e.g. bash does not support the : separator but it supports __ ). The Connector will therefore convert __ to : so you can use it on that systems.
The parameter casing must be the same as the config file casing.
The strings “true” and “false” are converted to the respective boolean values.
Number strings ("1" / "1.1") will be converted to the respective number types.
Complex structures (arrays, objects) are not supported. (=> modules:aModule:aKey='{"a": "x", "b": "y"}' or modules:aModule:aKey='["a", "b"]' is not valid)

Example

You want to configure the following values:

{
  "infrastructure": {
    "httpServer": {
      "enabled": true,
      "port": 8080,
      "apiKey": "an-api-key"
    }
  }
}

The first value can be configured using the variable infrastructure:httpServer:enabled="true". Note that the value is represented as a string in the environment variable and the Connector will rewrite it to its boolean representation.
The second value can be configured using the variable infrastructure:httpServer:port="8080". Note that the value is represented as a string in the environment variable and the Connector will rewrite it to its number representation.
The third value can be configured using the variable infrastructure:httpServer:apiKey="an-api-key".

Configuration options

The Connector provides the following configuration parameters:

{
    "debug": false,
    "transportLibrary": {
        "baseUrl": "https://prod.enmeshed.eu",
        "platformClientId": "CLIENT_ID",
        "platformClientSecret": "CLIENT_SECRET"
    },
    "database": {
        "connectionString": "mongodb://[username:password@]host1[:port1][,...hostN[:portN]][/[defaultauthdb][?options]]",
        "dbName": "a-db-name"
    },
    "infrastructure": { ... },
    "modules": { ... }
}

You can validate the config using our schema file. This is possible for example with VSCode or online tools like jsonschemavalidator.net.

debug `availbable since version 3.3.0`

⚠️ Do not turn on debug mode in production environments.

The debug flag configures if the Connector is set to production or debug mode. Defaults to false. Can also be configured using the environment variable DEBUG.

transportLibrary

baseUrl default: "https://prod.enmeshed.eu"

The base url is used to communicate with the enmeshed platform. It can be changed to use a custom enmeshed Backbone.
platformClientId required

The client id is required to communicate with the enmeshed platform. It can be acquired from the enmeshed Support.
platformClientSecret required

The client secret is required to communicate with the enmeshed platform. It can be acquired from the enmeshed Support.

database

connectionString required

At this point the connection to the database can be configured. The connection string must follow the MongoDB Connection String URI Format.
dbName default: "default"

The dbName string is used as the name of the MongoDB database, prefixed with acc-. You can use any name you like, but keep in mind that changing it later will NOT rename the database. Instead a new database will be created, together with a new enmeshed identity. Even though the old database will still exist, the Connector will not be able to access the data until you change the dbName back to its original value.

If you would like to use multiple Connectors with distinct identities (one identity per Connector) running on the same database, you have to specify a unique dbName for each of them.

Note: If you are using the Connector in combintation with a FerretDB, you have to pay attention to the database name restrictions specified in the FerretDB documentation.

infrastructure

Each infrastructure can be enabled or disabled by passing true / false to enabled.

httpServer

The HTTP server is the base for the coreHttpApi Module. It opens an express HTTP server where Modules can register endpoints.

Sample Configuration:

{
  // ...

  "infrastructure": {
    "httpServer": {
      "enabled": true,
      "cors": {
        "origin": false
      },
      "apiKey": "an-api-key"
    }
  }
}

enabled default: true

Enable or disable the HTTP server.
cors default: { "origin": false }

configure the CORS middleware. Valid options can be found here.
apiKey required

Define the API-Key the Connector should use to authenticate requests.

The API-Key can be chosen arbitrarily and has to be sent with every request in the X-API-KEY HTTP-Header.

There are no limitations regarding the allowed characters. We recommend using an API-Key that is at least 20 characters long.

The API-Key protects your Connector from unauthorized access and should therefore be kept secret.

helmetOptions default: depending on the connector mode

Configure the helmet middleware.

Defaults to {} in production mode. In debug mode the following options are used:

{
  "contentSecurityPolicy": {
    "directives": {
      "defaultSrc": [],
      "scriptSrc": ["'self'"],
      "styleSrc": ["'self'", "'unsafe-inline'", "https://fonts.googleapis.com"],
      "imgSrc": ["'self'", "https://enmeshed.eu", "data:"],
      "connectSrc": ["'self'"],
      "upgradeInsecureRequests": null
    }
  }
}

modules

Every Module can be enabled or disabled by passing true / false to enabled. Read more about the Module by clicking on the icon in each title.

amqpPublisher

This module is deprecated in favor of the Message Broker Publisher Module.

Sample Configuration:

{
  // ...

  "modules": {
    "amqpPublisher": {
      "enabled": false,
      "url": "amqp://example.com:5672",
      "exchange": "myExchange"
    }
  }
}

enabled default: false

Enable or disable the AMQP Publisher Module.
url required

The URL of the AMQP server.
exchange default: ""

The name of the AMQP exchange to publish to.

autoAcceptRelationshipCreationChanges

It is not recommended to use this Module for production scenarios.

Sample Configuration:

{
  // ...

  "modules": {
    "autoAcceptRelationshipCreationChanges": {
      "enabled": false,
      "responseContent": {}
    }
  }
}

enabled default: false

Enable or disable the autoAcceptRelationshipCreationChanges Module.
responseContent default: {}

The content that is used to accept the incoming Relationship Request.

coreHttpApi

Sample Configuration:

{
  // ...

  "modules": {
    "coreHttpApi": {
      "enabled": true,
      "docs": {
        "enabled": false,
        "rapidoc": {
          "persistAuth": false
        }
      }
    }
  }
}

enabled default: true

Enable or disable the coreHttpApi Module.
docs:enabled default: false

It is not possible to enable the docs in production mode.

Enable / disable the /docs/json and /docs/yaml routes and the rendered swagger / rapidoc documentations.
docs:rapidoc:persistAuth default: false

Authentication persistence can be a security risk. Use it with caution.

If set to true rapidoc persists the API Key in the local storage of the browser.

messageBrokerPublisher

Sample Configuration:

{
  // ...

  "modules": {
    "messageBrokerPublisher": {
      "enabled": false,
      "brokers": []
    }
  }
}

enabled default: false

Enable or disable the sync Module.
brokers default: []

Here you can define multiple brokers to which the Connector should publish messages.

Each broker consists of a type (string) and a config object. The type specifies the type of the broker (e.g. AMQP or PubSub) and the config object contains the configuration for the broker.
- type AMQP
  
  example
```
{
  "type": "AMQP",
  "config": {
    "url": "amqp://example.com:5672",
    "exchange": "myExchange"
  }
}
```
  configuration
  - url string, required -
    
    the URL of the AMQP broker
    
    the URL must be in the AMQP url format
  - exchange string -
    
    the name of the exchange to publish to
  - timeout number -
    
    the timeout in milliseconds for the broker to respond
- type MQTT
  
  example
```
{
  "type": "MQTT",
  "config": {
    "url": "mqtt://example.com:1883"
  }
}
```
  configuration
  - url string, required
    
    the URL of the MQTT broker
    
    the URL can be on the following protocols: mqtt, mqtts, tcp, tls, ws, wss, wxs or alis
- type PubSub
  
  example
```
{
  "type": "PubSub",
  "config": {
    "projectId": "myProjectId",
    "topicName": "myTopicName",
    "keyFile": "/path/to/keyfile.json"
  }
}
```
  configuration
  - projectId string, required
    
    the project id of the Google Cloud project
  - topicName string, required
    
    the name of the PubSub topic to publish to
  - keyFile string, required
    
    the (absolute) path of the key file to authenticate with the Google Cloud project
- type Redis
  
  example
```
{
  "type": "Redis",
  "config": {
    "url": "redis://example.com:6379"
  }
}
```
  configuration
  - url string, required
    
    the URL of the broker
    
    the URL must be in the Redis url format: redis[s]://[[username:]password@]host[:port][/database]

sync

Sample Configuration:

{
  // ...

  "modules": {
    "sync": {
      "enabled": false,
      "interval": 60
    }
  }
}

enabled default: false

Enable or disable the sync Module.
interval default: 60

The interval in seconds at which the sync Module will fetch changes from the Backbone.

PubSubPublisher

This module is deprecated in favor of the Message Broker Publisher Module.

Sample Configuration:

{
  // ...

  "modules": {
    "PubSubPublisher": {
      "enabled": false,
      "projectId": "",
      "topic": "",
      "keyFile": ""
    }
  }
}

enabled default: false

Enable or disable the PubSub Publisher Module.
projectId required

The project id of the Google Cloud project.
topic required

The name of the PubSub topic to publish to.
keyFile required

The (absolute) path of the key file to authenticate with the Google Cloud project.

webhooks

Sample Configuration:

{
  // ...

  "modules": {
    "webhooks": {
      "enabled": false,
      "targets": {},
      "webhooks": []
    }
  }
}

enabled default: false

Enable or disable the webhooks Module.
targets default: {}

Here you can predefine targets so you can reuse them for multiple webhooks.

A target consists of a URL as well as optional arbitrary headers, which the Connector should send as part of the request. Optionally, your URL can contain the placeholder {{trigger}}, which at runtime will be replaced with the event name that triggered the webhook (e.g. transport.messageReceived). This way, you can reuse the same target for multiple webhooks and still have different URLs for different events. See the code below for an example.

The server under the URL must respond to the request with a status code between 200 and 299. Otherwise the Connector will log a warning.

Example
```
{
  // a target with headers
  "target1": {
    "url": "https://example.com/enmeshed/webhook2",

    // the following headers will be sent as part of the webhook
    "headers": {
      "a-header": "a-value",
      "another-header": "another-value"
    }
  },

  // a target without headers
  "target2": {
    "url": "https://example.com/enmeshed/webhook"
  },

  // a target with the {{trigger}} placeholder as part of the URL
  "target3": {
    "url": "https://example.com/enmeshed/webhook/{{trigger}}"
  }
}
```

webhooks default: []

The webhooks that will be called. A webhook consists of one or more Connector Events on which the webhook should be triggered, as well as a target to which the request should be sent. The target either is an inline definition of target as described above, or a name of a target defined in the targets object.

Example

[
  {
    "triggers": ["transport.messageReceived"],

    // inline declaration of a target
    "target": {
      // see the targets section for a description of how to configure a target
    }
  },
  {
    "triggers": ["transport.messageReceived"],

    // a reference to a target defined in the 'targets' object
    "target": "target1"
  }
]

Payload

{
  // the event name (e.g. transport.messageReceived) that triggered the webhook
  "trigger": "transport.messageReceived",

  // the data of the event
  "data": {}
}

You can find type definitions of the event data in the Connector Events section.

Troubleshooting

If you encounter any problems while configuring the Connector, head over to the Troubleshooting site.

Operate enmeshed

Mounting a config file

Environment variables

Parsing rules

Example

Configuration options

debug availbable since version 3.3.0

transportLibrary

database

infrastructure

httpServer

modules

amqpPublisher

autoAcceptRelationshipCreationChanges

coreHttpApi

messageBrokerPublisher

sync

PubSubPublisher

webhooks

Payload

Troubleshooting

debug `availbable since version 3.3.0`