Skip to main content
Version: 1.3

LittleHorse Server


Let's get LittleHorse up and running in your own environment! In this lesson, we will use the quickstart from the LittleHorse Developer Hub to run your first WfSpec.

Background​

Before we get started, let's define some concepts that we will use today:

  • The LittleHorse Kernel is the digital kernel or scheduler in LittleHorse. The LittleHorse Kernel runs somewhere (in the cloud, in your environment, etc) and exposes a grpc API to clients. It is the distributed analog of the JVM in our analogy to Java.
    • The Kernel comprises of the "Server" (backend) and the "Dashboard" (frontend).
  • A Task Definition (TaskDef) is a blueprint for a single unit of work that can be executed in LittleHorse. It is analogous to a method signature in Java. An instance of a TaskDef (when you run a task) is called a TaskRun.
  • A Task Worker (LHTaskWorker) is a long-lived process that executes tasks. A Task Worker is code that you write, which uses our SDK to connect to LittleHorse, listens on a Task Queue, and executes your function/method every time LittleHorse puts a task on the queue.
  • A Workflow Specification (WfSpec) defines the logic of a process that is executed in LittleHorse. It is similar to a program in Java.
  • A Workflow Run (WfRun) is a running instance of a WfSpec. It is similar to a running instance of a program in Java.
  • An External Event (ExternalEvent) represents something that happens outside of your workflow. You can use an ExternalEvent to make your workflow wait for something to happen, like an asynchronous response from another system or waiting for a document be signed.
tip

For a more in-depth background on the Kernel, we recommend you check out the Concepts Documentation! It is our favorite part of the documentation.

Today's Workflow​

The quickstart WfSpec that we will run today models a "Know-Your-Customer" process. The workflow accepts information about a potential user of a well-regulated enterprise. The workflow will then:

  1. Request a third-party service to perform an identity check on the user.
  2. Wait for the service to respond with an answer. This is asynchronous, so we will use an ExternalEvent.
  3. Either notifies the customer of acceptance or rejection depending on the result of the identity verification step.

All of the tasks we execute simply print to the console for convenience. However, it's just plain old Java/Go/Python code, so you can easily see how we would extend them to make real API calls.

The Quickstart Know-Your-Customer Workflow
The Quickstart WfSpec

System Setup​

For this tutorial, your system will need:

as well as the language of your choice:

Java 21 or greater

First, we will run a LittleHorse Server and Dashboard for development purposes in docker (using the lh-standalone docker image):

Important

Make sure you have at least 2GB of RAM allocated to Docker and ports 2023, 8080, and 9092 must be free.

docker run --pull always --name lh-standalone --rm -d -p 2023:2023 -p 8080:8080  -p 9092:9092 \
  ghcr.io/littlehorse-enterprises/littlehorse/lh-standalone:1.3.0
tip

If you are on Linux, you can simplify the command to run the container by making use of Docker's host network. This option has multiple bugs with MacOS:

docker run --pull always --name lh-standalone --rm -d --net=host \
  ghcr.io/littlehorse-enterprises/littlehorse/lh-standalone:1.3.0

While the image is downloading, you can install our CLI tool, lhctl this CLI is used to interact with the LittleHorse Kernel:

brew install littlehorse-enterprises/lh/lhctl

Once the docker image is running and initialized, you should be able to verify connectivity with the lhctl whoami command, as follows:

>lhctl whoami
{
  "id":  {
    "id":  "anonymous"
  },
  "createdAt":  "2024-12-17T00:12:10.693Z",
  "perTenantAcls":  {},
  "globalAcls":  {
    "acls":  [
      {
        "resources":  [
          "ACL_ALL_RESOURCES"
        ],
        "allowedActions":  [
          "ALL_ACTIONS"
        ],
        "name":  ""
      }
    ]
  }
}
tip

Lastly, you should be able to see the dashboard on http://localhost:8080:

Once you have verified that you have connectivity with the lhctl command, the rest of this tutorial will assume that you have a running LittleHorse Kernel and dashboard.

Running the Quickstart​

We will now follow along with the quickstart for the language of your choice. Clone the Developer Hub:

git clone https://github.com/littlehorse-enterprises/lh-developer-hub.git
cd lh-developer-hub

The Java example is in examples/lh-server/java/00-quickstart.

The folder contains 3 main files:

  • QuickstartApplication.java: Provides separate commands to register metadata and run the task workers.
  • QuickstartWorkflow.java: Contains Java code defining the WfSpec using the LittleHorse SDK.
  • QuickstartTasks.java: Contains the plain old Java for our task workers.

To understand how exactly the code works, we recommend you check out the Concepts documentation.

Registering a WfSpec​

info

A Workflow Specification, or WfSpec, is metadata representing a series of steps to be executed when we execute a WfRun. You can think of a WfSpec as a blueprint for a business process.

We need to first register the WfSpec and TaskDef so that LittleHorse knows what to do when we tell it to execute a quickstart WfRun.

To register the WfSpec, you can run:

./gradlew -p examples/lh-server/java/00-quickstart run --args register

This command will do 3 things:

  1. Create a typed boolean ExternalEventDef called identity-verified.
  2. Create three TaskDefs called verify-identity, notify-customer-verified, and notify-customer-not-verified.
  3. Create a WfSpec called quickstart, which accepts two STR variables, full-name and email, and one MASKED INT variable, ssn.

At this point, you should be able to view the WfSpec in your LittleHorse Dashboard on http://localhost:8080/.

note

The next lessons will explain how to write a Task Worker and define a WfSpec. Patience, young Padawan.

Executing a WfRun​

Now that we have registered the WfSpec and TaskDef, we need to tell LittleHorse to execute a WfRun. We can do that in three ways:

  1. Using the lhctl run command.
  2. Using our gRPC client.
  3. Using the dashboard.
note

In this tutorial, we will use the lhctl run command to execute the WfSpec for simplicity. If you want to learn how to run a workflow from code using our SDK's, check out this documentation.

Let's execute a WfRun:

lhctl run quickstart full-name 'Obi-Wan Kenobi' email obiwan@jedi.temple ssn 123456789

This does two things. lhctl tells LittleHorse Kernel to execute the quickstart WfSpec. The command also passes the full-name, email, and ssn arguments with the values of Obi-Wan Kenobi, obiwan@jedi.temple, and 123456789 respectively.

A Running WfRun in LittleHorse Dashboard
A Running WfRun in LittleHorse Dashboard

As you can see, the WfRun is in the RUNNING state, and the TaskRun is in the TASK_SCHEDULED state.

Running the Task Workers​

Why is our WfRun "stuck"? Because no task worker is there to execute the verify-identity TaskRun that is currently in LittleHorse's Task Queue! Let's fix that by starting our Task Worker:

./gradlew -p examples/lh-server/java/00-quickstart run --args workers
A Pending ExternalEvent in LittleHorse Dashboard
A Pending ExternalEvent in LittleHorse Dashboard

Posting an Event​

You will notice that the verify-identity task completed successfully but, the workflow is still in the RUNNING state. This is because the workflow is waiting for an external event identity-verified to be posted to the workflow.

Normally in a real-world application, you would have some other service that would post an event to the workflow with webhooks. For this example, we will just use the lhctl command to post an event to the workflow. The WfSpec utilizes the Correlated Events feature such that the identity-verified event can be matched to a waiting WfRun by the email address.

Without going too deep into the internals of that feature, let's post a CorrelatedEvent and unblock our WfRun:

# lhctl put correlatedEvent <correlation key> <ExternalEventDef Name> <variable type> <value>
lhctl put correlatedEvent obiwan@jedi.temple identity-verified BOOL true

Now if we look at our WfRun again, you will see that the workflow has completed and Obi-Wan has been notified that their identity has been verified.

A Completed WfRun in LittleHorse Dashboard
A Completed WfRun in LittleHorse Dashboard

Wrapping Up​

Congratulations on executing your first WfRun at LittleHorse! You've taken your first steps into a larger world. Continue on with the next courses to learn how to develop your own applications on top of LittleHorse.

tip

In the meantime, if you haven't done so already: