From 0670af062cd8c08f9e7694e6483a69ea30fadcec Mon Sep 17 00:00:00 2001 From: dodo920306 Date: Mon, 4 Aug 2025 11:20:33 +0000 Subject: [PATCH 01/24] Create introduction and prerequisites lessons Signed-off-by: dodo920306 --- docs/tutorials/introduction.md | 9 +++++++++ docs/tutorials/prerequisites.md | 29 +++++++++++++++++++++++++++++ mkdocs.yml | 3 +++ 3 files changed, 41 insertions(+) create mode 100644 docs/tutorials/introduction.md create mode 100644 docs/tutorials/prerequisites.md diff --git a/docs/tutorials/introduction.md b/docs/tutorials/introduction.md new file mode 100644 index 00000000..247d84d7 --- /dev/null +++ b/docs/tutorials/introduction.md @@ -0,0 +1,9 @@ +# Lesson 0: Introduction + +*Creating a Hyperledger Fabric network is never an easy thing, and Hyperledger Cello has made it simpler.* + +Welcome to the *Hyperledger Cello* tutorials. In the following lessons, you will learn about how you can set up a *Hyperledger Cello* server and agent and use them to create a *Hyperledger Fabric* network with ease. + +The whole series is done using a *Ubuntu 22.04* computer, but it should be able to work on any *UNIX-like* operating system. If you encounter any problem trying to follow the tutorials, feel free to open an issue on our [*GitHub*](https://github.com/hyperledger-cello/cello/issues) page, or better, open a PR to solve it. For more infomation, please refer to the [*Contributing*](../contributing.md) page. + +Let's get started! diff --git a/docs/tutorials/prerequisites.md b/docs/tutorials/prerequisites.md new file mode 100644 index 00000000..27c4876a --- /dev/null +++ b/docs/tutorials/prerequisites.md @@ -0,0 +1,29 @@ +# Lesson 1: Prerequisites + +## Knowledger Base + +Before we get into this tutorial, though not necessary, it would be better if you have a basic understanding of *Hyperledger Fabric*. You can get more information about it by checking out the [*Key Concepts*](https://hyperledger-fabric.readthedocs.io/en/latest/key_concepts.html). + +You should also have read the [*Concept*](../concepts.md) page, but still, we'll briefly revisit key ideas as they come up. + +## Environment + +To set up the environment for the following lessons, make sure you have these 3 tools installed on your computer: + +1. [*git*](https://git-scm.com/downloads) +2. [*make*](https://www.gnu.org/software/make) +3. [*docker*](https://docs.docker.com/get-started/get-docker) + +So far, no compatibility issues have been reported with the versions of these tools. However, if you encounter any problems, feel free to let us know via the [*GitHub*](https://github.com/hyperledger-cello/cello) page. + +Now, navigate to the directory where you want to place the project and run: +```bash +$ git clone https://github.com/hyperledger-cello/cello +``` + +If the command runs successfully, switch into the project directory: +```bash +$ cd cello +``` + +That's it for this lesson. See you in the next one! diff --git a/mkdocs.yml b/mkdocs.yml index 88bfd7c6..5989794b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -41,6 +41,9 @@ nav: - Architecture: design/arch.md - Setup: - Server: setup/server.md + - Tutorials: + - "Lesson 0: Introduction": tutorials/introduction.md + - "Lesson 1: Prerequisites": tutorials/prerequisites.md - Agent: - Kubernetes: agents/kubernetes.md - Fabric operator: agents/fabric-operator.md From 63b4852a467ef38260924c0b91ec89526794f98f Mon Sep 17 00:00:00 2001 From: dodo920306 Date: Mon, 4 Aug 2025 11:33:18 +0000 Subject: [PATCH 02/24] Add dark mode Signed-off-by: dodo920306 --- mkdocs.yml | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index 5989794b..152966c6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -8,8 +8,18 @@ theme: feature: tabs: true palette: - primary: "light-blue" - accent: "light-blue" + - scheme: default + toggle: + icon: material/brightness-7 + name: Switch to dark mode + primary: "light-blue" + accent: "light-blue" + - scheme: slate + toggle: + icon: material/brightness-4 + name: Switch to light mode + primary: "light-blue" + accent: "light-blue" font: text: "Ubuntu" code: "Ubuntu Mono" From 8361d3aece68acf66d615a982172e3dfe745ca08 Mon Sep 17 00:00:00 2001 From: dodo920306 Date: Mon, 4 Aug 2025 11:50:06 +0000 Subject: [PATCH 03/24] Add navigation tabs Signed-off-by: dodo920306 --- docs/concepts.md | 5 +++++ docs/contributing.md | 5 +++++ docs/faq.md | 2 -- docs/index.md | 5 +++++ mkdocs.yml | 53 ++++++++++++++++++++++---------------------- 5 files changed, 41 insertions(+), 29 deletions(-) diff --git a/docs/concepts.md b/docs/concepts.md index 0f954346..250b612d 100644 --- a/docs/concepts.md +++ b/docs/concepts.md @@ -1,3 +1,8 @@ +--- +hide: + - navigation +--- + hero: All concepts related to cello # Concepts diff --git a/docs/contributing.md b/docs/contributing.md index 9561fafc..574db7cd 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,3 +1,8 @@ +--- +hide: + - navigation +--- + [//]: # (SPDX-License-Identifier: CC-BY-4.0) ## Introduction diff --git a/docs/faq.md b/docs/faq.md index ea8edb80..f409cf81 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -1,7 +1,5 @@ ## Questions -* [What is cello?](#what-is-cello) - ### What is cello? Hyperledger Cello is a blockchain provision and operation system, which helps manage blockchain networks in an efficient way. diff --git a/docs/index.md b/docs/index.md index 2b9df2c9..a5a94515 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,3 +1,8 @@ +--- +hide: + - navigation +--- + Welcome to Hyperledger Cello === diff --git a/mkdocs.yml b/mkdocs.yml index 152966c6..db9ade5b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -5,8 +5,8 @@ theme: name: "material" logo: "images/favicon.png" favicon: "images/favicon.png" - feature: - tabs: true + features: + - navigation.tabs palette: - scheme: default toggle: @@ -44,31 +44,30 @@ markdown_extensions: mode: view docs_dir: docs nav: - - Docs: - - Overview: index.md - - Concepts: concepts.md - - Design: - - Architecture: design/arch.md - - Setup: - - Server: setup/server.md - - Tutorials: - - "Lesson 0: Introduction": tutorials/introduction.md - - "Lesson 1: Prerequisites": tutorials/prerequisites.md - - Agent: - - Kubernetes: agents/kubernetes.md - - Fabric operator: agents/fabric-operator.md - - Operations: - - Dashboard: - - Operator operations: operations/dashboard/operator.md - - Admin operations: operations/dashboard/admin.md - - User operations: operations/dashboard/user.md - - Reference: - - Configuration: - - Server Configuration: reference/configuration/server.md - - Commands: - - make: reference/commands/make.md - - cli: reference/commands/cli.md - - Contribute: contributing.md + - Home: index.md + - Concepts: concepts.md + - Design: + - Architecture: design/arch.md + - Setup: + - Server: setup/server.md + - Tutorials: + - "Lesson 0: Introduction": tutorials/introduction.md + - "Lesson 1: Prerequisites": tutorials/prerequisites.md + - Agent: + - Kubernetes: agents/kubernetes.md + - Fabric operator: agents/fabric-operator.md + - Operations: + - Dashboard: + - Operator operations: operations/dashboard/operator.md + - Admin operations: operations/dashboard/admin.md + - User operations: operations/dashboard/user.md + - Reference: + - Configuration: + - Server Configuration: reference/configuration/server.md + - Commands: + - make: reference/commands/make.md + - cli: reference/commands/cli.md + - Contribute: contributing.md - FAQ: - faq.md - Release Notes: From d1c268dfe16f267148943425133b06bcb2072a54 Mon Sep 17 00:00:00 2001 From: dodo920306 Date: Mon, 4 Aug 2025 11:54:57 +0000 Subject: [PATCH 04/24] Add logo into README and homepage Signed-off-by: dodo920306 --- README.md | 2 +- docs/images/logo.svg | 247 +++++++++++++++++++++++++++++++++++++++++++ docs/index.md | 4 +- 3 files changed, 251 insertions(+), 2 deletions(-) create mode 100644 docs/images/logo.svg diff --git a/README.md b/README.md index fe8c95fd..1a450102 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -![Cello](docs/images/favicon.png) +![Cello](docs/images/logo.svg) [![Release](https://img.shields.io/github/v/release/hyperledger-cello/cello)](https://github.com/hyperledger-cello/cello/releases) [![Build Status](https://github.com/hyperledger/cello/actions/workflows/docker-image.yml/badge.svg)](https://github.com/hyperledger/cello/actions/workflows/docker-image.yml) diff --git a/docs/images/logo.svg b/docs/images/logo.svg new file mode 100644 index 00000000..3efbde5d --- /dev/null +++ b/docs/images/logo.svg @@ -0,0 +1,247 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/index.md b/docs/index.md index a5a94515..bc2fb068 100644 --- a/docs/index.md +++ b/docs/index.md @@ -6,7 +6,7 @@ hide: Welcome to Hyperledger Cello === -![Typical Scenario](images/scenario.png) +![Logo](images/logo.svg) Hyperledger Cello (HLC) is a blockchain provision and operation system, which helps people use and manage blockchains in a more efficient way. @@ -24,6 +24,8 @@ Using Cello, blockchain developers can: * Check the system status and manage chains, upload smart contract and test... through dashboards. * Maintain a pool of running blockchain networks on top of bare-metals, virtual clouds (e.g., virtual machines, vsphere Clouds), container clusters (e.g., Docker, Swarm, Kubernetes). +![Typical Scenario](images/scenario.png) + ## [Getting Started](setup/server.md) **For beginners, it is highly recommended to read the [Setup](setup/server.md) first**. From 376f6c1193a4a33c19e0945ad38f556f9a376e99 Mon Sep 17 00:00:00 2001 From: dodo920306 Date: Mon, 4 Aug 2025 12:24:14 +0000 Subject: [PATCH 05/24] Create the server-only compose file Signed-off-by: dodo920306 --- Makefile | 3 +- .../docker-compose.server.dev.yml | 74 +++++++++++++++++++ 2 files changed, 76 insertions(+), 1 deletion(-) create mode 100644 bootup/docker-compose-files/docker-compose.server.dev.yml diff --git a/Makefile b/Makefile index 62395c60..1d71c888 100755 --- a/Makefile +++ b/Makefile @@ -223,7 +223,8 @@ fabric: dashboard: docker build -t hyperledger/cello-dashboard:latest -f build_image/docker/common/dashboard/Dockerfile.in ./ - +server: + docker compose -f bootup/docker-compose-files/docker-compose.server.dev.yml up -d --force-recreate --remove-orphans .PHONY: \ diff --git a/bootup/docker-compose-files/docker-compose.server.dev.yml b/bootup/docker-compose-files/docker-compose.server.dev.yml new file mode 100644 index 00000000..0a12e9cb --- /dev/null +++ b/bootup/docker-compose-files/docker-compose.server.dev.yml @@ -0,0 +1,74 @@ +# This compose file will deploy the services, and bootup a postgres server. + +# +# SPDX-License-Identifier: Apache-2.0 +# + +# cello-dashboard: dashboard service for cello +# cello-api-engine: api engine service of cello to provide RESTful APIs, listen on 8080 +# cello-postgres: postgres db + +version: '3.2' +services: + cello-dashboard: + image: hyperledger/cello-dashboard + container_name: cello-dashboard + ports: + - "${DASHBOARD_SERVICE_PORT}:8081" + networks: + - cello-net + depends_on: + - cello-api-engine + + # pg database + cello-postgres: + image: postgres:12.0 + container_name: cello-postgres + restart: unless-stopped + environment: + - POSTGRES_DB=api_engine + - POSTGRES_USER=postgres + - POSTGRES_PASSWORD=123456 + ports: + - "5432:5432" + volumes: + - ${CELLO_STORAGE_PATH:-/opt/cello}/pgdata:/var/lib/postgresql/data + networks: + - cello-net + + # api engine service of cello + cello-api-engine: + image: hyperledger/cello-api-engine + container_name: cello-api-engine + restart: unless-stopped + stdin_open: true + dns_search: . + environment: + - GODEBUG=netdns=go + - DB_NAME=api_engine + - DB_USER=postgres + - DB_PASSWORD=123456 + - DB_HOST=cello-postgres + - CELERY_BROKER_URL=redis://redis + - DB_PORT=5432 + - DEBUG=True + - CORE_VM_ENDPOINT=unix:///host/var/run/docker.sock + - FABRIC_LOGGING_SPEC=INFO + - API_ENGINE_ADMIN_EMAIL=admin@cello.com + ports: + - "8080:8080" + volumes: + - ${CELLO_STORAGE_PATH:-/opt/cello}:/opt/cello + networks: + - cello-net + depends_on: + - cello-postgres + +networks: + cello-net: + name: cello-net + +volumes: + cello-api-engine: + cello-postgres: + cello-dashboard: From 2277761273669fc5110e149f56cfa7ba5ebb8e9f Mon Sep 17 00:00:00 2001 From: dodo920306 Date: Mon, 4 Aug 2025 12:32:50 +0000 Subject: [PATCH 06/24] Add the 'back-to-top' button Signed-off-by: dodo920306 --- mkdocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/mkdocs.yml b/mkdocs.yml index db9ade5b..c45190b9 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -7,6 +7,7 @@ theme: favicon: "images/favicon.png" features: - navigation.tabs + - navigation.top palette: - scheme: default toggle: From 9346895a1768dccc91245e71a4ee94138bf845f1 Mon Sep 17 00:00:00 2001 From: dodo920306 Date: Mon, 4 Aug 2025 12:33:26 +0000 Subject: [PATCH 07/24] Allow local build docs can be access from the outside by default Signed-off-by: dodo920306 --- mkdocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/mkdocs.yml b/mkdocs.yml index c45190b9..e4ff5277 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,6 +1,7 @@ site_name: Hyperledger Cello repo_name: "hyperledger/cello" repo_url: "https://github.com/hyperledger/cello" +dev_addr: 0.0.0.0:8000 theme: name: "material" logo: "images/favicon.png" From 42546edaf0dd39deea6f27437de757343f9b5177 Mon Sep 17 00:00:00 2001 From: dodo920306 Date: Mon, 4 Aug 2025 12:34:25 +0000 Subject: [PATCH 08/24] Make 'docs' same as 'doc' to `make` commands Signed-off-by: dodo920306 --- Makefile | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Makefile b/Makefile index 1d71c888..7c6eb819 100755 --- a/Makefile +++ b/Makefile @@ -145,6 +145,9 @@ deep-clean: ##@Clean Stop services, clean docker images and remove mounted local make clean-images rm -rf $(LOCAL_STORAGE_PATH) +docs: + make doc + doc: ##@Documentation Build local online documentation and start serve command -v mkdocs >/dev/null 2>&1 || pip install -r docs/requirements.txt || pip3 -r docs/requirements.txt mkdocs serve -f mkdocs.yml @@ -231,6 +234,7 @@ server: all \ license \ check \ + docs \ doc \ help \ docker \ From eb6fc509a0f417ae5fc0941755fd639d5a3a41d0 Mon Sep 17 00:00:00 2001 From: dodo920306 Date: Mon, 4 Aug 2025 12:35:16 +0000 Subject: [PATCH 09/24] Add `make server` Signed-off-by: dodo920306 --- Makefile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Makefile b/Makefile index 7c6eb819..44c1d8a1 100755 --- a/Makefile +++ b/Makefile @@ -229,7 +229,6 @@ dashboard: server: docker compose -f bootup/docker-compose-files/docker-compose.server.dev.yml up -d --force-recreate --remove-orphans - .PHONY: \ all \ license \ @@ -253,4 +252,5 @@ server: clean-images \ start-docker-compose \ stop-docker-compose \ - images \ \ No newline at end of file + images \ + server\ From 7cb46c1effcb18a7154787b14c9cd9b3afbe45a3 Mon Sep 17 00:00:00 2001 From: dodo920306 Date: Mon, 4 Aug 2025 12:54:39 +0000 Subject: [PATCH 10/24] Update mermaid style Signed-off-by: dodo920306 --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index e4ff5277..c4c8b27d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -40,7 +40,7 @@ markdown_extensions: custom_fences: - name: mermaid class: mermaid - format: !!python/name:mermaid2.fence_mermaid + format: !!python/name:pymdownx.superfences.fence_code_format - pymdownx.mark - pymdownx.critic: mode: view From dcbc1b626a208d19e6ba253a4e77262a9d2241b9 Mon Sep 17 00:00:00 2001 From: dodo920306 Date: Mon, 4 Aug 2025 12:59:16 +0000 Subject: [PATCH 11/24] Add the 'copy-code' buttons Signed-off-by: dodo920306 --- mkdocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/mkdocs.yml b/mkdocs.yml index c4c8b27d..7ab285ea 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -9,6 +9,7 @@ theme: features: - navigation.tabs - navigation.top + - content.code.copy palette: - scheme: default toggle: From c73561f42e60e3f50e10e4c6c52065552b352e6d Mon Sep 17 00:00:00 2001 From: dodo920306 Date: Mon, 11 Aug 2025 12:59:49 +0000 Subject: [PATCH 12/24] Change the Ubuntu font to the "Sans" versions The "Sans" versions are easier on the eyes. Signed-off-by: dodo920306 --- mkdocs.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index 7ab285ea..09abecbf 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -24,8 +24,8 @@ theme: primary: "light-blue" accent: "light-blue" font: - text: "Ubuntu" - code: "Ubuntu Mono" + text: "Ubuntu Sans" + code: "Ubuntu Sans Mono" markdown_extensions: - admonition - codehilite From 33c94ee0cdcc8096a1ecf187164fd7adc65eec24 Mon Sep 17 00:00:00 2001 From: dodo920306 Date: Mon, 11 Aug 2025 13:00:25 +0000 Subject: [PATCH 13/24] Create tutorial lesson 3: server Signed-off-by: dodo920306 --- docs/tutorials/prerequisites.md | 6 ++-- docs/tutorials/server.md | 55 +++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 3 files changed, 60 insertions(+), 2 deletions(-) create mode 100644 docs/tutorials/server.md diff --git a/docs/tutorials/prerequisites.md b/docs/tutorials/prerequisites.md index 27c4876a..327759a3 100644 --- a/docs/tutorials/prerequisites.md +++ b/docs/tutorials/prerequisites.md @@ -14,16 +14,18 @@ To set up the environment for the following lessons, make sure you have these 3 2. [*make*](https://www.gnu.org/software/make) 3. [*docker*](https://docs.docker.com/get-started/get-docker) +All of them are usually available through package managers. + So far, no compatibility issues have been reported with the versions of these tools. However, if you encounter any problems, feel free to let us know via the [*GitHub*](https://github.com/hyperledger-cello/cello) page. Now, navigate to the directory where you want to place the project and run: ```bash -$ git clone https://github.com/hyperledger-cello/cello +git clone https://github.com/hyperledger-cello/cello ``` If the command runs successfully, switch into the project directory: ```bash -$ cd cello +cd cello ``` That's it for this lesson. See you in the next one! diff --git a/docs/tutorials/server.md b/docs/tutorials/server.md new file mode 100644 index 00000000..0001da79 --- /dev/null +++ b/docs/tutorials/server.md @@ -0,0 +1,55 @@ +# Lesson 2: Server + +By the end of this lesson, you'll be able to set up a *Hyperledger Cello* server on your computer. + +## Dashboard +First, we'll need a dashboard for our server, which is the UI for us. +To do that, we have to build its image first by running: + +```bash +make dashboard +``` + +The image will be tagged as `hyperledger/cello-dashboard:latest`. + +This step can take a while because it builds the `node_module` via `yarn install`. + +## Database +We'll directly use the official PostgreSQL image as our database, so there is no need to build another one. + +## API Engine +Next, we'll build the center of our *Hyperledger Cello* server, which is the *api engine*. + +```bash +make api-engine +``` + +The image will be tagged as `hyperledger/cello-api-engine:latest`. + +This step can take a while because it has to install all the dependencies needed for the engine. + +## Start the Server + +Finally, we can start the server by: + +```bash +make server +``` + +## Conclusion +That's it! You have successfully run a *Hyperledger Cello* server on your computer. + +In the next lesson, we'll talk about how you can run an agent for it. + +See you then! + +## P.S. The "Quickstart" Way +Alternatively, you can run +```bash +make local +``` + +to set up a *Hyperledger Cello* server and agent as quick as possible. + +However, in order to give you a deeper understanding of how everything works, +we instead walked through the entire setup step-by-step in this lesson above. diff --git a/mkdocs.yml b/mkdocs.yml index 09abecbf..756580f8 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -56,6 +56,7 @@ nav: - Tutorials: - "Lesson 0: Introduction": tutorials/introduction.md - "Lesson 1: Prerequisites": tutorials/prerequisites.md + - "Lesson 2: Server": tutorials/server.md - Agent: - Kubernetes: agents/kubernetes.md - Fabric operator: agents/fabric-operator.md From 9619c67d74bea2b291ca8ebe7b5f6c48be2cccd3 Mon Sep 17 00:00:00 2001 From: dodo920306 Date: Tue, 12 Aug 2025 11:46:00 +0000 Subject: [PATCH 14/24] Add `make agent` command to start a agent independently Signed-off-by: dodo920306 --- Makefile | 10 ++++--- .../docker-compose.agent.dev.yml | 27 +++++++++++++++++++ .../docker-compose.server.dev.yml | 7 ----- 3 files changed, 34 insertions(+), 10 deletions(-) create mode 100644 bootup/docker-compose-files/docker-compose.agent.dev.yml diff --git a/Makefile b/Makefile index 262442c4..cd178429 100755 --- a/Makefile +++ b/Makefile @@ -219,7 +219,7 @@ images: api-engine docker-rest-agent fabric dashboard api-engine: docker build -t hyperledger/cello-api-engine:latest -f build_image/docker/common/api-engine/Dockerfile.in ./ --platform linux/$(ARCH) - + docker-rest-agent: docker build -t hyperledger/cello-agent-docker:latest -f build_image/docker/agent/docker-rest-agent/Dockerfile.in ./ --build-arg pip=$(PIP) --platform linux/$(ARCH) @@ -232,13 +232,16 @@ dashboard: server: docker compose -f bootup/docker-compose-files/docker-compose.server.dev.yml up -d --force-recreate --remove-orphans +agent: + docker compose -f bootup/docker-compose-files/docker-compose.agent.dev.yml up -d --force-recreate --remove-orphans + .PHONY: \ all \ license \ check \ check-api \ check-dashboard \ - docs \ + docs \ doc \ help \ docker \ @@ -258,4 +261,5 @@ server: start-docker-compose \ stop-docker-compose \ images \ - server\ + server \ + agent diff --git a/bootup/docker-compose-files/docker-compose.agent.dev.yml b/bootup/docker-compose-files/docker-compose.agent.dev.yml new file mode 100644 index 00000000..22528fdf --- /dev/null +++ b/bootup/docker-compose-files/docker-compose.agent.dev.yml @@ -0,0 +1,27 @@ +# +# SPDX-License-Identifier: Apache-2.0 +# + +services: + cello-docker-agent: + image: hyperledger/cello-agent-docker + container_name: cello-docker-agent + hostname: cello.docker.agent + restart: always + ports: + - "2375:2375" + - "5001:5001" + volumes: + - /var/run/docker.sock:/var/run/docker.sock + environment: + - DOCKER_URL=unix://var/run/docker.sock + - STORAGE_PATH=${CELLO_STORAGE_PATH:-/opt/cello}/hyperledger + networks: + - cello-net + +networks: + cello-net: + name: cello-net + +volumes: + cello-docker-agent: diff --git a/bootup/docker-compose-files/docker-compose.server.dev.yml b/bootup/docker-compose-files/docker-compose.server.dev.yml index 0a12e9cb..ba37fcc8 100644 --- a/bootup/docker-compose-files/docker-compose.server.dev.yml +++ b/bootup/docker-compose-files/docker-compose.server.dev.yml @@ -1,14 +1,7 @@ -# This compose file will deploy the services, and bootup a postgres server. - # # SPDX-License-Identifier: Apache-2.0 # -# cello-dashboard: dashboard service for cello -# cello-api-engine: api engine service of cello to provide RESTful APIs, listen on 8080 -# cello-postgres: postgres db - -version: '3.2' services: cello-dashboard: image: hyperledger/cello-dashboard From 744c944bf151bf35ed00d3205011c407f49cf92c Mon Sep 17 00:00:00 2001 From: dodo920306 Date: Tue, 12 Aug 2025 12:10:25 +0000 Subject: [PATCH 15/24] Create lesson 3: agent Signed-off-by: dodo920306 --- docs/tutorials/agent.md | 51 ++++++++++++++++++++++++++++++++++++++++ docs/tutorials/server.md | 30 ++++++++++++++++++----- mkdocs.yml | 1 + 3 files changed, 76 insertions(+), 6 deletions(-) create mode 100644 docs/tutorials/agent.md diff --git a/docs/tutorials/agent.md b/docs/tutorials/agent.md new file mode 100644 index 00000000..8a0c7154 --- /dev/null +++ b/docs/tutorials/agent.md @@ -0,0 +1,51 @@ +# Lesson 3: Agent + +By the end of this lesson, you'll be able to set up a *Hyperledger Cello* agent on your computer. + +**Remember: You can totally follow this lesson on a different machine from where you follow the last lesson i.e.** +**The agents can be on a different machine from the server.** + +See also: [*Concepts*](../concepts.md). + +## Image +### Agent + +First, we have to build the image of the agent by running + +```bash +make docker-rest-agent +``` + +The image will be tagged as `hyperledger/cello-agent-docker:latest`. + +## Start the Agent + +Next, start the agent by running + +```bash +make agent +``` + +If nothing goes wrong, you should see a container named `cello-docker-agent` running on your computer by executing + +```bash +docker ps +``` + +## Conclustion +That's it! You have successfully run a *Hyperledger Cello* agent on your computer. + +In the next lesson, we'll talk about how you can create an organization and its first administrator. + +See you then! + +## P.S. The "Quickstart" Way +Alternatively, you can run +```bash +make local +``` + +to set up a *Hyperledger Cello* server and agent in the same place as quick as possible. + +However, in order to give you a deeper understanding of how everything works, +we instead walked through the entire setup step-by-step in this tutorial. diff --git a/docs/tutorials/server.md b/docs/tutorials/server.md index 0001da79..efb19a88 100644 --- a/docs/tutorials/server.md +++ b/docs/tutorials/server.md @@ -2,9 +2,15 @@ By the end of this lesson, you'll be able to set up a *Hyperledger Cello* server on your computer. -## Dashboard +To do so, we'll set up 3 components of it: dashboard, database, and the api engine. + +See also: [*Concepts*](../concepts.md). + +## Image +### Dashboard First, we'll need a dashboard for our server, which is the UI for us. -To do that, we have to build its image first by running: + +Thus, we have to build its image by running: ```bash make dashboard @@ -14,10 +20,10 @@ The image will be tagged as `hyperledger/cello-dashboard:latest`. This step can take a while because it builds the `node_module` via `yarn install`. -## Database +### Database We'll directly use the official PostgreSQL image as our database, so there is no need to build another one. -## API Engine +### API Engine Next, we'll build the center of our *Hyperledger Cello* server, which is the *api engine*. ```bash @@ -36,6 +42,18 @@ Finally, we can start the server by: make server ``` +If nothing goes wrong, you should see 3 containers running on your computer by executing + +```bash +docker ps +``` + +They should be named `cello-dashboard`, `cello-api-engine`, `cello-postgres` respectively. + +Go to [http://0.0.0.0:8081](http://0.0.0.0:8081) (replace the hostname with your connectable host e.g. [http://localhost:8081](http://localhost:8081)). + +If you can see the login page on your browser, you're good to go. + ## Conclusion That's it! You have successfully run a *Hyperledger Cello* server on your computer. @@ -49,7 +67,7 @@ Alternatively, you can run make local ``` -to set up a *Hyperledger Cello* server and agent as quick as possible. +to set up a *Hyperledger Cello* server and agent in the same place as quick as possible. However, in order to give you a deeper understanding of how everything works, -we instead walked through the entire setup step-by-step in this lesson above. +we instead walked through the entire setup step-by-step in this tutorial. diff --git a/mkdocs.yml b/mkdocs.yml index 756580f8..3de80ecf 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -57,6 +57,7 @@ nav: - "Lesson 0: Introduction": tutorials/introduction.md - "Lesson 1: Prerequisites": tutorials/prerequisites.md - "Lesson 2: Server": tutorials/server.md + - "Lesson 3: Agent": tutorials/agent.md - Agent: - Kubernetes: agents/kubernetes.md - Fabric operator: agents/fabric-operator.md From d3418f45e176d8fbdf798d1aff038abb96b47ae3 Mon Sep 17 00:00:00 2001 From: dodo920306 Date: Wed, 13 Aug 2025 00:41:39 +0000 Subject: [PATCH 16/24] Create lesson 4: User & Organization Signed-off-by: dodo920306 --- docs/tutorials/agent.md | 4 +-- docs/tutorials/organization.md | 47 +++++++++++++++++++++++++++++++++ docs/tutorials/prerequisites.md | 2 +- docs/tutorials/server.md | 4 +-- mkdocs.yml | 1 + 5 files changed, 53 insertions(+), 5 deletions(-) create mode 100644 docs/tutorials/organization.md diff --git a/docs/tutorials/agent.md b/docs/tutorials/agent.md index 8a0c7154..f26f9365 100644 --- a/docs/tutorials/agent.md +++ b/docs/tutorials/agent.md @@ -33,11 +33,11 @@ docker ps ``` ## Conclustion -That's it! You have successfully run a *Hyperledger Cello* agent on your computer. +That's it! You have successfully run a *Hyperledger Cello* agent on your computer🎉. In the next lesson, we'll talk about how you can create an organization and its first administrator. -See you then! +See you then👋! ## P.S. The "Quickstart" Way Alternatively, you can run diff --git a/docs/tutorials/organization.md b/docs/tutorials/organization.md new file mode 100644 index 00000000..ea0f068b --- /dev/null +++ b/docs/tutorials/organization.md @@ -0,0 +1,47 @@ +# Lesson 4: User & Organization + +Finally! After the previous lessons, you now are ready to enter and use *Hyperledger Cello*🎉! + +Remember the *Hyperledger Cello* server you built in the [lesson 2](./server.md)? + +By the end of that lesson, you should be able to enter [http://0.0.0.0:8081](http://0.0.0.0:8081) to see the login page. + +Now go back to it because we're going to enter the server. + +## Register + +The site asks for your email and password to login, but since we haven't registered before, just click on the "register" first. + +Once you switch to the registration form, you may notice that there is a description on it: + +> This registration form is only for setting up a new organization and its first administrator. If your organization already exists, please ask your administrator to create your account. + +It means that the registration is actually for **organizations**, and it will create a user for it incidentally to make sure that there won't be an organization without a user can login. + +In *Hyperledger Cello*, every user must belong to an organization just like they does in *Hyperledger Fabric*. + +To join an existing organization afterwards, ask its administrators to register you. Remember, a user can belong to only one organization. + +Now, fill in the form, so we can go to the next step. You must name your organization like hostnames (e.g. "org1.cello.com") because it will be used as a part of your *node* hostnames. (We'll talk about *nodes* in the following lessons.) + +You should see the "Register successfully!" message once you finish. Then, go to the login page and login with the email and password you just registered! + +## After login + +You can see the 2 concepts we talk about in this lesson by going to the "Organization" and "User" managerment page. You can see all organizations and users there. + +Additionally, you can start invite others to your organization by registering them on the user management page. + +## Conclusion + +That's it! You have successfully create your organization and register a user🎉! + +In the next lesson, we'll talk about how you can connect you server with your agent. + +See you then👋! + +## P.S. The "default" user + +You may notice that on the user management page, there is another user named "admin" created besides the user you just registered for yourself. That's the "default" user. The default user can't operate anything because it has no organization, but it allows one to login a *Hyperledger Cello* server to wander around and check if it's OK. + +The default user email and password is assigned by the environment varables `API_ENGINE_ADMIN_EMAIL` and `API_ENGINE_ADMIN_PASSWORD` of the api engine container. By default, they're `admin@cello.com` and `pass`. diff --git a/docs/tutorials/prerequisites.md b/docs/tutorials/prerequisites.md index 327759a3..599b5eef 100644 --- a/docs/tutorials/prerequisites.md +++ b/docs/tutorials/prerequisites.md @@ -28,4 +28,4 @@ If the command runs successfully, switch into the project directory: cd cello ``` -That's it for this lesson. See you in the next one! +That's it for this lesson. See you in the next one👋! diff --git a/docs/tutorials/server.md b/docs/tutorials/server.md index efb19a88..df837701 100644 --- a/docs/tutorials/server.md +++ b/docs/tutorials/server.md @@ -55,11 +55,11 @@ Go to [http://0.0.0.0:8081](http://0.0.0.0:8081) (replace the hostname with your If you can see the login page on your browser, you're good to go. ## Conclusion -That's it! You have successfully run a *Hyperledger Cello* server on your computer. +That's it! You have successfully run a *Hyperledger Cello* server on your computer🎉. In the next lesson, we'll talk about how you can run an agent for it. -See you then! +See you then👋! ## P.S. The "Quickstart" Way Alternatively, you can run diff --git a/mkdocs.yml b/mkdocs.yml index 3de80ecf..bf7a0db5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -58,6 +58,7 @@ nav: - "Lesson 1: Prerequisites": tutorials/prerequisites.md - "Lesson 2: Server": tutorials/server.md - "Lesson 3: Agent": tutorials/agent.md + - "Lesson 4: User & Organization": tutorials/organization.md - Agent: - Kubernetes: agents/kubernetes.md - Fabric operator: agents/fabric-operator.md From 3659d84c176dbfadf9db18f89c6161775147b162 Mon Sep 17 00:00:00 2001 From: dodo920306 Date: Wed, 13 Aug 2025 00:41:55 +0000 Subject: [PATCH 17/24] Add navigation footer Signed-off-by: dodo920306 --- mkdocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/mkdocs.yml b/mkdocs.yml index bf7a0db5..5c6c5130 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -9,6 +9,7 @@ theme: features: - navigation.tabs - navigation.top + - navigation.footer - content.code.copy palette: - scheme: default From 244e13a21d823231c6fc4ac933baa253fad5e37f Mon Sep 17 00:00:00 2001 From: dodo920306 Date: Wed, 13 Aug 2025 11:00:36 +0000 Subject: [PATCH 18/24] Add admonitions Signed-off-by: dodo920306 --- docs/tutorials/agent.md | 24 +++++++++++++----------- docs/tutorials/organization.md | 9 ++++----- docs/tutorials/server.md | 19 ++++++++++--------- mkdocs.yml | 1 + 4 files changed, 28 insertions(+), 25 deletions(-) diff --git a/docs/tutorials/agent.md b/docs/tutorials/agent.md index f26f9365..813a477d 100644 --- a/docs/tutorials/agent.md +++ b/docs/tutorials/agent.md @@ -2,10 +2,12 @@ By the end of this lesson, you'll be able to set up a *Hyperledger Cello* agent on your computer. -**Remember: You can totally follow this lesson on a different machine from where you follow the last lesson i.e.** -**The agents can be on a different machine from the server.** +!!! note + Remember: You can totally follow this lesson on a different machine from where you follow the last lesson i.e. + The agents can be on a different machine from the server. -See also: [*Concepts*](../concepts.md). +!!! info + See also: [*Concepts*](../concepts.md). ## Image ### Agent @@ -39,13 +41,13 @@ In the next lesson, we'll talk about how you can create an organization and its See you then👋! -## P.S. The "Quickstart" Way -Alternatively, you can run -```bash -make local -``` +!!! info "P.S. The "Quickstart" Way" + Alternatively, you can run + ```bash + make local + ``` -to set up a *Hyperledger Cello* server and agent in the same place as quick as possible. + to set up a *Hyperledger Cello* **server and agent** in the same place as quick as possible. -However, in order to give you a deeper understanding of how everything works, -we instead walked through the entire setup step-by-step in this tutorial. + However, in order to give you a deeper understanding of how everything works, + we instead walked through the entire setup step-by-step in this tutorial. diff --git a/docs/tutorials/organization.md b/docs/tutorials/organization.md index ea0f068b..d6c3f841 100644 --- a/docs/tutorials/organization.md +++ b/docs/tutorials/organization.md @@ -12,7 +12,7 @@ Now go back to it because we're going to enter the server. The site asks for your email and password to login, but since we haven't registered before, just click on the "register" first. -Once you switch to the registration form, you may notice that there is a description on it: +Once you switch to the registration form, you may notice that there is an admonition on it: > This registration form is only for setting up a new organization and its first administrator. If your organization already exists, please ask your administrator to create your account. @@ -40,8 +40,7 @@ In the next lesson, we'll talk about how you can connect you server with your ag See you then👋! -## P.S. The "default" user +!!! info "P.S. The "default" user" + You may have noticed that on the user management page, there is another user named "admin" created besides the user you just registered for yourself. That's the "default" user. The default user can't operate anything because it has no organization, but it allows one to login a *Hyperledger Cello* server to wander around and check if it's OK. -You may notice that on the user management page, there is another user named "admin" created besides the user you just registered for yourself. That's the "default" user. The default user can't operate anything because it has no organization, but it allows one to login a *Hyperledger Cello* server to wander around and check if it's OK. - -The default user email and password is assigned by the environment varables `API_ENGINE_ADMIN_EMAIL` and `API_ENGINE_ADMIN_PASSWORD` of the api engine container. By default, they're `admin@cello.com` and `pass`. + The default user email and password is assigned by the environment varables `API_ENGINE_ADMIN_EMAIL` and `API_ENGINE_ADMIN_PASSWORD` of the api engine container. By default, they're `admin@cello.com` and `pass`. diff --git a/docs/tutorials/server.md b/docs/tutorials/server.md index df837701..b8afaff6 100644 --- a/docs/tutorials/server.md +++ b/docs/tutorials/server.md @@ -4,7 +4,8 @@ By the end of this lesson, you'll be able to set up a *Hyperledger Cello* server To do so, we'll set up 3 components of it: dashboard, database, and the api engine. -See also: [*Concepts*](../concepts.md). +!!! info + See also: [*Concepts*](../concepts.md). ## Image ### Dashboard @@ -61,13 +62,13 @@ In the next lesson, we'll talk about how you can run an agent for it. See you then👋! -## P.S. The "Quickstart" Way -Alternatively, you can run -```bash -make local -``` +!!! info "P.S. The "Quickstart" Way" + Alternatively, you can run + ```bash + make local + ``` -to set up a *Hyperledger Cello* server and agent in the same place as quick as possible. + to set up a *Hyperledger Cello* **server and agent** in the same place as quick as possible. -However, in order to give you a deeper understanding of how everything works, -we instead walked through the entire setup step-by-step in this tutorial. + However, in order to give you a deeper understanding of how everything works, + we instead walked through the entire setup step-by-step in this tutorial. diff --git a/mkdocs.yml b/mkdocs.yml index 5c6c5130..9641ca6d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -38,6 +38,7 @@ markdown_extensions: - markdown.extensions.meta - markdown.extensions.toc: permalink: true + - pymdownx.details - pymdownx.superfences: custom_fences: - name: mermaid From e6cdc5d456e7499f4ac01c65c2dc4411967951e1 Mon Sep 17 00:00:00 2001 From: dodo920306 Date: Wed, 13 Aug 2025 11:17:34 +0000 Subject: [PATCH 19/24] Tell users they can write their own compose files Signed-off-by: dodo920306 --- docs/tutorials/agent.md | 3 +++ docs/tutorials/server.md | 3 +++ 2 files changed, 6 insertions(+) diff --git a/docs/tutorials/agent.md b/docs/tutorials/agent.md index 813a477d..f2daba6d 100644 --- a/docs/tutorials/agent.md +++ b/docs/tutorials/agent.md @@ -28,6 +28,9 @@ Next, start the agent by running make agent ``` +!!! tip + By doing so, you deploy the agent with a pre-written docker compose file `bootup/docker-compose-files/docker-compose.agent.dev.yml` Nevertheless, You can actually deploy the agent however you like if you want to write your own docker compose file with your own configurations. It's all up to you! + If nothing goes wrong, you should see a container named `cello-docker-agent` running on your computer by executing ```bash diff --git a/docs/tutorials/server.md b/docs/tutorials/server.md index b8afaff6..271d0093 100644 --- a/docs/tutorials/server.md +++ b/docs/tutorials/server.md @@ -43,6 +43,9 @@ Finally, we can start the server by: make server ``` +!!! tip + By doing so, you deploy the server with a pre-written docker compose file `bootup/docker-compose-files/docker-compose.server.dev.yml`. Nevertheless, You can actually deploy the server however you like if you want to write your own docker compose file with your own configurations. It's all up to you! + If nothing goes wrong, you should see 3 containers running on your computer by executing ```bash From 64e4d6e1b95262873c233911b49af03b01df2f99 Mon Sep 17 00:00:00 2001 From: dodo920306 Date: Wed, 13 Aug 2025 12:56:49 +0000 Subject: [PATCH 20/24] Create lesson 5: agent, network, and node Signed-off-by: dodo920306 --- docs/tutorials/agent.md | 2 +- docs/tutorials/node.md | 79 ++++++++++++++++++++++++++++++++++ docs/tutorials/organization.md | 2 +- mkdocs.yml | 1 + 4 files changed, 82 insertions(+), 2 deletions(-) create mode 100644 docs/tutorials/node.md diff --git a/docs/tutorials/agent.md b/docs/tutorials/agent.md index f2daba6d..1fcbe59b 100644 --- a/docs/tutorials/agent.md +++ b/docs/tutorials/agent.md @@ -45,7 +45,7 @@ In the next lesson, we'll talk about how you can create an organization and its See you then👋! !!! info "P.S. The "Quickstart" Way" - Alternatively, you can run + Just as mentioned in the [last lesson](./server.md), alternatively, you can run ```bash make local ``` diff --git a/docs/tutorials/node.md b/docs/tutorials/node.md new file mode 100644 index 00000000..193788ee --- /dev/null +++ b/docs/tutorials/node.md @@ -0,0 +1,79 @@ +# Lesson 5: Agent, Network, & Node + +Now, you're ready to connect your server with your agent. + +## Agent + +To do that, please login to your server and go to the agent management page. + +Click on the "New" button to register a new agent with a URL linked to your agent host. The default agent port is `5001`. + +!!! info + Even if you register the agent successfully, it doesn't mean that the server can access the agent successfully. The server will only try to connect the agent when it has to operate *nodes*, and this will happen later in this lesson when we create a *network*. + +## Nodes + +### Image + +Compared to the usual pratice of *Hyperledger Fabric*, *Hyperledger Cello* doesn't use the official peer and orderer images to deploy nodes. Instead, *Hyperledger Cello* uses its own {++customized++} *Hyperledger Fabric* node images, which combines all *Hyperledger Fabric* binaries into one single image. + +To build that, run + +```bash +make fabric +``` + +The image will be tagged as `hyperledger/fabric:2.5.10`. + +!!! info "The "Quickstart" way" + The quickstart `make local` command we mentioned in [lesson 2](./server.md) and [lesson 3](./agent.md) will also build the node image for you. + +### Create peers and orderers + +!!! info + If you don't know what *peers* and *orderers* are, please check out [*Peers*](https://hyperledger-fabric.readthedocs.io/en/latest/peers/peers.html). + +Go to the node management page and click on the "New" button. You can choose to create either a *peer* or an *orderer* and name it. + +To create a channel in the following lessons, you must create at least 1 peer and 1 orderer. + +You should name them like hostnames just as you do for your organization because their names will also be used as a part of their hostnames. + +## Network + +You may notice that currently the status of your nodes are "created", and you don't see any container like *Hyperledger Fabric* nodes +running on your agent host. That's because the server **won't ask agents to deploy nodes until they're in a network**. + +Thus, you have to create a *network* to place your *nodes*. + +!!! info + *Network* actually derives from a deprecated idea *system channel* in *Hyperledger Fabric*, which means it also will be deprecated in the near future. However, we still need it here to run our nodes currently. + +Go to the network management page and click on the "New" button to create a network. + +After you create a network successfully, even though it doesn't seem like there is anything happening, you can go to the node management page to see if your node status turns to green with a "running" label. Please wait about 5 minutes if you don't see any change. After that, there may be something wrong in your deployment. You can check the container logs by executing [the `docker logs` command](https://docs.docker.com/reference/cli/docker/container/logs/) with the api engine or agent container or consider [contacting us](../../#communication-channels). + +Otherwise, you should see your nodes running as containers on your agent host by executing + +```bash +docker ps +``` + +!!! info + A peer container will be named as the peer name concatenated with the organization name. + + An orderer container will be named as the organization name with its first part replaced with the orderer name. + + For example, if there is an organization named "org1.cello.com" with a peer named "peer1" and an orderer named "orderer1", their containers should be named as "peer1.org1.cello.com" and "orderer1.cello.com". + + Such a naming method emphasizes that an orderer doesn't solely belong to its organization in a *Hyperledger Fabric* network. + +## Conclusion + +That's it! You have successfully connected your *Hyperledger Cello* server with your agent🎉! + +Moreover, you also managed to deploy some *Hyperledger Fabric* running nodes! + +In the next lesson, we'll talk about how you can create a *channel* with them. + +See you then👋! diff --git a/docs/tutorials/organization.md b/docs/tutorials/organization.md index d6c3f841..43497838 100644 --- a/docs/tutorials/organization.md +++ b/docs/tutorials/organization.md @@ -34,7 +34,7 @@ Additionally, you can start invite others to your organization by registering th ## Conclusion -That's it! You have successfully create your organization and register a user🎉! +That's it! You have successfully created your organization and register a user🎉! In the next lesson, we'll talk about how you can connect you server with your agent. diff --git a/mkdocs.yml b/mkdocs.yml index 9641ca6d..db5c2034 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -61,6 +61,7 @@ nav: - "Lesson 2: Server": tutorials/server.md - "Lesson 3: Agent": tutorials/agent.md - "Lesson 4: User & Organization": tutorials/organization.md + - "Lesson 5: Agent, Network, & Node": tutorials/node.md - Agent: - Kubernetes: agents/kubernetes.md - Fabric operator: agents/fabric-operator.md From c196b28d1faf165139f7207bc87239ec28d566a3 Mon Sep 17 00:00:00 2001 From: dodo920306 Date: Thu, 14 Aug 2025 12:29:46 +0000 Subject: [PATCH 21/24] Create "Lesson 6: Channel and Chaincode" Signed-off-by: dodo920306 --- docs/tutorials/channel.md | 78 +++++++++++++++++++++++++++++++++++++++ docs/tutorials/node.md | 3 ++ mkdocs.yml | 1 + 3 files changed, 82 insertions(+) create mode 100644 docs/tutorials/channel.md diff --git a/docs/tutorials/channel.md b/docs/tutorials/channel.md new file mode 100644 index 00000000..0c7204d9 --- /dev/null +++ b/docs/tutorials/channel.md @@ -0,0 +1,78 @@ +# Lesson 6: Channel and Chaincode + +!!! bug + Currently, this feature only works if the server is on the same host with agents i.e. **You can create channels only if all your *Hyperledger Cello* components aren't deployed across multiple hosts**. + + This is a serious bug, and we've noticed that. For the latest information about this issue, follow [#733](https://github.com/hyperledger-cello/cello/issues/733). + +!!! info + If you don't what channels are, please check out [Channels](https://hyperledger-fabric.readthedocs.io/en/release-2.5/channels.html). + +!!! info + If you don't what chaincodes are, please check out [Smart Contracts and Chaincode](https://hyperledger-fabric.readthedocs.io/en/release-2.5/smartcontract/smartcontract.html). + +After all the previous 6 lessons, you now are ready to create your first ***Blockchain*** with *Hyperledger Cello*. + +*Channel* is the closest concept to what a *blockchain* is known by the general public, or more specifically, a *private* blockchain, in the *Hyperledger Fabric* world. + +In contrast, *Chaincode* is the closest concept to what a *smart contract* is known by the general public in the *Hyperledger Fabric* world. + +## Create a Channel + +Go to the channel management page and click on the "New" button. + +Then, name the channel and choose your peers and orderers. + +## Deploy a Chaincode + +Mainly, there are 4 steps you should do when you deploy a chaincode + +1. Package +2. Install +3. Approve (for your organization only) +4. Commit + +Each step has its own meaning. + +Without packaging, you can't install a chaincode on a peer. + +Without installing, you can't approve a chaincode for your organization. + +Without approving, you can't commit a chaincode to a channel. + +Finally, without commiting, you can't use a chaincode to send transactions. + +### Package + +You have to do it yourself for this step. Please refer to [Package the smart contract](https://hyperledger-fabric.readthedocs.io/en/release-2.5/deploy_chaincode.html#package-the-smart-contract). + +### Install + +Go to the chaincode management page and click on the "New" button. + +Upload your chaincode package from the last step. + +The uploaded chaincode package ID will be shown as the label of it (assigned during packaging) and a hash value. + +After that, click on the "Install" button shown on your chaincode. + +### Approve + +If nothing goes wrong, click on the "Approve" button then. + +### Commit + +Lastly, commit the chaincode by the "Commit" button. + +## Conclusion + +That's it! You have successfully created your first *Hyperledger Fabric* channel, which is your first *blockchain*, with *Hyperledger Cello*🎉! + +Moreover, you also deployed your first *Hyperledger Fabric* chaincode, which is your first *smart contract*! + +In the next lesson, we'll talk about how you can interact with it. + +See you then👋! + +!!! warning + **You can't**. Currently you still can't interact with your chaincode through the *Hyperledger Cello*. Such a feature is still under development. Thus, there is no next lesson, but there will be one once the feature is finished😊! diff --git a/docs/tutorials/node.md b/docs/tutorials/node.md index 193788ee..c03f3876 100644 --- a/docs/tutorials/node.md +++ b/docs/tutorials/node.md @@ -77,3 +77,6 @@ Moreover, you also managed to deploy some *Hyperledger Fabric* running nodes! In the next lesson, we'll talk about how you can create a *channel* with them. See you then👋! + +!!! note + **Network* is not *Blockchain**, and there is no block on it. *Network* is just an abstract idea about what connects between organization *nodes*. diff --git a/mkdocs.yml b/mkdocs.yml index db5c2034..363c787d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -62,6 +62,7 @@ nav: - "Lesson 3: Agent": tutorials/agent.md - "Lesson 4: User & Organization": tutorials/organization.md - "Lesson 5: Agent, Network, & Node": tutorials/node.md + - "Lesson 6: Channel": tutorials/channel.md - Agent: - Kubernetes: agents/kubernetes.md - Fabric operator: agents/fabric-operator.md From 55cf7ce87f31cba931591a70aca875dd9fd421ea Mon Sep 17 00:00:00 2001 From: dodo920306 Date: Thu, 14 Aug 2025 12:40:57 +0000 Subject: [PATCH 22/24] Tell beginners to read tutorials first Signed-off-by: dodo920306 --- docs/design/arch.md | 5 +++++ docs/index.md | 2 +- docs/tutorials/channel.md | 2 +- 3 files changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/design/arch.md b/docs/design/arch.md index c429bb62..4855d076 100644 --- a/docs/design/arch.md +++ b/docs/design/arch.md @@ -1,3 +1,8 @@ +--- +hide: + - navigation +--- + # Architecture Design Here we discuss the architecture design for the mangement services on the Master node. diff --git a/docs/index.md b/docs/index.md index bc2fb068..ff124e33 100644 --- a/docs/index.md +++ b/docs/index.md @@ -28,7 +28,7 @@ Using Cello, blockchain developers can: ## [Getting Started](setup/server.md) -**For beginners, it is highly recommended to read the [Setup](setup/server.md) first**. +**For beginners, it is highly recommended to read the [Tutorials](tutorials/introduction.md) first**. ## Operation Guidelines * [Operator operations in dashboard](operations/dashboard/operator.md) diff --git a/docs/tutorials/channel.md b/docs/tutorials/channel.md index 0c7204d9..dbbd5758 100644 --- a/docs/tutorials/channel.md +++ b/docs/tutorials/channel.md @@ -1,4 +1,4 @@ -# Lesson 6: Channel and Chaincode +# Lesson 6: Channel & Chaincode !!! bug Currently, this feature only works if the server is on the same host with agents i.e. **You can create channels only if all your *Hyperledger Cello* components aren't deployed across multiple hosts**. From dd70e306dd309f7ae1e7e556556ec01944ab62ff Mon Sep 17 00:00:00 2001 From: dodo920306 Date: Thu, 14 Aug 2025 12:42:19 +0000 Subject: [PATCH 23/24] Remove obsolete or unfinished pages from the index Signed-off-by: dodo920306 --- docs/index.md | 6 +++--- mkdocs.yml | 11 ----------- 2 files changed, 3 insertions(+), 14 deletions(-) diff --git a/docs/index.md b/docs/index.md index ff124e33..04ba0051 100644 --- a/docs/index.md +++ b/docs/index.md @@ -26,16 +26,16 @@ Using Cello, blockchain developers can: ![Typical Scenario](images/scenario.png) -## [Getting Started](setup/server.md) +## Getting Started -**For beginners, it is highly recommended to read the [Tutorials](tutorials/introduction.md) first**. +**For beginners, it is highly recommended to read the [*Tutorials*](tutorials/introduction.md) first**. ## Operation Guidelines * [Operator operations in dashboard](operations/dashboard/operator.md) * [Admin operations in dashboard](operations/dashboard/admin.md) * [User operations in dashboard](operations/dashboard/user.md) -## [Contribute to the Project](contributing.md) +## Contribute to the Project * [How to Contribute](contributing.md) * [Code Style Guide](https://black.readthedocs.io/en/stable/the_black_code_style.html) diff --git a/mkdocs.yml b/mkdocs.yml index 363c787d..6bbcb031 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -53,8 +53,6 @@ nav: - Concepts: concepts.md - Design: - Architecture: design/arch.md - - Setup: - - Server: setup/server.md - Tutorials: - "Lesson 0: Introduction": tutorials/introduction.md - "Lesson 1: Prerequisites": tutorials/prerequisites.md @@ -63,20 +61,11 @@ nav: - "Lesson 4: User & Organization": tutorials/organization.md - "Lesson 5: Agent, Network, & Node": tutorials/node.md - "Lesson 6: Channel": tutorials/channel.md - - Agent: - - Kubernetes: agents/kubernetes.md - - Fabric operator: agents/fabric-operator.md - - Operations: - - Dashboard: - - Operator operations: operations/dashboard/operator.md - - Admin operations: operations/dashboard/admin.md - - User operations: operations/dashboard/user.md - Reference: - Configuration: - Server Configuration: reference/configuration/server.md - Commands: - make: reference/commands/make.md - - cli: reference/commands/cli.md - Contribute: contributing.md - FAQ: - faq.md From 09d529b8fd4be3cbaadc5092ca1923bd1285967a Mon Sep 17 00:00:00 2001 From: dodo920306 Date: Thu, 14 Aug 2025 12:43:33 +0000 Subject: [PATCH 24/24] Remove operations from the homepage They're all empty. Signed-off-by: dodo920306 --- docs/index.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/index.md b/docs/index.md index 04ba0051..21cac0ec 100644 --- a/docs/index.md +++ b/docs/index.md @@ -30,11 +30,6 @@ Using Cello, blockchain developers can: **For beginners, it is highly recommended to read the [*Tutorials*](tutorials/introduction.md) first**. -## Operation Guidelines -* [Operator operations in dashboard](operations/dashboard/operator.md) -* [Admin operations in dashboard](operations/dashboard/admin.md) -* [User operations in dashboard](operations/dashboard/user.md) - ## Contribute to the Project * [How to Contribute](contributing.md) * [Code Style Guide](https://black.readthedocs.io/en/stable/the_black_code_style.html)