Cello: provisioning Hyperledger Fabric networks as a service

A management plane for chains rather than a ledger

Hyperledger Cello describes itself as a blockchain provision and operation system that helps manage blockchain networks in an efficient way. The project lives under the Hyperledger umbrella, with documentation at the Hyperledger wiki and the repository under the hyperledger-cello organisation.

The list of what Cello is for is worth reading closely, because it defines the boundary. You can build up a Blockchain as a Service platform quickly from scratch. You can provision customizable blockchains instantly, for example a Hyperledger Fabric network v1.0. You can maintain a pool of running blockchain networks on top of baremetals, virtual clouds such as virtual machines and vSphere clouds, and container clusters such as Docker, Swarm and Kubernetes. And you can check system status, adjust the chain numbers and scale resources through dashboards.

That list describes a control plane. Cello does not implement consensus, does not execute transactions and does not provide a ledger of its own. It creates, starts, stops and monitors networks built from an actual blockchain implementation, in this case Fabric. The phrase blockchain as a service platform is the giveaway: the deliverable is a platform that other teams consume networks from.

The audience follows from that. If you run one Fabric network for one internal project, Cello is a lot of machinery for the job. If you are the platform team serving twenty business units that each want their own network with their own peers, ordering channels and their own configuration, then a self service dashboard and a pool are exactly what you need, and the alternative is writing that provisioning tooling yourself.

The local run is four containers and a Makefile target

The quick start is unusually concrete, and the whole system comes up as a set of containers managed through Make targets.

The prerequisites are Docker, Docker Compose V2, make, Node.js and, optionally, Kubernetes. The documentation notes the project switched to Docker Compose V2 and links the change. The comment in the setup notes says the all script for Cello service management is written in the Makefile.

The first step is to set a storage path through an environment variable, using the current directory in the example.

$  export CELLO_STORAGE_PATH=$(pwd)/cello

Then the service starts with a single target.

$ make local

That command builds the required local images and starts the dashboard, the API engine, a PostgreSQL database and the Fabric agent. The container listing in the documentation shows what that means in practice: cello/hyperledger-fabric-agent:local running a python manage.py command and exposing 8080, postgres:16.14 exposing 5432, cello/api-engine:latest exposing 8080, and cello/dashboard:latest exposing 8081.

So the four moving parts are the dashboard, the API engine, the database and the agent that talks to Fabric. Everything else is configuration.

The dashboard is reached at localhost:8081, and when you register an organisation from the dashboard you supply the agent URL, which in the docker compose setup is an internal service name rather than a localhost address:

http://cello-docker-agent:8080/api/v1/

That detail trips people up, because the browser on your laptop cannot resolve cello-docker-agent. The URL is used by the Cello components talking to each other inside the compose network, so it has to match the service naming in the compose file rather than what you would type into a browser.

The Makefile is the real interface, and it lists the whole lifecycle

The Makefile is documented at the top of the file itself, with a comment listing the available targets, and one of the useful things about it is that the list is a description of the operational model.

The documented targets are all, clean, check, deep-clean, doc, docker and docker-clean, docker-compose, help, license, local, reset, restart, setup-master, setup-worker, start and stop. Each has a one line description in the file.

Reading them tells you how the system is meant to be operated. The local target runs all services ad hoc. The start and stop targets manage the Cello service as a deployed set of containers. The reset target cleans and removes local storage and is flagged for development use only. The check target sets up the host as a master node and runs all the tests and checks, and is described as the target triggered by CI. The setup-master and setup-worker targets install packages and download Docker images, so a host can be enrolled as a master or a worker node. The doc target starts a local web service for exploring the documentation. The license target checks source files for the Apache license header, which is a nice detail about how the project keeps its headers consistent.

There is a Makefile.old in the repository root alongside the current one, which tells you the tooling has been reorganised at some point, and a .makerc directory for editor configuration.

The daily commands are short. Stopping the service, cleaning up all containers, and listing the available rules are each one line.

$ make stop
$ make clean
$ make help

If you want to start from a clean local environment, make local-reset removes the local data volume and restarts all services.

The PostgreSQL 12 to 16 upgrade is the sharpest documentation in the repository

The setup notes carry a section on migrating PostgreSQL 12 to 16, and it is the most detailed operational content in the repository, which tells you something about where the real friction is.

The important warning first: PostgreSQL major version data directories cannot be directly reused between PG12 and PG16 due to internal storage format changes. The guidance is to preserve the existing PG12 data directory or Docker volume so rollback remains possible, create a separate PG16 volume rather than overwriting the old storage, take a full backup of all databases and globals with pg_dumpall, check the extensions the application uses and verify psycopg2-binary compatibility, and validate the restored database before removing the old data.

The documented sequence for a docker compose dev setup using the named volume cello-postgres is a set of concrete commands: dump the databases and globals with pg_dumpall into a file, bring the environment down with docker compose -f docker-compose.dev.yaml down, create a backup volume and copy the old volume contents into it with a helper alpine container, remove the original volume, bring up the new PG16 container, restore the dump with psql, and finally bring up all development services.

docker exec -t cello-postgres pg_dumpall -U postgres > cello_pg12_backup.sql
docker compose -f docker-compose.dev.yaml down
docker volume rm cello-postgres
docker compose -f docker-compose.dev.yaml up -d cello-postgres
docker exec -i cello-postgres psql -U postgres < cello_pg12_backup.sql
docker compose -f docker-compose.dev.yaml up -d

