Skip to content

Commit

Permalink
docs(all): checking in integrated Cacti docs built using MkDocs
Browse files Browse the repository at this point in the history
Also added a GitHub action to push built docs to 'gh-pages' branch,
and then publish those docs to the organization's GitHub pages.

Signed-off-by: VRamakrishna <[email protected]>
  • Loading branch information
VRamakrishna authored and petermetz committed Oct 4, 2023
1 parent 063222c commit 8dd1c09
Show file tree
Hide file tree
Showing 122 changed files with 12,500 additions and 0 deletions.
36 changes: 36 additions & 0 deletions .github/workflows/deploy_docs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# Copyright IBM Corp. All Rights Reserved.
#
# SPDX-License-Identifier: CC-BY-4.0

name: Deploy Docs (Github Pages)

on:
push:
branches:
- main
paths:
- 'docs/**'

# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:

jobs:
deploy-docs:
runs-on: ubuntu-latest
steps:
# Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
- uses: actions/checkout@v3

- name: Use Python 3.x
uses: actions/setup-python@v4
with:
python-version: '3.10'
cache: 'pip' # caching pip dependencies

- name: Install dependencies
run: pip install -r requirements.txt
working-directory: docs

- name: Build and publish
run: git pull && mkdocs gh-deploy
working-directory: docs
1 change: 1 addition & 0 deletions docs/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
site/
1 change: 1 addition & 0 deletions docs/CODEOWNERS
Validating CODEOWNERS rules …
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
* @VRamakrishna
396 changes: 396 additions & 0 deletions docs/LICENSE

Large diffs are not rendered by default.

61 changes: 61 additions & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
# Welcome to the documentation template

