-
Notifications
You must be signed in to change notification settings - Fork 283
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs(build): add text build steps for Linux, Mac and Windows #2072
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,91 +1,91 @@ | ||
# 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. | ||
`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 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. | ||
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. | ||
|
||
The project uses Typescript for both back-end and front-end components. | ||
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. | ||
|
||
## 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 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. After this line, reference can also be given to use docker without sudo, as mentioned here, https://docs.docker.com/engine/install/linux-postinstall/ |
||
|
||
[![IMAGE ALT TEXT HERE](https://img.youtube.com/vi/5uuRTc3X4MM/0.jpg)](https://www.youtube.com/watch?v=5uuRTc3X4MM) | ||
``` | ||
|
||
### Package structure - Web Services | ||
#### Installing nvm, nodejs and yarn | ||
|
||
[![IMAGE ALT TEXT HERE](https://img.youtube.com/vi/DAML56rx5yQ/0.jpg)](https://www.youtube.com/watch?v=DAML56rx5yQ) | ||
``` | ||
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash | ||
nvm install --lts | ||
|
||
### Package structure - Main and Factory Plugin class | ||
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 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. For yarn, we do have a npm script. One can run this npm script from the cactus root folder, |
||
``` | ||
|
||
[![IMAGE ALT TEXT HERE](https://img.youtube.com/vi/w0bmkpge2Dw/0.jpg)](https://www.youtube.com/watch?v=w0bmkpge2Dw) | ||
#### Installing JDK 11 | ||
|
||
### Package structure - Test class | ||
``` | ||
sudo apt-get update && sudo apt-get upgrade | ||
sudo apt-get install openjdk-11-jdk | ||
java -version | ||
|
||
[![IMAGE ALT TEXT HERE](https://img.youtube.com/vi/3XpBYhN-8qs/0.jpg)](https://www.youtube.com/watch?v=3XpBYhN-8qs) | ||
### If you're using bash, you may need to set this in your bashrc file | ||
export JAVA_HOME=<path_to_java_home> | ||
``` | ||
|
||
## Fast Developer Flow / Code Iterations | ||
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). | ||
|
||
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. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Here, we can also mention the |
||
|
||
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 | ||
yarn add | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. We can specify the |
||
yarn configure | ||
|
||
![Fast Developer Flow / Code Iterations](./docs/hyperledger-cactus-watch-script-tutorial-2021-03-06.gif) | ||
### To test all your packages, you can run | ||
yarn test:all | ||
``` | ||
|
||
## Getting Started | ||
|
||
|
@@ -232,4 +232,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. | ||
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I believe saying Hyperledger Cactus (instead of just Cactus) here is better.