Installation

This guide covers different methods to install and run Cadence server in your environment. Choose the method that best fits your needs.

Installation Options

Docker

Recommended for development and testing

Homebrew

Quick installation on macOS

From Source

Full control and latest features

Docker Installation (Recommended)

Docker provides the fastest way to get started with Cadence, bundling all dependencies together.

Prerequisites

Requirements:

Docker version 20.10+
Docker Compose version 2.0+
At least 4GB of RAM allocated to Docker

Quick Start with Docker Compose

Clone the repository

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

Start Cadence server

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

This starts:

Cadence server (all 4 services: frontend, matching, history, worker)
Cassandra database
Cadence Web UI
Prometheus (metrics)
Grafana (monitoring dashboards)

Verify installation

Check that all services are running:

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

You should see all services in “running” state.

Docker Compose Variants

Cadence provides several Docker Compose configurations for different setups:

Database Options
Advanced Visibility
Special Configurations

Choose your preferred persistence layer:

# Cassandra with basic visibility
docker compose -f docker/docker-compose.yml up

Enable advanced search capabilities:

# Cadence with Elasticsearch 7.x
docker compose -f docker/docker-compose-es-v7.yml up

Advanced visibility enables:

Full-text search on workflow attributes
Complex query capabilities
Custom search attributes
Better performance for large-scale deployments

# Run multiple Cadence clusters for XDC replication
docker compose -f docker/docker-compose-multiclusters.yml up

Using Released Versions

By default, docker-compose.yml uses the master-auto-setup tag which tracks the latest development version. For production or stable environments, use a specific release:

Download a release

Go to Cadence releases and download the docker.tar.gz file:

# Example for version v1.2.9
wget https://github.com/cadence-workflow/cadence/releases/download/v1.2.9/docker.tar.gz
tar -xzvf docker.tar.gz
cd docker

Start the release

docker compose up

Update to the latest master image:

docker pull ubercadence/server:master-auto-setup

Homebrew Installation (macOS)

For macOS users, Homebrew provides a convenient way to install Cadence CLI and schema tools.

Install Cadence Tools

brew install cadence-workflow

This installs:

cadence - CLI tool
cadence-server - Server binary
cadence-sql-tool - SQL schema management
cadence-cassandra-tool - Cassandra schema management
Schema files at /usr/local/etc/cadence/schema/

Install Database

You’ll need to install and configure a database:

Cassandra
MySQL
PostgreSQL

# Install Cassandra
brew install cassandra

# Start Cassandra service
brew services start cassandra

# Verify Cassandra is running
cqlsh -e "DESCRIBE KEYSPACES;"

# Install MySQL
brew install mysql

# Start MySQL service
brew services start mysql

# Create Cadence user
mysql -u root <<EOF
CREATE USER 'uber'@'%' IDENTIFIED BY 'uber';
GRANT ALL PRIVILEGES ON *.* TO 'uber'@'%';
FLUSH PRIVILEGES;
EOF

# Install PostgreSQL
brew install postgresql@14

# Start PostgreSQL service
brew services start postgresql@14

# Create Cadence user and database
psql postgres <<EOF
CREATE USER postgres WITH PASSWORD 'cadence';
ALTER USER postgres WITH SUPERUSER;
EOF

Install Database Schema

After setting up your database, install the Cadence schema:

make install-schema

# Or manually with the tool
cadence-cassandra-tool \
  --ep 127.0.0.1 \
  create \
  -k cadence \
  --rf 1

cadence-cassandra-tool \
  --ep 127.0.0.1 \
  -k cadence \
  setup-schema \
  -v 0.0

cadence-cassandra-tool \
  --ep 127.0.0.1 \
  -k cadence \
  update-schema \
  -d /usr/local/etc/cadence/schema/cassandra/cadence/versioned

You need to install schemas for both the cadence (main) and cadence_visibility databases. Repeat the above commands with the visibility schema paths.

Start Cadence Server

# For Cassandra
cadence-server start

# For MySQL
cadence-server --zone mysql start

# For PostgreSQL
cadence-server --zone postgres start

Build from Source

Building from source gives you the latest features and full control over the build.

Prerequisites

# Install Go
brew install go

# Verify Go installation
go version  # Should be 1.21+

# Set up GOPATH if not already set
echo 'export PATH=$PATH:$GOPATH/bin' >> ~/.zshrc
source ~/.zshrc

Build Cadence

Clone the repository

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

