Search

Download files

Before you begin,

Ensure you have downloaded the LedgerBridge JAR file (gospel-ledgerbridge-<version>.jar) from the Gospel Dashboard> Downloads section.
Download the certificate and private key for the current session from the Tools > Certificate Tools page.

Starting LedgerBridge

You can start LedgerBridge using any of the following options:

Start with default settings (without configuration): Starts LedgerBridge at the default port, http://localhost:8080/login, with limited features.
Command Line Arguments: Pass parameters as command line arguments.
Properties File: You can set and configure the properties file which contains the configurations used to start LedgerBridge.

Start LedgerBridge with default settings

Starting LedgerBridge without any configuration allows you to log on to the LedgerBridge administration console and view the configurations available for starting LedgerBridge and the LedgerBridge connector. Run the following command in the terminal:

java -jar gospel-ledgerbridge-<version>.jar

Log on to the LedgerBridge administration console (http://localhost:8080/login) using the password provided in the terminal. On this page, you can enter the required configuration and generate a properties file using the Download Config option. Save the file (application.properties) to the directory which contains the gospel-ledgerbridge-<version>.jar file, and restart LedgerBridge to apply the new configuration.

When you start LedgerBridge without configuration, LedgerBridge starts with minimal functionalities. This option is useful only for viewing the dashboard and generating the properties file. To be able to import records, start LedgerBridge either by passing parameters as command-line arguments or by defining the properties file.

The LedgerBridge Administrative Panel > Config Builder page displays the configuration currently applied when starting the LedgerBridge.

On this page, you can provide the required configuration and generate a configuration file using the Download Config option. Save the file to the LedgerBridge directory as application.properties and restart LedgerBridge to apply the new configuration.

Pass parameters in the terminal as command-line arguments

To pass the parameters in the terminal as command-line arguments, go to the directory where the gospel-ledgerbridge-<version>.jar file is located, and run the following command:

java -jar gospel-ledgerbridge-<version>.jar --gospelUrl=<https://URL> --pathToCertificate=<path/../certificate> --pathToPrivateKey=<path/../privatecertificate>

The code example lists some configuration values required for starting LedgerBridge. You can provide additional configuration parameters if required.
You can download the certificate and private key for the current session from the Tools > Certificate Tools page.

Log on to the LedgerBridge administration console (http://localhost:8080/login) using the password provided in the terminal.

Defining properties

You can store configurable properties in an application.properties file and place it in the same directory as the JAR file.

Each parameter is stored as a pair of strings, one storing the name of the parameter, and the other storing the value. For example, dataLocation=datafiles where, dataLocation is the parameter and datafiles is the value.

The parameters set from the command line have precedence over the properties file in the project directory.

If you have defined the configuration in the application.properties file, open the terminal, go to the directory where the gospel-ledgerbridge-<version>.jar file is located, and run the following command:

java -jar gospel-ledgerbridge-<version>.jar

Log on to the LedgerBridge administration console (http://localhost:8080/login). Use the password defined in the properties file, or use the password generated for this session displayed in the terminal.

Configuring LedgerBridge Settings

The table lists and describes the configuration values you can set in the applications.properties or pass as parameters in the terminal when starting the LedgerBridge:

If you make changes to the configuration, you must restart LedgerBridge to apply the changes.
The parameters set from the command line have precedence over the properties file in the project directory.

Properties	Description	Value
`queueSize`	Size of the record queue is allowed to grow to before it is consumed and sent to LedgerBridge. If the number is too large, the amount of queue space taken up can become excessive as the data is not committed, and cannot be removed from the queue until the data is committed.	Default: `1000` Minimum value: `100` Maximum value = `10000`
`batchSize`	The records are sent to the LedgerBridge in batches. Set the number of records to be sent in each batch. For example, if you set the value to a big number, more data is sent to the LedgerBridge, and if the value is set to a small number, frequent requests are made to the LedgerBridge for data.	Default: `10` Minimum value: `1` Maximum value: `100`
`batchTimeoutSeconds`	Time in seconds after which a record batch gets consumed, even if it has not reached the set batch size.	Minimum value: `1` Maximum value: `100`
`preserveSharedSecretBetweenRuns`	When set to true, the LedgerBridge Connector attempts to load secret from the file system, based on the parameters passed. Otherwise, it generates a random secret.	`True` (Default) `False`
`sharedSecretFileName`	Required. The file containing the secret passphrase that is shared between Ledgerbridge and Ledgerbridge connector	Default: .ledgerbridge
`pathToDirectoryContainingSharedSecret`	Required. The directory containing the secret passphrase that is shared between Ledgerbridge and Ledgerbridge connector
`sharedSecretLength`	The shared secret length in bytes	Default: `64` Minimum value: `32` Maximum value: `1024`
`tokenValidityPeriodSeconds`	The period (in seconds) after which a LedgerBridge connection-token becomes invalid	Default: `15` Minimum value: `1` Maximum value: `3600`
`logErrorsToFileSystem`	Message logging is disabled by default. When enabled, it logs on files (debug.log and error.log) in a /logs folder created under the current path and archives it through a rolling policy. The maximum default size of the log files is 10 MB. When the maximum size is reached, a back up of the file is created and renamed to <filename.timestamp>.log.	`True` `False` (Default)
`logDirectory`	The path to the directory where the log files are saved.	Default: `./logs`
`pathToCertificate`	The full path to the directory containing the certificate file and private key. You can download the certificate and private key for the current session from the Tools > Certificate Tools page.	`/path/to/certificate`
`pathToPrivateKey`		`/path/to/key`
`gospelUrl`	Required. The address of the Gospel UI.	`http://localhost:8080`
`apiVersion`	The version of the Gospel API.	Default: `v1.1`
`idField`	Required. The field in the data source that defines the ID for the records. You can use `%AUTOID%` to automatically generate the ID when importing the records.	Default: `id`
`action`	Required. Value for the "Action" field.	Expected values are, `write` (Default) `delete` `read`
`uiPassword`	The password used for logging on to the UI. If you leave this field empty, the password that is automatically generated when you start LedgerBridge is displayed in the terminal.
`errorRecordDefinitionId`	The record definition to which the logs are written. Ensure that the record definition has required permissions, and contains fields message and loglevel that are of type string.
`errorRecordDefinitionVersion`	The version of the record definition to which the logs are written.
`chainLogLevel`	You can set the following severity level of the messages to control the type of messages displayed on the console. DISABLED: Disables logging ERROR: Logs errors and critical errors WARN: Logs warnings, errors, and critical errors INFO: Logs informational messages DEBUG: Logs debug messages and also logs informational messages, warnings, errors, and critical errors TRACE: Logs trace messages that can be used for problem-solving	Default: `DISABLED`
`recordDefinitionCacheMinutes`	Duration in minutes for which the Record Definition is stored in the cache.	Default: `60`
`backendConnectionTimeoutSeconds`	Duration in seconds for which LedgerBridge should wait to get the RecordDefinition from the backend before timing out.	Default: `15`
`metricPrintPeriodMinutes`	Duration in minutes between each set of metrics that are reported in the console Set the value to zero (`0`) to disable the feature.	Default: `5`
`metricLogLevel`	Records the rate of logged events by their logging level Ensure that the following properties are set in the application.properties to enable logging: `logging.level.com.gospel=DEBUG` `logging.level.tech.gospel=DEBUG`	Default: `DEBUG` Options: `DEBUG` `ERROR` `INFO` `TRACE` `WARN`

Example Configuration

Below is an example of the application.properties file containing the available configurations that can be provided when starting LedgerBridge:

queueSize=100
batchSize=10
batchTimeoutSeconds=1
preserveSharedSecretBetweenRuns=true
sharedSecretFileName=.ledgerbridge
pathToDirectoryContainingSharedSecret=.
sharedSecretLength=64
tokenValidityPeriodSeconds=15
logErrorsToFileSystem=true
logDirectory=./logs
pathToCertificate=spcert.pem
pathToPrivateKey=spkey.pem
gospelUrl=https://sample-gospel-url.com
apiVersion=v1.1
idField=id
action=write
uiPassword=p
errorRecordDefinitionId=RecordErrors
errorRecordDefinitionVersion=1
chainLogLevel=DISABLED
recordDefinitionCacheMinutes=60
backendConnectionTimeOutSeconds=15
metricPrintPeriodMinutes=5
metricLogLevel=DEBUG

Step 1- Configure and start LedgerBridge