References

• 1: Dolittle CLI
• 1.1: Runtime
• 1.1.1: Aggregates
• 1.1.1.1: List
• 1.1.1.2: Get
• 1.1.1.3: Events
• 1.1.2: Event Handlers
• 1.1.2.1: List
• 1.1.2.2: Get
• 1.1.2.3: Replay
• 1.1.3: Event Types
• 1.1.3.1: List
• 1.1.4: Projections
• 1.1.4.1: List
• 1.1.4.2: Get
• 1.1.4.3: Replay
• 2: Runtime
• 2.1: Compatibility
• 2.2: Configuration
• 2.3: Failures

1 - Dolittle CLI

This section helps you learn about how to use the Dolittle CLI tool. If you’re new to the CLI, jump down to the how to install section to get started.

Command overview

How to install

There are two ways to install the Dolittle CLI tool, directly as a binary or using the dotnet tool command if you’re using .NET.

Installing as a .NET tool

To install the tool globally on your machine, run:

dotnet tool install --global Dolittle.Runtime.CLI

This should make the dolittle command anywhere. You might have to modify your PATH environment variable to make it work, and the .NET installer should guide you in how to do this. If it doesn’t, you can have a look at the dotnet tool install documentation for more help.

Installing as a binary

To install the tool manually, head over to the Runtime latest release page on GitHub, expand the “Assets” section at the bottom of the release, and download the binary for your setup. Next you’ll have to place this file somewhere in your PATH to make it available as a command, on a *nix-like system, /usr/local/bin is usually a nice place, in the process of moving it we also recommend that you rename it to just dolittle. Lastly you will need to make the file executable by running chomd a+x /usr/local/bin/dolittle and you should be all set.

Subcommands

1.1 - Runtime

dolittle runtime [subcommand]

Options

Details

The dolittle runtime commands interacts with a Runtime you can access from your machine. You can specify an endpoint using the --runtime <host[:port]> option. If you don’t specify an endpoint, the CLI will try to locate a Runtime it can interact with itself. Currently it looks for Docker containers running a dolittle/runtime:* image with the management port (51052) exposed. If there are more than one available Runtime and you have not specified an endpoint, you’ll be presented with an interactive selector to choose one.

Subcommands

1.1.1 - Aggregates

dolittle runtime aggregates [subcommand]

Options

Subcommands

1.1.1.1 - List

dolittle runtime aggregates list [options]

Options

1.1.1.2 - Get

dolittle runtime aggregates get <identifier> [options]

Arguments

Options

1.1.1.3 - Events

dolittle runtime aggregates events <identifier> <eventsource> [options]

Arguments

Options

1.1.2 - Event Handlers

dolittle runtime eventhandlers [subcommand]

Options

Subcommands

1.1.2.1 - List

dolittle runtime eventhandlers list [options]

Options

1.1.2.2 - Get

dolittle runtime eventhandlers get <identifier> [options]

Arguments

Options

1.1.2.3 - Replay

Replay all events

Initiates reprocessing of all events (from position 0 in the Event Handler Stream) for all Tenants. If you want to only reprocess all events for a specific Tenant, use the replay from 0 command.

dolittle runtime eventhandlers replay all <identifier> [options]

Arguments

Options

Replay events from a specific position in the Event Handler Stream

Initiates reprocessing of events from the specified position (in the Event Handler Stream) for a specific Tenant. This command will fail if the specified position is higher than the current position for the Event Handler, which would cause some events to be skipped.

dolittle runtime eventhandlers replay from <identifier> <position> [options]

Arguments

Options

1.1.3 - Event Types

dolittle runtime eventtypes [subcommand]

Options

Subcommands

1.1.3.1 - List

dolittle runtime eventtypes list [options]

Options

1.1.4 - Projections

dolittle runtime projections [subcommand]

Options

Subcommands

1.1.4.1 - List

dolittle runtime projections list [options]

Options

1.1.4.2 - Get

