From eb739aeeb6b67a37644636d21c066d43f2ba9e77 Mon Sep 17 00:00:00 2001 From: Abhinav Srivastava Date: Thu, 9 Jun 2022 19:12:55 -0700 Subject: [PATCH 1/3] docs(build): add text build steps for Linux, Mac and Windows #1963 Signed-off-by: Abhinav Srivastava --- BUILD.md | 139 ++++++++++++++++++++++++++----------------------------- 1 file changed, 66 insertions(+), 73 deletions(-) diff --git a/BUILD.md b/BUILD.md index 026ed3b138..146f8708e0 100644 --- a/BUILD.md +++ b/BUILD.md @@ -1,91 +1,84 @@ -# Hyperledger Cactus Build Instructions +### Cactus BUILD instruction -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. +#### Installing Git +Git is a tool for version control that you will need to build and maintain Hyperledger Cactus from source. To install Git on a Debian-based Linux system, you should run the following command. -> 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) +```shell +sudo apt install git-all +``` -### Package structure - OpenAPI +Installation methods for other systems can be found [here](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git). + +#### Installing Docker + +Docker is a tool for containerization of softwares. It helps ship software and mitigates compatibility issues. To install Docker, please follow the installation guide provided [here](https://docs.docker.com/engine/install/). + +To install Docker on Debian, one would follow the following steps. + +```shell= +### Uninstall old Docker versions +sudo apt-get remove docker docker-engine docker.io containerd runc + +### Setup your repositories +sudo apt-get update +sudo apt-get install \ + ca-certificates \ + curl \ + gnupg \ + lsb-release + +### Add Docker's GPG keys +sudo mkdir -p /etc/apt/keyrings +curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg +echo \ + "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian \ $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null + +### Install the Docker Engine +sudo apt-get update +sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin + +### Check that the package has been correctly installed +sudo docker run hello-world -[![IMAGE ALT TEXT HERE](https://img.youtube.com/vi/5uuRTc3X4MM/0.jpg)](https://www.youtube.com/watch?v=5uuRTc3X4MM) +``` -### Package structure - Web Services +#### Installing NPM and Node -[![IMAGE ALT TEXT HERE](https://img.youtube.com/vi/DAML56rx5yQ/0.jpg)](https://www.youtube.com/watch?v=DAML56rx5yQ) +NPM is Node Package Manager and essential to building Cactus. There are many different methods of installing Node depending on your system and thus it is recommended you follow the guide provided [here](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). -### Package structure - Main and Factory Plugin class +``` +sudo apt-get update +sudo apt install nodejs +sudo apt install npm +``` -[![IMAGE ALT TEXT HERE](https://img.youtube.com/vi/w0bmkpge2Dw/0.jpg)](https://www.youtube.com/watch?v=w0bmkpge2Dw) +#### Installing JDK 8 -### Package structure - Test class +``` +sudo apt-get update +sudo apt-get install openjdk-8-jdk -[![IMAGE ALT TEXT HERE](https://img.youtube.com/vi/3XpBYhN-8qs/0.jpg)](https://www.youtube.com/watch?v=3XpBYhN-8qs) +### Check the version of Java +java -version -## Fast Developer Flow / Code Iterations +### If you're using bash, you may need to set this in your bashrc file +export JAVA_HOME= +``` -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. +#### Installing VS Code -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). +You can download and install VS Code from [here](https://code.visualstudio.com/download). It is suggested to install the git-graph and Docker plugins. -It also supports re-running the OpenAPI generator when you update any -`openapi.json` spec files that we use to describe our endpoints. +#### Clone and compile the Cactus repository 🌵 -The `npm run watch` script in action: +``` +git clone https://github.com/hyperledger/cactus +npm install +npm run configure -![Fast Developer Flow / Code Iterations](./docs/hyperledger-cactus-watch-script-tutorial-2021-03-06.gif) +### To test all your packages, you can run +npm run test:all +``` ## Getting Started @@ -232,4 +225,4 @@ By creating a PR for the edited `ci.yml` file, this will the CI to run their tes 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. \ No newline at end of file +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. From ad35ad1f953c64eccf1367800aaf91e91ccd71f2 Mon Sep 17 00:00:00 2001 From: Abhinav Srivastava Date: Mon, 13 Jun 2022 16:04:02 -0700 Subject: [PATCH 2/3] Update BUILD.md Signed-off-by: Abhinav Srivastava --- BUILD.md | 31 +++++++++++++++++-------------- 1 file changed, 17 insertions(+), 14 deletions(-) diff --git a/BUILD.md b/BUILD.md index 146f8708e0..c85b01bdb3 100644 --- a/BUILD.md +++ b/BUILD.md @@ -1,5 +1,7 @@ ### Cactus BUILD instruction +`apt` is available on Debian and its downstream distros. Windows and Mac installation instructions are provided below. Alternatively, you can use `choco` on Windows and `brew` on MacOS (although they aren't as maintained as `apt`). + #### Installing Git Git is a tool for version control that you will need to build and maintain Hyperledger Cactus from source. To install Git on a Debian-based Linux system, you should run the following command. @@ -42,29 +44,30 @@ sudo docker run hello-world ``` -#### Installing NPM and Node - -NPM is Node Package Manager and essential to building Cactus. There are many different methods of installing Node depending on your system and thus it is recommended you follow the guide provided [here](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). +#### Installing nvm, nodejs and yarn ``` -sudo apt-get update -sudo apt install nodejs -sudo apt install npm +curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash +nvm install --lts + +curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - +echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list +sudo apt update && sudo apt install yarn ``` -#### Installing JDK 8 +#### Installing JDK 11 ``` -sudo apt-get update -sudo apt-get install openjdk-8-jdk - -### Check the version of Java +sudo apt-get update && sudo apt-get upgrade +sudo apt-get install openjdk-11-jdk java -version ### If you're using bash, you may need to set this in your bashrc file export JAVA_HOME= ``` +For Windows, you can follow the guide provided [here](https://docs.oracle.com/en/java/javase/11/install/installation-jdk-microsoft-windows-platforms.html#GUID-371F38CC-248F-49EC-BB9C-C37FC89E52A0). For MacOS, you can follow the instructions [here](https://docs.oracle.com/en/java/javase/11/install/installation-jdk-macos.html#GUID-F575EB4A-70D3-4AB4-A20E-DBE95171AB5F). + #### Installing VS Code You can download and install VS Code from [here](https://code.visualstudio.com/download). It is suggested to install the git-graph and Docker plugins. @@ -73,11 +76,11 @@ You can download and install VS Code from [here](https://code.visualstudio.com/d ``` git clone https://github.com/hyperledger/cactus -npm install -npm run configure +yarn add +yarn configure ### To test all your packages, you can run -npm run test:all +yarn test:all ``` ## Getting Started From 04048fcf844cc9adfcbc580fc872cf78820ab6b4 Mon Sep 17 00:00:00 2001 From: Abhinav Srivastava Date: Mon, 13 Jun 2022 16:05:38 -0700 Subject: [PATCH 3/3] Update BUILD.md Signed-off-by: Abhinav Srivastava --- BUILD.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/BUILD.md b/BUILD.md index c85b01bdb3..0de51571c0 100644 --- a/BUILD.md +++ b/BUILD.md @@ -2,6 +2,10 @@ `apt` is available on Debian and its downstream distros. Windows and Mac installation instructions are provided below. Alternatively, you can use `choco` on Windows and `brew` on MacOS (although they aren't as maintained as `apt`). +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. + #### Installing Git Git is a tool for version control that you will need to build and maintain Hyperledger Cactus from source. To install Git on a Debian-based Linux system, you should run the following command.