Quickstart

This guide will help you run your first Cadence workflow in minutes. You’ll start a local Cadence server using Docker Compose, register a domain, and execute a sample workflow.

Prerequisites

Make sure you have the following installed on your system:

Docker (version 20.10 or later)
Docker Compose (version 2.0 or later)
Git

Step 1: Start Cadence Server

The easiest way to run Cadence locally is using Docker Compose. This will start all required services including Cadence server, Cassandra database, and the Web UI.

Clone the Cadence repository

git clone https://github.com/cadence-workflow/cadence.git
cd cadence

Start the services

docker compose -f docker/docker-compose.yml up

The first time you run this command, Docker will download all required images. This may take a few minutes.

You should see output indicating that services are starting:

[+] Running 5/5
 ✔ Container cadence-cassandra-1       Started
 ✔ Container cadence-prometheus-1      Started
 ✔ Container cadence-node-exporter-1   Started
 ✔ Container cadence-cadence-1         Started
 ✔ Container cadence-cadence-web-1     Started

Verify the services are running

The following services are now available:

Service	URL	Description
Cadence Frontend	`localhost:7933` (TChannel)	API endpoint
Cadence Frontend	`localhost:7833` (gRPC)	API endpoint
Cadence Web UI	http://localhost:8088	Web interface
Grafana	http://localhost:3000	Metrics dashboard
Prometheus	http://localhost:9090	Metrics storage

Using Alternative Databases

The default setup uses Cassandra. You can use MySQL or PostgreSQL instead:

# Use MySQL as the persistence layer
docker compose -f docker/docker-compose-mysql.yml up

Step 2: Access the Web UI

Open your browser and navigate to http://localhost:8088 to access the Cadence Web UI.

The Cadence Web UI provides a visual interface for monitoring workflows, viewing execution history, and querying workflow state.

The Web UI allows you to:

View workflow execution history
Query workflows by various filters
Inspect workflow details and event history
Monitor running and completed workflows

Step 3: Install Cadence CLI

The Cadence CLI is used to interact with the Cadence server, register domains, and manage workflows.

# Install Cadence CLI using Homebrew
brew install cadence-workflow

Step 4: Register a Domain

Domains are a logical grouping of workflows and activities. You must register a domain before running any workflows.

cadence --do samples-domain domain register

The --do flag specifies the domain name. You can list all domains with:

cadence domain list

Step 5: Run Your First Workflow

Now let’s run a sample workflow. Choose your preferred language:

Go
Java

Clone the Go samples repository

git clone https://github.com/cadence-workflow/cadence-samples.git
cd cadence-samples

Build the samples

make bins

This creates sample binaries in the ./bin directory.

Start a worker

Workers execute your workflow and activity code. Start the helloworld worker:

./bin/helloworld -m worker &

You should see output indicating the worker has started:

INFO  Logger created.
INFO  Domain successfully registered.  {"Domain": "samples-domain"}
INFO  Started Workflow Worker  {"Domain": "samples-domain", "TaskList": "helloWorldGroup"}
INFO  Started Activity Worker  {"Domain": "samples-domain", "TaskList": "helloWorldGroup"}

Execute the workflow

./bin/helloworld

You should see output like:

INFO  Started Workflow  {"WorkflowID": "helloworld_75cf142b-c0de-407e-9115-1d33e9b7551a", "RunID": "98a229b8-8fdd-4d1f-bf41-df00fb06f441"}
INFO  Workflow completed.  {"Result": "Hello Cadence!"}

Understanding the Code

Here’s the helloworld workflow implementation:

// Workflow definition
func helloWorldWorkflow(ctx workflow.Context, name string) (string, error) {
    ao := workflow.ActivityOptions{
        ScheduleToStartTimeout: time.Minute,
        StartToCloseTimeout:    time.Minute,
    }
    ctx = workflow.WithActivityOptions(ctx, ao)
    
    var result string
    err := workflow.ExecuteActivity(ctx, helloWorldActivity, name).Get(ctx, &result)
    if err != nil {
        return "", err
    }
    
    return result, nil
}

// Activity implementation
func helloWorldActivity(ctx context.Context, name string) (string, error) {
    return "Hello " + name + "!", nil
}

The workflow:

Defines activity execution options (timeouts)
Executes an activity asynchronously
Waits for the result
Returns the greeting

Clone the Java samples repository

git clone https://github.com/cadence-workflow/cadence-java-samples.git
cd cadence-java-samples

Build the samples

./gradlew build

Start a worker