For a deployment using the host path /opt/cello/pgdata, which is the ${CELLO_STORAGE_PATH:-/opt/cello}/pgdata form used by several compose files, the steps differ. The old directory is moved aside rather than copied, with sudo mv /opt/cello/pgdata /opt/cello/pgdata_v12_backup followed by creating a fresh directory with mkdir -p, and the compose files involved are bootup/docker-compose-files/docker-compose.dev.yml, docker-compose.server.dev.yml or docker-compose-dev.yml.

That the database is pinned at postgres:16.14 in the current compose output, while the migration notes still describe moving from PG12, is the clearest signal of the project's vintage and its operational debt.

Kubernetes and multi-node deployment live in bootup and kconfig

Beyond the local docker compose path, the repository contains the pieces for a real deployment, and they are visible in the top level layout.

There is a bootup/ directory holding docker compose files, including the server variants referenced in the PostgreSQL migration section. There is a Kconfig file and a kconfig-lib/ directory, which indicates configuration handled through the Kconfig system rather than through ad hoc environment variables alone, and that pairs with the CELLO_STORAGE_PATH style variables for the paths that still use the environment.

The docker-compose.dev.yaml file sits at the repository root, and the Makefile targets setup-master and setup-worker describe enrolling a host as a master or a worker node, installing packages and pulling images. That is a multi-node arrangement rather than a single host, which fits with the stated ability to maintain a pool of networks across baremetals, virtual clouds and container clusters.

The documentation tree is organised with mkdocs.yml at the root, a docs/ directory and a readthedocs configuration in .readthedocs.yml, plus release_notes/ for the release history and a CHANGELOG.md. There is a docs/setup/server.md with a troubleshoot section that the quick start points to for anyone who hits a problem.

The governance and tooling files are also conventional for a Hyperledger project: CODEOWNERS, MAINTAINERS.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, a pre-commit configuration, and a repolint.json for repository linting. The presence of a Kconfig, a repolint configuration and a code owners file is a reasonable signal about how seriously the project treats its own repository conventions.

A pool of networks needs an inventory, and that is Cello's real job

It is easy to read Cello as a set of docker compose files with a UI on top, and to ask what the dashboard adds. The answer lies in the third bullet of the feature list: maintaining a pool of running blockchain networks on top of different substrates.

A pool implies inventory. Networks have identities, owners, organisations, peers, ordering services, channels and configuration, and all of that has to be recorded somewhere. Once the pool is bigger than a handful of networks, the questions become operational: what is running, what is unhealthy, how many chains exist for a given project, how much resource is each consuming, and can a new organisation be enrolled without an operator editing YAML by hand on three hosts.

Cello's answer is the agent plus the API engine. The dashboard is only the human-facing half; the Fabric agent is the half that actually talks to a Fabric network, and the API engine is the half that coordinates. An organisation registration in the dashboard goes through the agent URL, which is what makes it possible to onboard an organisation into a running chain from a browser form rather than by hand editing connection profiles.

That is also where the honest limitation lies. Cello manages the lifecycle of networks built on a ledger implementation, and the Fabric agent is the part that knows how to do that for Fabric. The feature list names Fabric v1.0 as the example of a customizable blockchain to provision, and the repository topics are blockchain, distributed-ledger, hyperledger and operating-system. Adding a different ledger means adding a different agent, and the amount of work in that is not small.

There is also a scale question that the documentation does not answer. Nothing here describes how the pool scales, what the limits are on the number of networks a single Cello deployment can hold, or how the platform handles a network that fails partially. For a platform team, that is the first question to answer before committing.

Licence, project status and the wiki as the real documentation

The licence field on the repository says Apache-2.0, and the Makefile header confirms the same with an SPDX-License-Identifier: Apache-2.0 marker and an IBM Corp copyright line. That is a permissive licence with an explicit patent grant, which is the conventional choice for enterprise blockchain tooling. This is not legal advice, but the terms are standard and the project also ships a license header check target, so the licensing is enforced rather than aspirational.

Release history shows steady but not fast progress. v1.1.0-rc was tagged on 2024-12-27, v1.1.0 on 2025-07-15 and v1.2.0 on 2025-10-22, and the last push was on 2026-10-22. So there is a version 1.2 line and the tree is still being worked on, roughly a year after that tag.

The repository carries a README whose table of contents lists sections the visible text does not cover, including Main Features, Documentation with a getting started and develop guideline, a section on why the project is named cello, and an incubation notice. The incubation notice is worth noting: Hyperledger projects at that stage carry a specific status, and the presence of that entry in the table of contents means the project page says something about its maturity that the short readme does not.

Documentation is split across three places. The README covers the quick start and the database migration. The docs/ directory and mkdocs.yml cover the development documentation. And the project homepage points at the Hyperledger wiki, which suggests the substantive user and operator documentation lives in the wiki rather than the repository. The repository also has an inclusive language statement, which is a standard requirement for Hyperledger projects.

If you are evaluating this, the wiki is the document to read, and the version history in release_notes/ is the document that tells you how fast the interface moves.

Editorial conclusion

Cello suits a platform or operations team that needs to hand out blockchain networks to many internal users, because the dashboard, the agent and the network pool exist for that job rather than for running a single chain. It does not suit a team that only needs one Fabric network, since a plain docker compose file for Fabric is less machinery for that, and it is not a chain framework itself, so it does not replace Fabric, Hyperledger Besu or any other ledger. Before adopting it, read the PostgreSQL migration section for your storage layout, since the documented upgrade paths differ between the named volume and the host path deployments, and check the agent URL your dashboard registers, because that value has to match how the containers resolve each other.

Frequently asked questions

Official sources

1. hyperledger-cello/cello on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases