Cadence is a distributed, scalable, durable, and highly available orchestration engine we developed at Uber Engineering to execute asynchronous long-running business logic in a scalable and resilient way.

This web UI is used to view workflows from Cadence, see what's running, and explore and debug workflow executions.

The latest version of cadence-web is included in the cadence composed docker containers in the main Cadence repository. Follow the instructions there to get started.

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

Set these environment variables if you need to change their defaults.

Note: To connect cadence-web to multiple clusters, you will need to add comma-delimted entries for CADENCE_GRPC_PEERS, CADENCE_GRPC_SERVICES_NAMES & CADENCE_CLUSTERS_NAMES for each cluster (each cluster values are grouped by their index within the Comma-delimited lists).

Example:

CADENCE_GRPC_PEERS=127.0.0.1:3000,127.0.0.1:5000 
CADENCE_GRPC_SERVICES_NAMES=cadence-frontend-cluster0,cadence-frontend-cluster1
CADENCE_CLUSTERS_NAMES=cluster0,cluster1

Feature flags control various UI features and functionality in cadence-web. These can be configured using environment variables.

Note: For advanced customization, feature flags can be modified through resolvers in the dynamic config system (src/config/dynamic/resolvers).

You can run cadence-web with secure gRPC TLS communication by passing your CA certificate file to the container and configure the environment variable accordingly.

1. Prepare your CA certificate file:
   Ensure you have the root CA file (e.g., ca.pem) accessible on your host machine.

2. Mount the certificate file into the container:
   Use Docker volume mounting (-v or --volume) to make the certificate file available inside the container at a known path.

3. Set the CADENCE_GRPC_TLS_CA_FILE environment variable to the mounted certificate path:

Example command (for Linux):

docker run -it --rm \
  -p 8088:8088  \
  -v /path/on/host/ca.pem:/etc/certs/ca.pem:ro \
  -e CADENCE_GRPC_TLS_CA_FILE=/etc/certs/ca.pem \
  ubercadence/server:master-auto-setup

• Replace /path/on/host/ca.pem with the actual location of your CA certificate on the host system.
• CADENCE_GRPC_TLS_CA_FILE must point to the path inside the container where the certificate is mounted.

cadence-web requires node v18 or greater to be able to run correctly.

To create a production build, follow these steps:

1. Install npm packages and download idls

npm install && npm run install-idl && npm run generate:idl

2. Build the project files

npm run build

3. After building the code, start the server by running this command from the same directory as the build

npm start

4. Once the webapp is ready, access it through localhost:8088 (port can be changed using CADENCE_WEB_PORT environment variable)

To run the development server, follow these steps:

1. Install npm packages and download idls

npm install && npm run install-idl && npm run generate:idl

2. Run the development server using

npm run dev

3. Once the webapp is ready, access it through localhost:8088 (port can be changed using CADENCE_WEB_PORT environment variable)

Note: For contribution we recommend using dev containers, check VSCode Dev Containers for more information

1. Set up the Remote Containers plugin in VSCode.
2. Open the cadence-web directory in VSCode.
3. Make sure to update CADENCE_GRPC_PEERS with the correct host. (If you are connecting to a server on a container host machine use host.docker.internal:7833, where 7833 is the gRPC port for a running cadence-frontend service)
4. Use the Command Palette to select the 'Reopen folder in Container' option
5. Follow the same commands listed in Running development environment.

To start development against dockerized cadence services, run the following command from the root of the project

docker-compose -f docker-compose-backend-services.yml up

You can customize the YAML file or reuse configurations from the cadence repository. (In case of reusing existing files: ensure that cadence-web is not included in the composed container services, or just remove it)

After running cadence, start cadence-web for development using one of the previous methods (Running development environment, VSCode Dev Containers)

To update the Cadence IDL files:

1. Update the commit hash in package.json under config.cadence_idl_version to the latest commit hash from the cadence-idl repository.

2. Download the new IDL files:

npm run install-idl

3. Generate TypeScript types from the IDL files:

npm run generate:idl

4. Check for errors:

npm run lint && npm run typecheck && npm run test

5. Run cadence-web locally to sanity-check if everything works as expected (see Running development environment)

6. Fix any errors that arise from the updated IDL files.

We'd love your help in making the Cadence Web UI great. Please review our contribution guidelines.

If you'd like to propose a new feature or discuss issues, join the CNCF Slack workspace in the #cadence-users channel to start a discussion.

Apache 2.0 License, please see LICENSE for details.