dolittle runtime projection get <identifier> <scope> [options]

Arguments

Options

1.1.4.3 - Replay

Initiates a replay of all events to rebuild Projection read models. This command drops all persisted read models, and potential copies in MongoDB, and restarts the Projection to build new ones.

dolittle runtime projection replay <identifier> <scope> [options]

Arguments

Options

2 - Runtime

I’m the overview of the reference folder. I’ll appear when you click on the “References”

2.1 - Compatibility

By Runtime version:

By DotNET SDK version:

By JavaScript SDK version:

2.2 - Configuration

The Runtime uses the ASP.NET Configuration System for reading configuration related to setting up the logging and also configuration for the Runtime itself. It reads and overrides configuration in a prioritized manner where configuration from files is overridden by environment variables and command-line arguments.

Configuration points

Endpoints

Sets up the ports for the Runtime interface endpoints.

Private

The GRPC port for communication between Runtime and Clients, usually an application using the SDK, for Runtime functionalities.

• Port
  • Type: Integer
  • Default: 50053

Public

The GRPC port for communication between Runtimes using the Event Horizon.

• Port
  • Type: Integer
  • Default: 50052

Management

The GRPC port for communication between Runtimes and Clients for management related functionalities. The ´dolittle´ CLI uses this port for communicating with the Runtime.

• Port
  • Type: Integer
  • Default: 51052

ManagementWeb

The GRPC-Web port for communication between Runtimes and Clients for management related functionalities. A browser-application using GRPC-Web can communicate with the Runtime using this port.

• Port
  • Type: Integer
  • Default: 51152

Web

The REST-service endpoint for the Runtime. Only some functionalities are provided through this endpoint.

• Port
  • Type: Integer
  • Default: 8001

Metrics

The port where we provide metrics using Prometheus. Used for metrics scraping.

• Port
  • Type: Integer
  • Default: 9700

Eventstore:BackwardsCompatibility:Version

A required configuration denoting whether the event store should use the old formatting used in V6 of the runtime or the newer format. In V6 Runtime the Partition ID and Event Source ID were forced to by GUIDs and also stored as such in the database. In V7 we changed it so that these were strings, not GUIDs, thus the database scheme is slightly different and it needs to be configured explicitly. Only Runtimes that has event store databases with data from V6 of the Runtime should use the V6 option.

Type: String

Values

• V6
• V7

ReverseCalls

Contains a feature-flag for whether or not to use reverse calls implemented with actors.

• UseActors
  • Type: boolean
  • Default: True

Platform

Defines the platform specific information related to the running microservice.

• CustomerName
  • Type: string
  • Default: ‘[Not Set]’
• CustomerID
  • Type: GUID
  • Default: ‘ca900ec9-bae8-462e-b262-fa3efc825ca8’
• ApplicationName
  • Type: string
  • Default: ‘[Not Set]’
• ApplicationID
  • Type: GUID
  • Default: ‘4fe9492c-1d19-4e6b-be72-03208789906e’
• MicroserviceName
  • Type: string
  • Default: ‘[Not Set]’
• MicroserviceID
  • Type: GUID
  • Default: ‘4a5d2bc3-543f-459a-ab0b-e8e924093260’
• Environment
  • Type: string
  • Default: ‘Development’

Microservices

The addresses of other Runtimes used when subscribing to an event horizon stream. This is a dictionary mapping specifying the host:port address for reaching the Public Endpoint on the given Microservice ID (Key of the objet)

• <Microservice-GUID>
  • Host
    • Type: string
  • Port
    • Type: Integer

Tenant-Specific Configuration

Configurations that are specific to a single tenant. All of the configurations for a tenant is behind the configuration key tenants:<Tenant-Guid>

Resources

Embeddings [Obsolete]

• Servers
  • Description: The name of the host server. (Usually ‘localhost’)
  • Type: Array[string]
• Database
  • Description: The name of the mongo database
  • Type: string
