From 2e682b0c608b6b3fac12fca7a39227bcd7309e8d Mon Sep 17 00:00:00 2001 From: mik-tf Date: Fri, 26 Apr 2024 22:11:07 +0000 Subject: [PATCH 1/5] Update docs/hero_mdbook_fullvm.md --- docs/hero_mdbook_fullvm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/hero_mdbook_fullvm.md b/docs/hero_mdbook_fullvm.md index f85b93d..7517a09 100644 --- a/docs/hero_mdbook_fullvm.md +++ b/docs/hero_mdbook_fullvm.md @@ -86,7 +86,7 @@ ssh-add /root/.ssh/books ## Install hero, crysallib and V ``` -curl https://raw.githubusercontent.com/freeflowuniverse/crystallib/development/scripts/build_hero.sh > /tmp/build_hero.sh +curl https://raw.githubusercontent.com/freeflowuniverse/crystallib/development/scripts/installer_hero.sh > /tmp/build_hero.sh bash /tmp/build_hero.sh ``` -- 2.40.1 From 5c87340c671f99500058ff06d174c372ddf963cc Mon Sep 17 00:00:00 2001 From: mik-tf Date: Fri, 26 Apr 2024 22:17:31 +0000 Subject: [PATCH 2/5] updated create mdbook --- docs/hero_create_mdbook.md | 177 +++++++++++++++++++++++++++++++++++++ 1 file changed, 177 insertions(+) create mode 100644 docs/hero_create_mdbook.md diff --git a/docs/hero_create_mdbook.md b/docs/hero_create_mdbook.md new file mode 100644 index 0000000..bcb7391 --- /dev/null +++ b/docs/hero_create_mdbook.md @@ -0,0 +1,177 @@ +

Create a New mdbook with Hero

+ +

Table of Contents