./gradlew -q execute -PmainClass=com.uber.cadence.samples.hello.HelloWorld$HelloWorldWorker

Keep this terminal running.

Execute the workflow (in a new terminal)

./gradlew -q execute -PmainClass=com.uber.cadence.samples.hello.HelloWorld

You should see:

Hello World!

Understanding the Code

Here’s the Java helloworld workflow:

// Workflow interface
public interface HelloWorldWorkflow {
    @WorkflowMethod
    String getGreeting(String name);
}

// Workflow implementation
public static class HelloWorldWorkflowImpl implements HelloWorldWorkflow {
    private final HelloWorldActivities activities = 
        Workflow.newActivityStub(HelloWorldActivities.class);
    
    @Override
    public String getGreeting(String name) {
        return activities.composeGreeting(name);
    }
}

// Activity interface
public interface HelloWorldActivities {
    String composeGreeting(String name);
}

// Activity implementation
public static class HelloWorldActivitiesImpl implements HelloWorldActivities {
    @Override
    public String composeGreeting(String name) {
        return "Hello " + name + "!";
    }
}

Step 6: View Workflow in Web UI

Go back to the Cadence Web UI at http://localhost:8088 to see your workflow execution.

Select the domain

From the dropdown at the top, select samples-domain.

View workflow list

You’ll see your helloworld workflow execution in the list.

Inspect workflow details

Click on the workflow to see:

Complete event history
Input parameters
Execution timeline
Activity results

The workflow execution history shows all events, activity results, and the complete execution timeline.

Next Steps

Congratulations! You’ve successfully run your first Cadence workflow. Here’s what to explore next:

Explore More Samples

Try more complex workflow patterns and examples

Learn Core Concepts

Understand workflows, activities, and task lists

Production Setup

Set up Cadence for production use

CLI Reference

Master the Cadence command-line interface

Troubleshooting

Docker containers won't start

Make sure ports 7933, 7833, 8088, and 9042 are not already in use:

# Check for port conflicts
lsof -i :7933
lsof -i :8088

Stop the containers and remove volumes to start fresh:

docker compose -f docker/docker-compose.yml down -v

Worker can't connect to Cadence

Verify the Cadence frontend is running:

docker compose -f docker/docker-compose.yml ps

Check that port 7933 (TChannel) or 7833 (gRPC) is accessible:

nc -zv localhost 7933

Domain registration fails

Ensure the Cadence server is fully started (wait 30-60 seconds after docker compose up).Check Cadence server logs:

docker compose -f docker/docker-compose.yml logs cadence

Web UI shows no workflows

Make sure you’ve selected the correct domain (samples-domain) from the dropdown menu.Verify workflows were actually executed by checking worker logs.

The Docker Compose setup is intended for local development only. For production deployments, refer to the operations guide.

Clean Up

To stop all services and clean up:

# Stop services
docker compose -f docker/docker-compose.yml down

# Remove all data (databases, volumes)
docker compose -f docker/docker-compose.yml down -v

Get Started

Core Concepts

Architecture

Deployment

Operations

Client SDKs

Quickstart

Quickstart

Prerequisites

Step 1: Start Cadence Server

Using Alternative Databases

Step 2: Access the Web UI

Step 3: Install Cadence CLI

Step 4: Register a Domain

Step 5: Run Your First Workflow

Understanding the Code

Understanding the Code

Step 6: View Workflow in Web UI

Next Steps

Explore More Samples

Learn Core Concepts

Production Setup

CLI Reference

Troubleshooting

Clean Up

Build docs developers (and LLMs) love

Get Started

Core Concepts

Architecture

Deployment

Operations

Client SDKs

​Quickstart

​Prerequisites

​Step 1: Start Cadence Server

​Using Alternative Databases

​Step 2: Access the Web UI

​Step 3: Install Cadence CLI

​Step 4: Register a Domain

​Step 5: Run Your First Workflow

​Understanding the Code

​Understanding the Code

​Step 6: View Workflow in Web UI

​Next Steps

Explore More Samples

Learn Core Concepts

Production Setup

CLI Reference

​Troubleshooting

​Clean Up

Build docs developers (and LLMs) love

Quickstart

Prerequisites

Step 1: Start Cadence Server

Using Alternative Databases

Step 2: Access the Web UI

Step 3: Install Cadence CLI

Step 4: Register a Domain

Step 5: Run Your First Workflow

Understanding the Code

Understanding the Code

Step 6: View Workflow in Web UI

Next Steps

Troubleshooting

Clean Up