Configuration options

Introduction

This page explains how Darlean can be configured by means of JSON/JSON5 configuration files, command-line arguments and environment variables and provides an overview of the configuration options for regular and runtime Darlean applications.

Mapping to JSON, command-line and the environment

Configuration options on this page are provided in the form outerScope.innerScope.configOption. For example, darlean.runtime.enabled or darlean.appId. But that is not literally how they are to be provided in a JSON/JSON5 config file, as command line argument or as environment variable.

The following table illustrates the mapping from configuration options to the corresponding JSON/JSON5 structure, command-line arguments and environment variables. This is done for two example options: darlean.runtime.enabled (which is a boolean) and darlean.runtimeApps (which is an array of strings).

Order of option sources

A configuration option provided on the command line overrules the same configuration option provided in the environment which overrules the same configuration options provided in the JSON/JSON5 config file.

Generic options

Standard options

The following are the standard Darlean options that can be used by regular applications as well as runtime applications:

• darlean.appId – The application id as a string. Used for applications to find each other on the network. When not specified, defaults to 'app'.
• darlean.runtimeApps – List of runtime application id’s as an array of strings. Used by applications to find the applications that provide essential runtime services such as the actor lock, actor registry and persistence. When not present, the id of the current application is considered the only runtime application id and the application is considered to be an all-in-one application (see the option darlean.runtime.enabled).
• darlean.pidFilePrefix – String that indicates the prefix of PID files. When not present, defaults to ./pid/. The prefix is appended with the app-id + '.pid'. This file is generated when an application starts, and deleted when it stops. It contains the process id (pid) of the application. The file can be used to gracefully stop (kill) the application on platforms that support this mechanism (unix flavors). Also, when a file with the same name is already present when the application starts up, and error is logged and the application refuses to start. This prevents duplicate application instances.
  To disable the pid file creation and the duplicate check mechanism, provide a value of 'none'.
• darlean.runFilePrefix – String that indicates the prefix of RUN files. When not present, defaults to the value of darlean.pidFilePrefix. The prefix is appended with the app-id + '.run'. The run file is generated when an application starts, and deleted when it stops. It contains the process id (pid) of the application. The file can be used to gracefully stop the application an any platform, even on those like windows that do not support a graceful stop of command-line applications. The file being watched by Darlean, and when Darlean detects that the file is removed, it will begin a graceful stop.
  To disable the run file creation and the watching mechanism, provide a value of 'none'.
• darlean.config – String that provides the path to a configuration file (including the file name) that is used for the configuration of Darlean. Can only be provided on the command-line or via the environment.

Messaging options

Darlean can use various transport mechanisms to facilitate communication between applications. By default, it uses DMB (Darlean Message Bus), which is a modified version of the simple yet powerful and performing NATS message bus.

The following options control messaging:

• darlean.messaging.transports – An array of transport names. Currently, only 'dmb' is supported. When not present, defaults to ['dmb'].

DMB messaging options

The following options control messaging by means of the Darlean Message Bus (DMB).

• darlean.messaging.dmb.hosts – An array of strings of indicating the hostnames or IP addresses for each of the configured runtime-apps. When not present, defaults to a list of local hosts (127.0.0.1). When more items are specified than present in the list of runtime-apps, the list is truncated to contain exactly that amount of items. When less items are specified than present in the list of runtime-apps, the missing apps are not considered a message system node.
  Applications use this list to connect to the DMB.
• darlean.messaging.dmb.basePort – A number indicating the base port on which the DMB can be reached. The first runtime application from the list of runtime-apps on a certain hostname/IP address listens on port basePort, the second one on port basePort + 1, and so on. When not present, defaults to port 4500.

Runtime options

The following options control whether an application acts as a runtime application and how it behaves as a runtime application.

• darlean.runtime.enabled – Boolean that indicates whether the current application should function as a runtime application. When not specified, an application is considered a runtime application when it is an all-in-one application or when it is an implicit-runtime application.
  An application is considered all-in-one when darlean.runtimeApps is not explicitly configured.
  An application is considered an implicit-runtime application when the application is not an all-in-one application (that is, darlean.runtimeApps is explicitly configured) and its app-id is in the list of (explicit) runtime-apps.

Generic persistence options

The following options relate to the generic persistence runtime functionality. This functionality provides a generic (unified) interface to persistence. For more information, see the Darlean Persistence Service.

• darlean.runtime.persistence.enabled – Boolean that indicates whether the current application should provide persistence. When not present, persistence is enabled when darlean.runtime.enabled evaluates to true.
• darlean.runtime.persistence.specifiers (JSON ONLY) – Array of IPersistenceSpecifierCfg objects that provide the mapping from specifiers (that application code provide to the persistence functionality to indicate what functional kind of data they are storing or retrieving) to compartments (that actually persist the data). Regardless of the presence of this option, a default mapping that maps everything to the 'fs.default' compartment is always present (but it can be overruled by providing a different mapping for specifier '*').
  The specifier name can contain one or more wildcards ('*'). When a value at the place of a wild card is needed in the compartment name, it can be substituted by means of '${*}' for the first wildcard occurrance, '${**}' for the second, and so on.
• darlean.runtime.persistence.handlers (JSON ONLY) – Array of IPersistenceHandlerCfg objects that provide the mapping from compartment name to the type of the actor that is responsible for the actual persistence. An actor with the specified actor type and with the compartment name as first and only id element is invoked by the persistence service. Regardless of the presence of this option, a default mapping that maps compartments 'fs.*' on the file system persistence actor type (FS_PERSISTENCE_SERVICE) is provided (but it can be overruled by providing a different mapping for compartment 'fs.*'.
  The compartment name can contain one or more wildcards ('*'). Substitution is not supported for the actor type (so, it is not possible to use '${*}' and the like as part of the actor types).

Filesystem persistence options

The following options relate to the functionality of using the file system for persistence of data.

• darlean.runtime.fsPersistence.enabled – Boolean that indicates whether the current application should provide file system persistence. When not present, file system persistence is enabled when darlean.runtime.enabled evaluates to true.
• darlean.runtime.fsPersistence.basePath – String that indicates the default base path on disk in which compartments are stored. Individual compartments can override this setting. When not present, defaults to ./persistence/.
• darlean/runtime.fsPersistence.shardCount – Number that indicates the default number of shards that are used for a compartment. Individual compartments can override this setting. The default is 8.
• darlean.runtime.fsPersistence.maxShardCount – Number that indicates the maximum number of shards that any compartment can have. Compartments that have more shards configured than this maximum will not use more than this maximum value. This can be useful for debugging as it limits the amount of folders that have to be inspected to find the data of interest.
  Warning: Changing the maximum shard count may have unexpected results. When restricting the shard count for a compartment with a higher shard count, a new folder is created in which the data for the compartment is stored. As a result, the old data may look as if it is lost, although that is actually not the case: the old data is still present, and will be used again when the original shard count is restored.
• darlean.runtime.fsPersistence.compartments (JSON ONLY) – Array of IFileSystemCompartmentCfg objects that configure the various compartments. Regardless of the presence of this option, a default compartment for 'fs.*' is always present.

Actor lock options

The following options relate to the functionality of the actor lock. The actor lock provides the guarantee that applications are the only application within the cluster that has a certain actor active. As such, it plays a crucial role in a Darlean cluster.

• darlean.runtime.actorLock.enabled – A boolean that indicates whether the actor lock functionality is enabled. When not present, the actor lock is enabled when darlean.runtime.enabled evaluates to true.
• darlean.runtime.actorLock.apps – An array of strings of application id’s that indicates which applications together form the actor lock. When not present, defaults to the list of runtime-apps.
• darlean.runtime.actorLock.redundancy – A number that indicates the redundancy of the actor lock. When the amount of applications that provide actor lock functionality form the majority of this redundancy value, the actor lock is available for applications. When not present, defaults to 3. When the number of configured runtime-apps is less than the redundancy, the redundancy is reduced to the number of configured runtime-apps.

Actor registry options

The following options relate to the actor registry functionality. The actor registry maintains an administration of which actor types are known to the system, on which applications they can be hosted, and how their placement should be.

• darlean.runtime.actorRegistry.enabled – A boolean that indicates whether the actor registry functionality is enabled. When not present, the actor registry is enabled when darlean.runtime.enabled evaluates to true.
• darlean.runtime.actorRegistry.apps – An array of strings of application id’s that indicates which applications provide the actor registry. When not present, defaults to the list of runtime-apps. At least one such application must be available to facilitate the actor registry.

DMB Server options

The following options relate to the DMB Server functionality. A group of DMB Servers form a distributed messaging bus that applications can connect to to communicate with each other. By default, every application for which the runtime functionality is enabled also acts as a DMB Server.

• darlean.runtime.dmb.enabled – A boolean that indicates whether the DMB server functionality is enabled. When not present, the internal DMB Server is enabled when darlean.runtime.enabled evaluates to true.
• darlean.runtime.dmb.clusterPortBase – A number that indicates the base cluster port. The cluster port is the port used by other DMS servers to connect to each other and to exchange messages. Like with the regular base port, the first DMS server from the list of runtime-apps for a hostname/IP Address listens to port clusterPortBase, the second to clusterPortBase + 1, and so on. When not present, defaults to port 5500.