Skip to main content

Quickstart


In this lesson, we'll get you started playing around with LittleHorse in a local development environment as quickly as possible.

System Setup​

For this tutorial, your system will need:

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

warning

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

docker run --name littlehorse --rm -d -p 2023:2023 -p 8080:8080 ghcr.io/littlehorse-enterprises/littlehorse/lh-standalone:latest

While the image is downloading, you can install our CLI tool, lhctl:

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":  ""
      }
    ]
  }
}

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

note

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 server and dashboard.

Running the Example​

We will now follow along with our Java Quickstart. Clone the quickstart repository and navigate into it:

git clone https://github.com/littlehorse-enterprises/lh-quickstart-java.git
cd lh-quickstart-java

The repository contains three main files:

  • Main.java: This file is the executable entrypoint. This file registers the Workflow Specification (WfSpec), Task Definition (TaskDef), and runs the task worker.
  • QuickstartWorkflow.java: Contains Java code defining the WfSpec using the LittleHorse SDK.
  • Greeter.java: Contains the plain old Java code for our task worker.
info

In this course, we will run through the quickstart at a high level. In the following lessons we will recreate the entire quickstart from scratch.

Registering the Workflow​

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

info

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

To register the WfSpec, you can run:

./gradlew run --args register

This command will do two things:

  1. Create a TaskDef called greet, which takes in one parameter.
  2. Create a WfSpec called quickstart, which executes one (lonely) task: the greet task.

A WfSpec in LH Dashboard

This workflow accepts a STR variable (representing a name), and greets that name by calling the greet task.

info

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

Executing the WfSpec​

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

  1. Using the lhctl run command.
  2. Using our GPRC Client.
  3. Using the dashboard.
note

In this tutorial, we will use the lhctl run command to execute the WfSpec for simplicity. In Executing WfSpecs, we will explore how to execute WfSpecs using the gRPC Client and the dashboard.

Let's execute a WfSpec:

lhctl run quickstart input-name obi-wan

This does two things. lhctl tells LittleHorse server to execute the "quickstart" WfSpec. The command also passes the "input-variable" argument with the value of "obi-wan".

A WfRun Pending in LH Dashboard

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

Run the Task Worker​

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

./gradlew run --args worker

Now if we look at our WfRun again, we can see that it was completed, and that we said a proper "Hello, there!" to Obi-Wan!

A Completed WfRun in LH Dashboard

Wrapping Up​

Congratulations on executing your first WfSpec 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.

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