Skip to content
Home » Documentation » Operation modes

Operation modes

Darlean can operate in two operation modes: all-in-one and distributed. The all-in-one mode is perfect for local development and small-scale applications. The distributed mode is recommended for deployments that require scalability and redundancy.

Switching from one mode to the other is only a matter of configuration. No code changes are required to move from one mode to the other, and that the same code base can be used regardless of the configured operation mode.

All-in-one operation

In the all-in-one mode is the default when Darlean is not configured otherwise. In all-in-one mode, a cluster only consists of one application that contains the project-specific application logic (actors) and all necessary runtime functionality (like persistence).

The all-in-one mode is useful during the development of small applications. It is also useful for production deployments of small applications that do not require redundancy. For example, a small website for which it is okay to be offline for a minute or two during updates.

In all-in-one mode, all communication between actors is performed in-process. Darlean does not launch a Darlean Message Bus (DMB) server nor does it use DMB to try to connect to the cluster.

The default app-id for all-in-one applications is ‘app’.

Distributed operation

The distributed operation mode is automatically enabled when a list of runtime-apps is provided in the configuration. In distributed mode, applications in the cluster can work together and connect with each other.

Runtime functionality

At least one node in the cluster must have runtime functionality enabled. When redundancy is important, at least three nodes in the cluster must have runtime functionality enabled.

Runtime functionality is automatically enabled for all applications whose app-id is in the configured list of runtime-apps.

When runtime functionality is enabled for an application, is provides the following functionality to the cluster:

  • A distributed actor registry. This allows other applications to find out which actor types can run on which applications, and what the prefered placement strategy of those actor types is.
  • A distributed actor lock. This allows applications to acquire an exclusive lock on a certain actor that they intend to start running.
  • A DMB Server. A Darlean Message Bus Server is started for every application that is configured to be a runtime application.
  • The persistence service. This allows actors to load and store their state to persistent storage. It is a generic interface to specific persistence providers, such as the file system persistence provider mentioned below.
  • A file system persistence provider. This provider persists actor state to disk on a local or shared, physical or virtual file system.

Configuration

A minimal configuration file for distributed operation looks as follows:

{
    runtimeApps: ['my-app']
}

for a single-application cluster, or

{
    runtimeApps: ['runtime01', 'runtime02', 'runtime03']
}

for a cluster with multiple runtime applications.

Note that Darlean supports both JSON and JSON5 as configuration file format. The advantage of JSON5 is that it allows comments and that it does not require key names to be quoted.

Alternatively, Darlean can be started in distributed operation mode without a configuration file but with command line arguments.

For a situation in which our my-app application is the only runtime application in the cluster:

$ node ./lib/index.js --darlean-runtimeapps=my-app --darlean-appid=my-app

Or for a situation in which there are 3 runtime nodes in the cluster:

$ node ./lib/index.js --darlean-runtimeapps=runtime01,runtime02,runtime03 --darlean-appid=my-app

It is also possible to configure your environment accordingly (and/or to combine that with command line arguments):

D:> set DARLEAN_RUNTIMEAPPS=runtime01,runtime02,runtime03
D:> set DARLEAN_APPID=my-app
D:> node ./lib/index.js

For more information, see Configuration.