Initialize submodules

git submodule update --init --recursive

Download dependencies

go mod download

Build all binaries

make bins

This creates:

cadence-server - Main server binary
cadence - CLI tool
cadence-cassandra-tool - Cassandra schema tool
cadence-sql-tool - SQL schema tool
cadence-canary - Canary testing tool
cadence-bench - Benchmarking tool

All binaries are placed in the current directory.

If you encounter build errors:

Ensure you’re using Go 1.21 or later
Run git submodule update --init --recursive for proto/thrift errors
Check the Dockerfile for the latest build steps

Development Setup

For active development, set up the full development environment:

Start dependencies

Choose your database and start it with Docker:

# Cassandra
docker compose -f ./docker/dev/cassandra.yml up -d

# Or MySQL
docker compose -f ./docker/dev/mysql.yml up -d

# Or PostgreSQL
docker compose -f ./docker/dev/postgres.yml up -d

Install schema

# For Cassandra
make install-schema

# For MySQL
make install-schema-mysql

# For PostgreSQL
make install-schema-postgres

# For SQLite (no external DB needed)
make install-schema-sqlite

Run the server

# Cassandra
./cadence-server start

# MySQL
./cadence-server --zone mysql start

# PostgreSQL
./cadence-server --zone postgres start

# SQLite (no external DB)
./cadence-server --zone sqlite start

./cadence --do samples-domain domain register

Database Configuration

Cadence requires two types of storage:

Core Persistence: Stores workflow state, history, and metadata
Visibility Storage: Enables workflow search and listing

Supported Databases

Cassandra
MySQL
PostgreSQL
SQLite

Recommended for: High-throughput, large-scale deploymentsConfiguration (config/development.yaml):

persistence:
  defaultStore: cass-default
  visibilityStore: cass-visibility
  numHistoryShards: 4
  datastores:
    cass-default:
      nosql:
        pluginName: "cassandra"
        hosts: "127.0.0.1"
        keyspace: "cadence"
        connectTimeout: 2s
        timeout: 10s
        consistency: LOCAL_QUORUM
    cass-visibility:
      nosql:
        pluginName: "cassandra"
        hosts: "127.0.0.1"
        keyspace: "cadence_visibility"

Cassandra provides excellent scalability and is the most battle-tested option for Cadence.

Recommended for: Small to medium deployments, existing MySQL infrastructureConfiguration (config/development_mysql.yaml):

persistence:
  defaultStore: mysql-default
  visibilityStore: mysql-visibility
  numHistoryShards: 4
  datastores:
    mysql-default:
      sql:
        pluginName: "mysql8"
        databaseName: "cadence"
        connectAddr: "127.0.0.1:3306"
        connectProtocol: "tcp"
        user: "uber"
        password: "uber"
        maxConns: 20
        maxIdleConns: 20
    mysql-visibility:
      sql:
        pluginName: "mysql8"
        databaseName: "cadence_visibility"
        connectAddr: "127.0.0.1:3306"
        connectProtocol: "tcp"
        user: "uber"
        password: "uber"
        maxConns: 10
        maxIdleConns: 10

MySQL 8.0 is supported. For MySQL 5.7, use the appropriate schema version.

Recommended for: Organizations with PostgreSQL expertiseConfiguration (config/development_postgres.yaml):

persistence:
  defaultStore: postgres-default
  visibilityStore: postgres-visibility
  numHistoryShards: 4
  datastores:
    postgres-default:
      sql:
        pluginName: "postgres12"
        databaseName: "cadence"
        connectAddr: "127.0.0.1:5432"
        connectProtocol: "tcp"
        user: "postgres"
        password: "cadence"
        maxConns: 20
        maxIdleConns: 20
    postgres-visibility:
      sql:
        pluginName: "postgres12"
        databaseName: "cadence_visibility"
        connectAddr: "127.0.0.1:5432"
        connectProtocol: "tcp"
        user: "postgres"
        password: "cadence"
        maxConns: 10
        maxIdleConns: 10

Recommended for: Development, testing, single-machine deploymentsConfiguration (config/development_sqlite.yaml):

persistence:
  defaultStore: sqlite-default
  visibilityStore: sqlite-visibility
  numHistoryShards: 4
  datastores:
    sqlite-default:
      sql:
        pluginName: "sqlite"
        databaseName: "/tmp/cadence.db"
    sqlite-visibility:
      sql:
        pluginName: "sqlite"
        databaseName: "/tmp/cadence_visibility.db"

SQLite is not recommended for production use. Use it only for development and testing.

Number of History Shards

The numHistoryShards configuration determines the parallelism and scalability of your Cadence cluster:

persistence:
  numHistoryShards: 1024  # Choose based on scale

Choosing shard count:

Development: 4 shards
Small production: 64-128 shards
Medium production: 512 shards
Large production: 1024-4096 shards

This value CANNOT be changed after deployment without data migration.

Advanced Visibility Setup

For production deployments with large workflow volumes, set up advanced visibility:

Elasticsearch
OpenSearch

# Start Elasticsearch with Kafka
docker compose -f docker/dev/cassandra-esv7-kafka.yml up -d

# Install Elasticsearch schema
make install-schema-es-v7

# Start server with ES configuration
./cadence-server --zone es_v7 start

Benefits:

Full-text search on workflow attributes
Custom search attributes
Complex query capabilities
Better performance at scale

# Start OpenSearch with Kafka
docker compose -f docker/dev/cassandra-opensearch-kafka.yml up -d

# Install OpenSearch schema
make install-schema-es-opensearch

# Start server
./cadence-server --zone es_opensearch start

Verification

After installation, verify your Cadence setup:

Check server health

# Using CLI
cadence cluster health

# Using curl
curl http://localhost:7933/health

cadence --do test-domain domain register --retention 7

List domains

cadence domain list

You should see your newly created domain.

Access Web UI

Open http://localhost:8088 in your browser (if using Docker setup).

Next Steps

Quickstart

Run your first workflow

Configuration

Advanced server configuration

Production Setup

Deploy Cadence in production

Monitoring

Set up metrics and monitoring

Troubleshooting

Build fails with 'cannot find module'

Update submodules and dependencies:

git submodule update --init --recursive
go mod download

Schema installation fails

Ensure your database is running and accessible:

# For Cassandra
cqlsh -e "DESCRIBE KEYSPACES;"

# For MySQL
mysql -u uber -puber -e "SHOW DATABASES;"

# For PostgreSQL
psql -U postgres -c "\l"

Server won't start

Check the configuration file and logs:

# Verify config syntax
./cadence-server --config config/development.yaml validate

# Check server logs
./cadence-server start 2>&1 | tee server.log

Port already in use

Find and stop the process using required ports:

# Find process on port 7933
lsof -ti:7933 | xargs kill -9

# Or change ports in config

For production deployments, refer to the comprehensive operations documentation for best practices on scaling, monitoring, and maintaining Cadence clusters.

Get Started

Core Concepts

Architecture

Deployment

Operations

Client SDKs

Installation

Installation

Installation Options

Docker

Homebrew

From Source

Docker Installation (Recommended)

Prerequisites

Quick Start with Docker Compose

Docker Compose Variants

Using Released Versions

Homebrew Installation (macOS)

Install Cadence Tools

Install Database

Install Database Schema

Start Cadence Server

Build from Source

Prerequisites

Build Cadence

Development Setup

Database Configuration

Supported Databases

Number of History Shards

Advanced Visibility Setup

Verification

Next Steps

Quickstart

Configuration

Production Setup

Monitoring

Troubleshooting

Build docs developers (and LLMs) love

Get Started

Core Concepts

Architecture

Deployment

Operations

Client SDKs

​Installation

​Installation Options

Docker

Homebrew

From Source

​Docker Installation (Recommended)

​Prerequisites

​Quick Start with Docker Compose

​Docker Compose Variants

​Using Released Versions

​Homebrew Installation (macOS)

​Install Cadence Tools

​Install Database

​Install Database Schema

​Start Cadence Server

​Build from Source

​Prerequisites

​Build Cadence

​Development Setup

​Database Configuration

​Supported Databases

​Number of History Shards

​Advanced Visibility Setup

​Verification

​Next Steps

Quickstart

Configuration

Production Setup

Monitoring

​Troubleshooting

Build docs developers (and LLMs) love

Installation

Installation Options

Docker Installation (Recommended)

Prerequisites

Quick Start with Docker Compose

Docker Compose Variants

Using Released Versions

Homebrew Installation (macOS)

Install Cadence Tools

Install Database

Install Database Schema

Start Cadence Server

Build from Source

Prerequisites

Build Cadence

Development Setup

Database Configuration

Supported Databases

Number of History Shards

Advanced Visibility Setup

Verification

Next Steps

Troubleshooting