Skip to content

Building

Hyperledger Cacti Build Instructions

This is the place to start if you want to give Cactus a spin on your local machine or if you are planning on contributing.

This is not a guide for using Cactus for your projects that have business logic but rather a guide for people who want to make changes to the code of Cactus. If you are just planning on using Cactus as an npm dependency for your project, then you might not need this guide at all.

The project uses Typescript for both back-end and front-end components.

Fast Developer Flow / Code Iterations

We put a lot of thought and effort into making sure that fast developer iterations can be achieved (please file a bug if you feel otherwise) while working on the framework.

If you find yourself waiting too much for builds to finish, most of the time that can be helped by using the npm run watch script which can automatically recompile packages as you modify them (and only the packages that you have modified, not everything).

It also supports re-running the OpenAPI generator when you update any openapi.json spec files that we use to describe our endpoints.

The npm run watch script in action:

Fast Developer Flow / Code Iterations

Getting Started

A Dev Container is a pre-configured Docker-based development environment that automatically installs all required tools (Node.js, Yarn, Go, Rust, etc.). This avoids manual setup and ensures consistency across contributors.

Prerequisites

Before starting, install:

Step-by-Step Setup

1. Clone the repository 

git clone https://github.com/hyperledger-cacti/cacti.git
cd cacti
code .

2. Open in Dev Container

Once VS Code opens: * Look for popup: “Reopen in Container” * Click it

If popup does not appear: * Press Cmd + Shift + P (Mac) or Ctrl + Shift + P (Windows/Linux) * Search: Dev Containers: Reopen in Container * Press Enter

3. Wait for setup

VS Code will: * Build Docker container * Install dependencies

This may take several minutes.

Known Issue (Important for New Contributors)

During testing, the DevContainer setup may fail due to a Go version mismatch: * Current container installs Go 1.20.x * Some dependencies require Go ≥ 1.23

This can cause container build failure.

Workaround

If DevContainer fails, run the project locally instead: 

npm install -g yarn
yarn install

Tip: If you're new to open source, running locally is often faster and simpler than debugging container issues.

Nix Flake Quickstart

If you have Nix installed with flakes enabled, you can set up a complete, reproducible development environment with a single command. Nix provides the exact versions of Node.js, Go, Rust, JDK, Protobuf, and all other required toolchains, no manual installation necessary.

Prerequisites

  • Nix with flakes enabled
  • Docker (daemon must be running on the host for integration tests)

Note: If you are new to Nix, see the detailed Nix Setup Guide for installation and configuration instructions.

Step-by-Step Setup

1. Clone the repository 

git clone https://github.com/hyperledger-cacti/cacti.git
cd cacti

2. Enter the development shell 

nix develop

The first run downloads and caches all dependencies (a few minutes). Subsequent runs are near-instantaneous.

3. Build the project 

yarn run configure

Tip: If you only work on TypeScript packages and do not need Go, Rust, or Java, use the lighter Node-only shell instead: nix develop .#node

MacOS

Unless explicitly stated otherwise, each bullet will apply to both Intel and ARM Macs. In bullets where there is a difference in the installation process it will be noted. * Git * https://github.com/git-guides/install-git#install-git-on-mac * NodeJS v20.20.0, npm v10.8.2 (we recommend using the Node Version Manager (nvm) if available for your OS) * Download nvm using script * See the Section "Macs with Apple Silicon Chips" under macOS Troubleshooting for ARM Mac specific instructions * Download nvm using homebrew * Using nvm install and use specific version of node: 

nvm install 20.20.0
nvm use 20.20.0
* Yarn * npm run enable-corepack (from within the project directory) * Docker Engine is available on Mac OS through Docker Engine. * See the difference in system requirements for Docker Desktop for Intel and ARM Macs under System Requirements on the page above. * Docker Compose * Installing Docker Desktop on Mac will include Docker Compose * OpenJDK (Corda support Java 8 JDK but do not currently support Java 9 or higher) * Follow instructions for Mac here * Go * Installing Go for Mac * Under featured downloads on the page above choose between the ARM64 or x86-64 option based on your machine. * Adding Environment Variable and Go extensions * Foundry (required for SATP Hermes smart contract compilation) * Install Foundry: 
curl -L https://foundry.paradigm.xyz | bash
* Restart your terminal or run source ~/.zshrc, then: 
foundryup
* Verify installation: 
forge --version