• MaxConnectionPoolSize
  • Description: The max number of concurrent MongoDB connections
  • Type: Integer
  • Default: 1000

EventStore

• Servers
  • Description: The name of the host server. (Usually ‘localhost’)
  • Type: Array[string]
• Database
  • Description: The name of the mongo database
  • Type: string
• MaxConnectionPoolSize
  • Description: The max number of concurrent MongoDB connections
  • Type: Integer
  • Default: 1000

Projections

• Servers
  • Description: The name of the host server. (Usually ‘localhost’)
  • Type: Array[string]
• Database
  • Description: The name of the mongo database
  • Type: string
• MaxConnectionPoolSize
  • Description: The max number of concurrent MongoDB connections
  • Type: Integer
  • Default: 1000

ReadModels

• Host
  • Description: The full host connection string of the MongoDB connection. (Usually mongodb://localhost:27017)
  • Type: string
• Database
  • Description: The name of the mongo database
  • Type: string
• MaxConnectionPoolSize
  • Description: The max number of concurrent MongoDB connections
  • Type: Integer
  • Default: 1000

EventHorizon

Defines the event horizons for this tenant (only consents can be configured).

• <Microservice-GUID>
  • Consents
    • Description: The list of consents for a specific Partition in a public Stream from this specific tenant to specific tenant in the Microservice from the key of this entry.
    • Type: Array[Object]
      • ConsumerTenant
        • Description: The ID of the Tenant in the Microservice given above in the key of this entry that gets a consent to subscribe to the configured Partition in the configured public Stream
        • Type: GUID
      • Stream
        • Description: The ID of the public stream that the event horizon reads events from.
        • Type: GUID
      • Partition
        • Description: The partition ID of the public stream that the event horizon reads events from.
        • Type: GUID
      • Consent
        • Description: The ID of the consent. (Not used for anything yet)
        • Type: GUID

runtime.yml

The Runtime uses a single YAML configuration file called runtime.yml located under the .dolittle/ folder. This file has a 1:1 correspondence with the Runtime Configuration meaning that all fields under the runtime.yml config file gets prefixed Dolittle:Runtime: (represented as an environment variable by Dolittle__Runtime__) used in the Asp.Net configuration system.

Example config

eventStore:
    backwardsCompatibility:
        version: V6
platform:
    customerID: 6d8eaf84-969c-4234-b78f-30632a608e5a
    applicationID: e0078604-ae62-378d-46fb-9e245d824c61
    microserviceID: ffb20e4f-9227-574d-31aa-d6e59b34495d
    customerName: TheCustomer
    applicationName: THeApplication
    microserviceName: TheMicroservice
    environment: Dev
microservices:
    d47c6fb7-2339-e286-2912-2b9f163a5aa3:
        host: some.host
        port: 50052
tenants:
    1c707441-95b3-4214-a4d1-4199c58afa23:
        resources:
            embeddings:
            servers:
            - my.host
            database: embeddings
            eventStore:
            servers:
            - my.host
            database: eventstore
            readModels:
            host: mongodb://my.host:27017
            database: readmodels
            projections:
            servers:
            - dev-mongo.application-e0078604-ae62-378d-46fb-9e245d824c61.svc.cluster.local
            database: projections
        eventHorizons:
            d47c6fb7-2339-e286-2912-2b9f163a5aa3:
            consents:
            -   consumerTenant: c5b5847a-68e6-4b31-ad33-8f2beb216d8b
                stream: d9b302bb-5439-4226-a225-3b4a0986f6ed
                partition: 00000000-0000-0000-0000-000000000000
                consent: 4d43e837-0a8e-4b3d-a3eb-5301f5650d91

Default configuration

When using the dolittle/runtime images it is provided with a default runtime.yml setting up only resources for the “Development Tenant” 445f8ea8-1a6f-40d7-b2fc-796dba92dc44

tenants:
  445f8ea8-1a6f-40d7-b2fc-796dba92dc44:
    resources:
      eventStore:
        servers:
          - localhost
        database: event_store
        maxConnectionPoolSize: 1000
      projections:
        servers:
          - localhost
        database: projections
        maxConnectionPoolSize: 1000
      embeddings:
        servers:
          - localhost
        database: embeddings
        maxConnectionPoolSize: 1000
      readModels:
        host: mongodb://localhost:27017
        database: readmodels
        useSSL: false

appsettings.json

All Runtime configurations in theory can also be provided through the Asp.Net appsettings.json configuration file by simply having a Dolittle:Runtime object in the root of the configuration:

{
    "Dolittle": {
        "Runtime": {
            "Platform": {
                "ApplicationID": ...
            },
            "Tenants": {
                "<Tenant-GUID>": {
                    "Resources": {
                        ...
                    }
                }
            }
        }
    },
    "Logging": {
        ...
    }
}

Environment variables

All configurations to the Runtime can be configured with environment variables by prefixing the environment variables with Dolittle__Runtime__

Legacy

The Legacy Runtime pre version V8 uses JSON configuration files. The files are mounted to the .dolittle/ folder inside the Docker image.

platform.json

Required. Configures the Microservice environment for the Runtime.

{
    "applicationName": "<application-name>",
    "applicationID": "<application-id>",
    "microserviceName": "<microservice-name>",
    "microserviceID": "<microservice-id>",
    "customerName": "<customer-name>",
    "customerID": "<customer-id>",
    "environment": "<environment-name>"
}

tenants.json

Required. Defines each Tenant in the Runtime.

{
    <tenant-id>: {}
}

resources.json

Required. Configurations for the resources available per Tenant:

• eventStore: MongoDB configuration for the Event Store
• projections: MongoDB configuration for the storage of Projections
• embeddings: MongoDB configuration for the storage of Embeddings
• readModels: MongoDB configuration for a database that can be used for any storage and accessed through the SDKs directly. This database should only be used to store data that can be rebuilt from replaying events.

The database name must be unique for all resources and tenants, reusing the same name will cause undefined behaviour in the Runtime and potential dataloss.

{
    <tenant-id>: {
        "eventStore": {
            "servers": [
                <MongoDB connection URI>
            ],
            "database": <MongoDB database name>,
            "maxConnectionPoolSize": 1000
        },
        "projections": {
            "servers": [
                <MongoDB connection URI>
            ],
            "database": <MongoDB database name>,
            "maxConnectionPoolSize": 1000
        },
        "embeddings": {
            "servers": [
                <MongoDB connection URI>
            ],
            "database": <MongoDB database name>,
            "maxConnectionPoolSize": 1000
        },
        "readModels": {
            "host": <MongoDB connection string>,
            "database": <MongoDB database name>,
            "useSSL": false
        }
    }
}

event-horizon-consents.json

Required. Defines the Consents a Producer tenant gives to Consumers so that they can receive events over the Event Horizon.

{
    // The producer tenant that gives the consent
    <tenant-id>: [
        {
            // the consumers microservice and tenant to give consent to
            "microservice": <microservice-id>,
            "tenant": <tenant-id>,
            // the producers public stream and partition to give consent to
            "stream": <stream-id>,
            "partition": <partition-id>,
            // an identifier for this consent 
            "consent": <consent-id>
        }
    ]
}

microservices.json

Defines where the Producer microservices are so that the Consumer can Subscribe to them.

{
    // the id of the producer microservice
    <microservice-id>: {
        // producer microservices Runtime host and public port
        "host": <host>,
        "port": <port>
    }
}

endpoints.json

Defines the private and public ports for the Runtime.

{
    "public": {
        // default 50052
        "port": <port>
    },
    "private": {
        // default 50053
        "port": <port>
    }
}

metrics.json

The port to expose the Prometheus Runtimes metrics server on.

{
    // default 9700
    "Port": <port>
}

2.3 - Failures

Event Store

Filters

Event Handlers

Event Horizon