This repository serves as a template for creating documentation for Hyperledger projects. The template utilizes MkDocs (documentation at [mkdocs.org](https://www.mkdocs.org)) and the theme Material for MkDocs (documentation at [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)). Material adds a number of extra features to MkDocs, and Hyperledger repositories can take advantage of the theme's [Insiders](https://squidfunk.github.io/mkdocs-material/insiders/) capabilities.

[Material for MkDocs]: https://squidfunk.github.io/mkdocs-material/
[Mike]: https://github.com/jimporter/mike

## Prerequisites

To test the documents and update the published site, the following tools are needed:

- A Bash shell
- git
- Python 3
- The [Material for Mkdocs] theme.
- The [Mike] MkDocs plugin for publishing versions to gh-pages.
- Not used locally, but referenced in the `mkdocs.yml` file and needed for
deploying the site to gh-pages.

### git
`git` can be installed locally, as described in the [Install Git Guide from GitHub](https://github.com/git-guides/install-git).

### Python 3
`Python 3` can be installed locally, as described in the [Python Getting Started guide](https://www.python.org/about/gettingstarted/).

### Mkdocs

The Mkdocs-related items can be installed locally, as described in the [Material
for Mkdocs] installation instructions. The short, case-specific version of those
instructions follow:

```bash
pip install -r requirements.txt
```

### Verify Setup

To verify your setup, check that you can run `mkdocs` by running the command `mkdocs --help` to see the help text.

## Useful MkDocs Commands

The commands you will usually use with `mkdocs` are:

* `mkdocs serve` - Start the live-reloading docs server.
* `mkdocs build` - Build the documentation site.
* `mkdocs -h` - Print help message and exit.
* `mkdocs gh-deploy` - Build and push documents to `gh-pages` branch, and publish to URL configured in `mkdocs.yml`.

## Adding Content

The basic process for adding content to the site is:

- Create a new markdown file under the `docs` folder
- Add the new file to the table of contents (`nav` section in the `mkdocs.yml` file)

## Repository layout

mkdocs.yml # The configuration file.
docs/
index.md # The documentation homepage.
... # Other markdown pages, images and other files.
15 changes: 15 additions & 0 deletions docs/docs/architecture.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
The Cacti integrated architecture is illustrated below.

<img src="../images/cacti-architecture-v2-integration.png">

This consists of a set of modules, services (offering standard APIs), and libraries that offer a selection of cross-network transaction pipelines, which can be constructed by picking and choosing from the collection.

The integrated architecture was generated by fusing the pre-existing Cactus and Weaver architectures, identifying and re-labeling common (or overlapping) components and calling out unique components separately.

For reference, here is the Cactus architecture.

<img src="../images/cactus-architecture.png">

And here is the Weaver architecture.

<img src="../images-weaver/weaver-architecture.png">
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
223 changes: 223 additions & 0 deletions docs/docs/cactus/build.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,223 @@
Hyperledger Cactus 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.

Developers guide
----------------

This is a video guide to setup Hyperledger Cactus on your local machine.

### Installing git

[![IMAGE ALT TEXT HERE](https://img.youtube.com/vi/RJhifrmSiNA/0.jpg)](https://www.youtube.com/watch?v=RJhifrmSiNA)

### Installing and configuring docker

[![IMAGE ALT TEXT HERE](https://img.youtube.com/vi/V8YBQoxdyiE/0.jpg)](https://www.youtube.com/watch?v=V8YBQoxdyiE)

### Installing npm and node

[![IMAGE ALT TEXT HERE](https://img.youtube.com/vi/94xoV9Vfu14/0.jpg)](https://www.youtube.com/watch?v=94xoV9Vfu14)

### Installing jdk 8

[![IMAGE ALT TEXT HERE](https://img.youtube.com/vi/V8YBQoxdyiE/0.jpg)](https://youtube.com/watch?v=t4y57Qvrdcc)

### Installing VSCode and plugins

[![IMAGE ALT TEXT HERE](https://img.youtube.com/vi/RHQLhZRlAR0/0.jpg)](https://www.youtube.com/watch?v=RHQLhZRlAR0)

### Clone the repository

[![IMAGE ALT TEXT HERE](https://img.youtube.com/vi/n_HiEwgzPsM/0.jpg)](https://www.youtube.com/watch?v=n_HiEwgzPsM)

### Compiling all packages

[![IMAGE ALT TEXT HERE](https://img.youtube.com/vi/5v82MAHPQmM/0.jpg)](https://www.youtube.com/watch?v=5v82MAHPQmM)

### Testing all packages

[![IMAGE ALT TEXT HERE](https://img.youtube.com/vi/mVuk8txh-JE/0.jpg)](https://www.youtube.com/watch?v=mVuk8txh-JE)

### Compiling a specific packages

[![IMAGE ALT TEXT HERE](https://img.youtube.com/vi/e7vkd9i-I4c/0.jpg)](https://www.youtube.com/watch?v=e7vkd9i-I4c)

### Testing a specific package

[![IMAGE ALT TEXT HERE](https://img.youtube.com/vi/Jzw9JQZu6c8/0.jpg)](https://www.youtube.com/watch?v=Jzw9JQZu6c8)

### Package structure - OpenAPI

[![IMAGE ALT TEXT HERE](https://img.youtube.com/vi/5uuRTc3X4MM/0.jpg)](https://www.youtube.com/watch?v=5uuRTc3X4MM)

### Package structure - Web Services

[![IMAGE ALT TEXT HERE](https://img.youtube.com/vi/DAML56rx5yQ/0.jpg)](https://www.youtube.com/watch?v=DAML56rx5yQ)

### Package structure - Main and Factory Plugin class

[![IMAGE ALT TEXT HERE](https://img.youtube.com/vi/w0bmkpge2Dw/0.jpg)](https://www.youtube.com/watch?v=w0bmkpge2Dw)

### Package structure - Test class

[![IMAGE ALT TEXT HERE](https://img.youtube.com/vi/3XpBYhN-8qs/0.jpg)](https://www.youtube.com/watch?v=3XpBYhN-8qs)

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](_images/hyperledger-cactus-watch-script-tutorial-2021-03-06.gif)

Getting Started
----------------------------------------------------------------

* Use preset environment:

* [VSCode docker container](#./.devcontainer)

* … or install OS level dependencies manually:

* Windows Only

* WSL2 or any virtual machine running Ubuntu 20.04 LTS

* Git

* NodeJS v16.14.2, npm v8.5.0 (we recommend using the Node Version Manager (nvm) if available for your OS)

nvm install 16.14.2
nvm use 16.14.2

* Yarn

* `npm run install-yarn` (from within the project directory)

* [Docker Engine](https://docs.docker.com/engine/install/ubuntu/). Make sure that Docker is working and running, for example, running `docker ps -aq`

* Docker Compose

* OpenJDK (Corda support Java 8 JDK but do not currently support Java 9 or higher)

* `sudo apt install openjdk-8-jdk-headless`

* Indy SDK (optional)

* [Installing the SDK](https://github.com/hyperledger/indy-sdk#installing-the-sdk)

* [Build the SDK from source](https://github.com/hyperledger/indy-sdk#how-to-build-indy-sdk-from-source)

* Clone the repository


git clone https://github.com/hyperledger/cactus.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 cactus

* 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


### 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 20.04 LTS

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(r) 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](_images/build-script-decision-tree-2021-03-06.png)

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](https://docs.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh/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/[email protected]) 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 your GitHub Actions by using ssh](https://github.com/marketplace/actions/debugging-with-ssh).

By creating a PR for the edited `ci.yml` file, this will 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-20.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](introduction.md "Welcome to Hyperledger Cactus documentation!") [Next](examples.md "Examples")

* * *
8 changes: 8 additions & 0 deletions docs/docs/cactus/code-of-conduct.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
Code of Conduct Guidelines
======================================================================================

Please review the Hyperledger [Code of Conduct](https://wiki.hyperledger.org/community/hyperledger-project-code-of-conduct) before participating and abide by these community standards.

[Previous](governance.md "Governance") [Next](contributing.md "Contributing")

* * *
Loading

0 comments on commit 8dd1c09

Please sign in to comment.