Linux

Tested on Ubuntu 22.04 LTS

  • Base prerequisites (install these first, they're used by later curl-based installers)
  • sudo apt-get update && sudo apt-get install -y git curl ca-certificates build-essential python3
  • NodeJS v20.20.0, npm v10.8.2 (we recommend using the Node Version Manager (nvm))
  • Install nvm: 
    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc
  • Install and use the required Node version: 
    nvm install 20.20.0
nvm use 20.20.0
  • Yarn
  • npm run enable-corepack (from within the project directory)
  • Docker Engine
  • Post-install — allow running without sudo: 
    sudo usermod -aG docker $USER
newgrp docker
  • Docker Compose
  • Included with Docker Engine on modern installations. Verify with: 
    docker compose version
  • OpenJDK (Corda support requires Java 8 JDK)
  • sudo apt-get install -y openjdk-8-jdk
  • Note: openjdk-8-jdk is not available from the default Ubuntu 24.04 repositories. On 24.04 you'll need a supported external distribution (e.g. Temurin 8 from Adoptium) — see Adoptium install guide.
  • Go (requires Go >= 1.20; parts of this repo such as weaver/common/protos-go will fail to build with older toolchains)
  • We recommend installing from the official Go downloads page: go.dev/dl. The golang-go package on Ubuntu 22.04 ships an older toolchain (1.18) and is not sufficient on its own.
  • Foundry (required for SATP Hermes smart contract compilation)
  • Install Foundry: 
    curl -L https://foundry.paradigm.xyz | bash
source ~/.bashrc
foundryup
  • Verify installation: 
    forge --version

Windows

We recommend using WSL2 (Windows Subsystem for Linux) with Ubuntu 22.04.

  • Install WSL2
  • Open PowerShell as Administrator: 
    wsl --install -d Ubuntu-22.04

  • Restart your machine, then open Ubuntu from the Start menu

  • Docker Desktop for Windows

  • Enable WSL2 integration: Docker Desktop → Settings → Resources → WSL Integration

  • If you encounter socket permission errors inside WSL2, add your user to the docker group instead of loosening the socket permissions (do not chmod 666 /var/run/docker.sock — that grants root-equivalent access to any local process): 

    sudo usermod -aG docker $USER
newgrp docker

  • Then follow the Linux instructions above inside your WSL2 terminal

Random Windows specific issues not covered here

We recommend that you use WSL2 or any Linux VM (or bare metal). We test most frequently on Ubuntu 22.04 LTS

Configure Cacti

  • Clone the repository
git clone https://github.com/hyperledger-cacti/cacti.git

Windows specific gotcha: File paths too long error when cloning. To fix: Open PowerShell with administrative rights and then run the following:

git config --system core.longpaths true
  • Change directories to the project root
cd cacti
  • Run this command to enable corepack (Corepack is included by default with all Node.js installs, but is currently opt-in.)
npm run enable-corepack
  • Run the initial configuration script (can take a long time, 10+ minutes on a low-spec laptop)
yarn run configure

At this point you should have all packages built for development.

You can start making your changes (use your own fork and a feature branch) or just run existing tests and debug them to see how things fit together.

For example you can run a ledger single status endpoint test via the REST API with this command:

npx tap --ts --timeout=600 packages/cactus-test-plugin-htlc-eth-besu/src/test/typescript/integration/plugin-htlc-eth-besu/get-single-status-endpoint.test.ts

You can also start the API server and verify more complex scenarios with an arbitrary list of plugins loaded into Cactus. This is useful for when you intend to develop your plugin either as a Cactus maintained plugin or one on your own.

npm run generate-api-server-config

Notice how this task created a .config.json file in the project root with an example configuration that can be used a good starting point for you to make changes to it specific to your needs or wants.

The most interesting part of the .config.json file is the plugins array which takes a list of plugin package names and their options (which can be anything that you can fit into a generic JSON object).

Notice that to include a plugin, all you need is specify it's npm package name. This is important since it allows you to have your own plugins in their respective, independent Github repositories and npm packages where you do not have to seek explicit approval from the Cactus maintainers to create/maintain your plugin at all.

Once you are satisfied with the .config.json file's contents you can just:

npm run start:api-server

After starting the API server, you will see in the logs that plugins were loaded and that the API is reachable on the port you specified (4000 by default). The Web UI (Cockpit) is disabled by default but can be enabled by changing the property value 'cockpitEnabled' to true and it is reachable through port on the port your config specified (3000 by default).

You may need to enable manually the CORS patterns in the configuration file. This may be slightly inconvenient, but something we are unable to compromise on despite valuing developer experience very much. We have decided that the software should be secure by default above all else and allow for customization/degradation of security as an opt-in feature rather than starting from that state.

At this point, with the running API server, you can * Test the REST API directly with tools like cURL or Postman * Develop your own applications against it with the Cactus API Client(s) * Create and test your own plugins

Build Script Decision Tree

The npm run watch script should cover 99% of the cases when it comes to working on Cactus code and having it recompile, but for that last 1% you'll need to get your hands dirty with the rest of the build scripts. Usually this is only needed when you are adding new dependencies (npm packages) as part of something that you are implementing.

There are a lot of different build scripts in Cactus in order to provide contributors fine® grained control over what parts of the framework they wish build.

Q: Why the complexity of so many build scripts?

A: We could just keep it simple with a single build script that builds everything always, but that would be a nightmare to wait for after having changed a single line of code for example.

To figure out which script could work for rebuilding Cactus, please follow the following decision tree (and keep in mind that we have npm run watch too)

Build Script Decision Tree

Running CI Checks Locally Before Pushing

Before opening a pull request, you should run the same checks that CI will run. This helps catch issues early and speeds up the review process.

Quick Checklist

# 1. Build the project
yarn run configure

# 2. Run linting
yarn run lint

# 3. Run all tests (unit + integration)
yarn run test:jest:all

# 4. Run the full CI script (Linux/macOS/WSL only)
./tools/ci.sh

Individual Steps

Check Command Notes
TypeScript compilation yarn tsc Compiles all packages
ESLint yarn run format:eslint Lints JS/TS files
Prettier yarn run format:prettier Formats code
Spell check yarn run spellcheck Checks spelling in source
Jest tests yarn run test:jest:all Runs all Jest test suites
Single test file yarn jest path/to/test.test.ts Run one specific test

Docker Tests

Some integration tests require Docker. Ensure Docker is running before executing:

# Build all-in-one ledger images (if needed)
cd tools/docker/<ledger>-all-in-one
docker build -t <image-name> .

# Then run the integration tests that depend on Docker
yarn jest --testPathPattern=integration

Tip: If you are only modifying documentation or configuration files, you can skip the Docker tests. CI will run them automatically on your PR.

Configuring SSH to use upterm

Upload your public key onto github if not done so already. A public key is necessary to join the ssh connection to use upterm. For a comprehensive guide, see the Generating a new SSH key and adding it to the ssh-agent.

Locate the ci.yml within .github/workflows and add to the ci.yml code listed below: - name: Setup upterm session uses: lhotari/action-upterm@v1 with: repo-token: ${{ secrets.GITHUB_TOKEN }}

Keep in mind that the SSH upterm session should come after the checkout step (uses: actions/checkout@v4.1.1) to ensure that the CI doesn't hang without before the debugging step occurs. Editing the ci.yml will create a new upterm session within .github/workflows by adding a new build step. For more details, see the Debug with SSH action.

By creating a PR for the edited ci.yml file, this will allow the CI to run their tests. There are two ways to navigate to CIs. 1) Go to the PR and click the checks tab 2) Go to the Actions tab within the main Hyperledger Cactus Repository

Click on the CI Cactus workflow. There should be a new job you've created be listed underneath the build (ubuntu-22.04) jobs. Click on the the new job (what's you've named your build) and locate the SSH Session within the Setup Upterm Session dropdown. Copy the SSH command that start with ssh and ends in .dev (ex. ssh **********:***********@uptermd.upterm.dev). Open your OS and paste the SSH command script in order to begin an upterm session.

Previous Next