+ +- [Introduction](#introduction) +- [Prerequisites](#prerequisites) +- [Creating a New mdbook](#creating-a-new-mdbook) + - [Cloning the mdbook Repository](#cloning-the-mdbook-repository) + - [Directory Tree Example](#directory-tree-example) + - [Files and Directories Example](#files-and-directories-example) +- [Generating the mdbook Locally](#generating-the-mdbook-locally) +- [Pushing the Changes](#pushing-the-changes) +- [Generating the mdbook from a Remote Repository](#generating-the-mdbook-from-a-remote-repository) + +*** + +## Introduction + +We show how to build an mdbook using the [Hero tool](https://github.com/freeflowuniverse/crystallib/tree/development/cli/hero). + +For this guide, we will show how to add an mdbook to the TFGrid repository `info_tfgrid` on `git.ourworld.tf`. + +## Prerequisites + +Before proceeding further, make sure you read and completed the [guide on how to use Hero and mdbook](./hero_fullvm.md). + +## Creating a New mdbook + +Let's go through all the steps to create a new mdbook. We will call our book `new_mdbook`. + +### Cloning the mdbook Repository + +For this guide, we will add a book to `info_tfgrid`. For this reason, we first start to clone the repository. Note that this step can be done automatically by Hero, but it might be easier to do it manually for later steps, such as pushing changes with git. + +``` +mkdir -p /root/code/git.ourworld.tf/tfgrid +cd /root/code/git.ourworld.tf/tfgrid +git clone https://git.ourworld.tf/tfgrid/info_tfgrid +``` + +Once we've cloned the repository, we can make changes to the repository and then push it to `git.ourworld.tf` when we're ready. + +Before creating the new mdbook, let's have a look at how the overall directory tree will look like. + +### Directory Tree Example + +We first show the directory tree template to give an overview of the project. Without taking into account the other mdbooks within the repository, the overall directory tree would look like this: + +``` +├── books +│ └── new_mdbook +│ ├── SUMMARY.md +│ └── sync_production.sh +├── collections +│ └── new_mdbook +│ ├── .collection +│ ├── new_mdbook_example1.md +│ └── new_mdbook_example2.md +└── heroscript + └── new_mdbook + ├── book_collections.md + ├── context.md + └── sshkey.md +``` + +### Files and Directories Example + +Hero uses three main directories to build an mdbook `books`, `collections` and `heroscript`. Let's have a look at each of them. + +- `books` + - This directory contains the file `SUMMARY.md` of every mdbook as well as a script file called `sync_production.sh`. Each summary file is within the proper mdbook directory (here we have `new_mdbook`). + - In our case, we will have `books/new_mdbook/SUMMARY.md`. + - The summary file will point to the markdown files we want our mdbook populated with. + - We note that the SUMMARY.md file needs to point to a directory contained within the `collections` directory, as shown just below. + ``` + - [Example 1](new_mdbook/new_mdbook_example1.md) + - [Example 2](new_mdbook/new_mdbook_example2.md) + ``` + - The script file named `sync_production.sh` should contain the following content (make sure to adjust with the proper book name): + ``` + #!/bin/bash + rsync -rv ~/hero/www/info/new_mdbook/ root@info.ourworld.tf:/root/hero/www/info/new_mdbook/ + ``` +- `collections` + - This directory contains all the markdown files needed to build all the books in the repository. + - In our case, we will put two markdown files in the new collections named `new_mdbook` + - `collections/new_mdbook/new_mdbook_example1.md` + - `collections/new_mdbook/new_mdbook_example2.md` + - Note that each collections directory should contain a file called `.collection`. This file should be empty. + ``` + touch .collection + ``` +- `heroscript` + - This directory contains three files that are necessary for Hero to build the mdbook, `book_collections.md`, `context.md` and `sshkey.md` + - `context.md` sets the proper configuration for the mdbook using the command `configure` + - This file is the same throughout all the `info_tfgrid` repository. + ``` + !!books.configure + buildroot:'~/hero/var/mdbuild' + publishroot:'~/hero/www/info' + install:true + reset:false + ``` + - `sshkey.md` contains the private SSH key + - This file is the same throughout all the `info_tfgrid` repository. + ``` + !!sshagent.key_add + name:'books' + privkey:' + -----BEGIN OPENSSH PRIVATE KEY----- + b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAAAMwAAAAtzc2gtZW + QyNTUxOQAAACDXf9Z/2AH8/8a1ppagCplQdhWyQ8wZAieUw3nNcxsDiQAAAIhb3ybRW98m + 0QAAAAtzc2gtZWQyNTUxOQAAACDXf9Z/2AH8/8a1ppagCplQdhWyQ8wZAieUw3nNcxsDiQ + AAAEC+fcDBPqdJHlJOQJ2zXhU2FztKAIl3TmWkaGCPnyts49d/1n/YAfz/xrWmlqAKmVB2 + FbJDzBkCJ5TDec1zGwOJAAAABWJvb2tz + -----END OPENSSH PRIVATE KEY----- + ' + + ``` + - `book_collections.md` has many purposes + - It is used to generate the mdbook name + - It points the URL where the SUMMARY.md is located + - In the directory `books` as we've seen above + - It also point the URLs where the markdown files are located + - In the directory `collections` as we've seen above + ``` + !!book.generate name:'new_mdbook' title:'New mdbook' + url:'https://git.ourworld.tf/tfgrid/info_tfgrid/src/branch/main/books/new_mdbook' + + + !!doctree.add + url:'https://git.ourworld.tf/tfgrid/info_tfgrid/src/branch/main/collections/new_mdbook' + + ``` + +## Generating the mdbook Locally + +Once you've created all the necessary files for your mdbook, you can build the mdbook locally with Hero: + +``` +hero mdbook -p /root/code/git.ourworld.tf/tfgrid/info_tfgrid/heroscript/new_mdbook +``` + +Then you can open the mdbook locally: + +``` +hero mdbook -p /root/code/git.ourworld.tf/tfgrid/info_tfgrid/heroscript/new_mdbook -o +``` + +If you're using a remote VM for Hero, you can run the following line to see the book on your local browser. Check the [Hero Full VM guide](./hero_fullvm.md) for more information on this. + +``` +pushd /root/hero/www/info/new_mdbook/; python3 -m http.server 5173; popd; +``` + +## Pushing the Changes + +Once you've set the files and directories for your new mdbook and that you are satisfied with the result, you can push the changes to `git.ourworld.tf`. + +``` +git add . +git commit -m "added new book to info_tfgrid" +git push +``` + +## Generating the mdbook from a Remote Repository + +Once the changes are uploaded to the remote repository, you will be able to update the local repository and build the new mdbook using the remote repository URL: + +- Update the repository + ``` + hero mdbook -u https://git.ourworld.tf/tfgrid/info_tfgrid/src/branch/main/heroscript/new_mdbook -gr + ``` +- Build the book + ``` + hero mdbook -u https://git.ourworld.tf/tfgrid/info_tfgrid/src/branch/main/heroscript/new_mdbook -o + ``` \ No newline at end of file -- 2.40.1 From b844c50634a86fd52793c51808113f54ae9baa6c Mon Sep 17 00:00:00 2001 From: mik-tf Date: Fri, 26 Apr 2024 23:06:41 +0000 Subject: [PATCH 3/5] Update docs/hero_mdbook_fullvm.md --- docs/hero_mdbook_fullvm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/hero_mdbook_fullvm.md b/docs/hero_mdbook_fullvm.md index 7517a09..f85b93d 100644 --- a/docs/hero_mdbook_fullvm.md +++ b/docs/hero_mdbook_fullvm.md @@ -86,7 +86,7 @@ ssh-add /root/.ssh/books ## Install hero, crysallib and V ``` -curl https://raw.githubusercontent.com/freeflowuniverse/crystallib/development/scripts/installer_hero.sh > /tmp/build_hero.sh +curl https://raw.githubusercontent.com/freeflowuniverse/crystallib/development/scripts/build_hero.sh > /tmp/build_hero.sh bash /tmp/build_hero.sh ``` -- 2.40.1 From 214d8d9b2dfe8532596229ea6d3abe04b31a66f9 Mon Sep 17 00:00:00 2001 From: mik-tf Date: Fri, 26 Apr 2024 23:07:51 +0000 Subject: [PATCH 4/5] revert 5c87340c671f99500058ff06d174c372ddf963cc revert updated create mdbook --- docs/hero_create_mdbook.md | 177 ------------------------------------- 1 file changed, 177 deletions(-) delete mode 100644 docs/hero_create_mdbook.md diff --git a/docs/hero_create_mdbook.md b/docs/hero_create_mdbook.md deleted file mode 100644 index bcb7391..0000000 --- a/docs/hero_create_mdbook.md +++ /dev/null @@ -1,177 +0,0 @@ -

Create a New mdbook with Hero

- -

Table of Contents

- -- [Introduction](#introduction) -- [Prerequisites](#prerequisites) -- [Creating a New mdbook](#creating-a-new-mdbook) - - [Cloning the mdbook Repository](#cloning-the-mdbook-repository) - - [Directory Tree Example](#directory-tree-example) - - [Files and Directories Example](#files-and-directories-example) -- [Generating the mdbook Locally](#generating-the-mdbook-locally) -- [Pushing the Changes](#pushing-the-changes) -- [Generating the mdbook from a Remote Repository](#generating-the-mdbook-from-a-remote-repository) - -*** - -## Introduction - -We show how to build an mdbook using the [Hero tool](https://github.com/freeflowuniverse/crystallib/tree/development/cli/hero). - -For this guide, we will show how to add an mdbook to the TFGrid repository `info_tfgrid` on `git.ourworld.tf`. - -## Prerequisites - -Before proceeding further, make sure you read and completed the [guide on how to use Hero and mdbook](./hero_fullvm.md). - -## Creating a New mdbook - -Let's go through all the steps to create a new mdbook. We will call our book `new_mdbook`. - -### Cloning the mdbook Repository - -For this guide, we will add a book to `info_tfgrid`. For this reason, we first start to clone the repository. Note that this step can be done automatically by Hero, but it might be easier to do it manually for later steps, such as pushing changes with git. - -``` -mkdir -p /root/code/git.ourworld.tf/tfgrid -cd /root/code/git.ourworld.tf/tfgrid -git clone https://git.ourworld.tf/tfgrid/info_tfgrid -``` - -Once we've cloned the repository, we can make changes to the repository and then push it to `git.ourworld.tf` when we're ready. - -Before creating the new mdbook, let's have a look at how the overall directory tree will look like. - -### Directory Tree Example - -We first show the directory tree template to give an overview of the project. Without taking into account the other mdbooks within the repository, the overall directory tree would look like this: - -``` -├── books -│ └── new_mdbook -│ ├── SUMMARY.md -│ └── sync_production.sh -├── collections -│ └── new_mdbook -│ ├── .collection -│ ├── new_mdbook_example1.md -│ └── new_mdbook_example2.md -└── heroscript - └── new_mdbook - ├── book_collections.md - ├── context.md - └── sshkey.md -``` - -### Files and Directories Example - -Hero uses three main directories to build an mdbook `books`, `collections` and `heroscript`. Let's have a look at each of them. - -- `books` - - This directory contains the file `SUMMARY.md` of every mdbook as well as a script file called `sync_production.sh`. Each summary file is within the proper mdbook directory (here we have `new_mdbook`). - - In our case, we will have `books/new_mdbook/SUMMARY.md`. - - The summary file will point to the markdown files we want our mdbook populated with. - - We note that the SUMMARY.md file needs to point to a directory contained within the `collections` directory, as shown just below. - ``` - - [Example 1](new_mdbook/new_mdbook_example1.md) - - [Example 2](new_mdbook/new_mdbook_example2.md) - ``` - - The script file named `sync_production.sh` should contain the following content (make sure to adjust with the proper book name): - ``` - #!/bin/bash - rsync -rv ~/hero/www/info/new_mdbook/ root@info.ourworld.tf:/root/hero/www/info/new_mdbook/ - ``` -- `collections` - - This directory contains all the markdown files needed to build all the books in the repository. - - In our case, we will put two markdown files in the new collections named `new_mdbook` - - `collections/new_mdbook/new_mdbook_example1.md` - - `collections/new_mdbook/new_mdbook_example2.md` - - Note that each collections directory should contain a file called `.collection`. This file should be empty. - ``` - touch .collection - ``` -- `heroscript` - - This directory contains three files that are necessary for Hero to build the mdbook, `book_collections.md`, `context.md` and `sshkey.md` - - `context.md` sets the proper configuration for the mdbook using the command `configure` - - This file is the same throughout all the `info_tfgrid` repository. - ``` - !!books.configure - buildroot:'~/hero/var/mdbuild' - publishroot:'~/hero/www/info' - install:true - reset:false - ``` - - `sshkey.md` contains the private SSH key - - This file is the same throughout all the `info_tfgrid` repository. - ``` - !!sshagent.key_add - name:'books' - privkey:' - -----BEGIN OPENSSH PRIVATE KEY----- - b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAAAMwAAAAtzc2gtZW - QyNTUxOQAAACDXf9Z/2AH8/8a1ppagCplQdhWyQ8wZAieUw3nNcxsDiQAAAIhb3ybRW98m - 0QAAAAtzc2gtZWQyNTUxOQAAACDXf9Z/2AH8/8a1ppagCplQdhWyQ8wZAieUw3nNcxsDiQ - AAAEC+fcDBPqdJHlJOQJ2zXhU2FztKAIl3TmWkaGCPnyts49d/1n/YAfz/xrWmlqAKmVB2 - FbJDzBkCJ5TDec1zGwOJAAAABWJvb2tz - -----END OPENSSH PRIVATE KEY----- - ' - - ``` - - `book_collections.md` has many purposes - - It is used to generate the mdbook name - - It points the URL where the SUMMARY.md is located - - In the directory `books` as we've seen above - - It also point the URLs where the markdown files are located - - In the directory `collections` as we've seen above - ``` - !!book.generate name:'new_mdbook' title:'New mdbook' - url:'https://git.ourworld.tf/tfgrid/info_tfgrid/src/branch/main/books/new_mdbook' - - - !!doctree.add - url:'https://git.ourworld.tf/tfgrid/info_tfgrid/src/branch/main/collections/new_mdbook' - - ``` - -## Generating the mdbook Locally - -Once you've created all the necessary files for your mdbook, you can build the mdbook locally with Hero: - -``` -hero mdbook -p /root/code/git.ourworld.tf/tfgrid/info_tfgrid/heroscript/new_mdbook -``` - -Then you can open the mdbook locally: - -``` -hero mdbook -p /root/code/git.ourworld.tf/tfgrid/info_tfgrid/heroscript/new_mdbook -o -``` - -If you're using a remote VM for Hero, you can run the following line to see the book on your local browser. Check the [Hero Full VM guide](./hero_fullvm.md) for more information on this. - -``` -pushd /root/hero/www/info/new_mdbook/; python3 -m http.server 5173; popd; -``` - -## Pushing the Changes - -Once you've set the files and directories for your new mdbook and that you are satisfied with the result, you can push the changes to `git.ourworld.tf`. - -``` -git add . -git commit -m "added new book to info_tfgrid" -git push -``` - -## Generating the mdbook from a Remote Repository - -Once the changes are uploaded to the remote repository, you will be able to update the local repository and build the new mdbook using the remote repository URL: - -- Update the repository - ``` - hero mdbook -u https://git.ourworld.tf/tfgrid/info_tfgrid/src/branch/main/heroscript/new_mdbook -gr - ``` -- Build the book - ``` - hero mdbook -u https://git.ourworld.tf/tfgrid/info_tfgrid/src/branch/main/heroscript/new_mdbook -o - ``` \ No newline at end of file -- 2.40.1 From 3fc87e05a76667a44f984bbb64e374eb28d8670f Mon Sep 17 00:00:00 2001 From: Mik-TF Date: Sat, 27 Apr 2024 09:49:13 -0400 Subject: [PATCH 5/5] added docker hero mdbook steps --- docs/hero_mdbook_docker.md | 70 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 docs/hero_mdbook_docker.md diff --git a/docs/hero_mdbook_docker.md b/docs/hero_mdbook_docker.md new file mode 100644 index 0000000..88c75cf --- /dev/null +++ b/docs/hero_mdbook_docker.md @@ -0,0 +1,70 @@ +

Deploy mdBook with Hero on Docker

+ +

Table of Contents

+ +- [Introduction](#introduction) +- [Prerequisites](#prerequisites) +- [Steps](#steps) +- [Questions and Feedback](#questions-and-feedback) + +--- + +## Introduction + +We give the basic steps to use Hero on Docker to run and create mdBooks. + +## Prerequisites + +- Docker engine should be installed and running +- You need a git repository to work with (here we use **info_tfgrid**) + - Clone the hero mdbook repo on your local machine and note the path + +## Steps + +In this setup, we will have two temrinal windows running. One window running the **docker run** command and the other running the **docker exec** command. Steps are shown in details. + +Note that you will need to adjust the local path of the git repo and the docker path of the git repo. + +- On a terminal window, start Hero docker + ``` + sudo docker run --name herodocker -v /local/machine/path/to/git/repo:/docker/path/to/git/repo/ ghcr.io/scottyeager/hero:latest + ``` + - In our case, the docker path to the repo is the following + ``` + /root/code/git.ourworld.tf/tfgrid/info_tfgrid/ + ``` +- Open a new terminal window and enter the following. We will be working on this window now. + ``` + sudo docker exec -it herodocker bash + ``` +- Set git globally with a safe directory + ``` + git config --global --add safe.directory /root/code/git.ourworld.tf/tfgrid/info_tfgrid + ``` +- You can now use hero normally, e.g. with **projectinca**: + ``` + hero mdbook -u https://git.ourworld.tf/tfgrid/info_tfgrid/src/branch/main/heroscript/projectinca -gp + ``` +- To view the mdbook on your local browser, run the lines: + ``` + cd ~/hero/var/mdbuild/projectinca/ + mdbook serve -n 0.0.0.0 + ``` +- You should be able to view the rendered book at + ``` + http://172.17.0.2:3000/ + ``` +- To stop the container, exit the current window and run the following: + ``` + sudo docker stop herodocker + ``` + - The first terminal window that was running **docker run** should now have exited Docker. +- To start Hero after having stopped the container, run the following: + ``` + sudo docker start herodocker + ``` + - You can now run the previous line **docker exec** and continue your work. + +## Questions and Feedback + +If you have any questions or feedback, please let us know by either writing a post on the [ThreeFold Forum](https://forum.threefold.io/), or by chatting with us on the [TF Grid Tester Community](https://t.me/threefoldtesting) Telegram channel. \ No newline at end of file -- 2.40.1