updated docs for hero
This commit is contained in:
parent
76c820817c
commit
5a8f4886a0
@ -36,6 +36,7 @@ For this guide, we will add a book to `info_tfgrid`. For this reason, we first s
|
|||||||
mkdir -p /root/code/git.ourworld.tf/tfgrid
|
mkdir -p /root/code/git.ourworld.tf/tfgrid
|
||||||
cd /root/code/git.ourworld.tf/tfgrid
|
cd /root/code/git.ourworld.tf/tfgrid
|
||||||
git clone https://git.ourworld.tf/tfgrid/info_tfgrid
|
git clone https://git.ourworld.tf/tfgrid/info_tfgrid
|
||||||
|
cd 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.
|
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.
|
||||||
@ -47,10 +48,6 @@ Before creating the new mdbook, let's have a look at how the overall directory t
|
|||||||
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:
|
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
|
├── collections
|
||||||
│ └── new_mdbook
|
│ └── new_mdbook
|
||||||
│ ├── .collection
|
│ ├── .collection
|
||||||
@ -60,37 +57,37 @@ We first show the directory tree template to give an overview of the project. Wi
|
|||||||
└── new_mdbook
|
└── new_mdbook
|
||||||
├── book_collections.md
|
├── book_collections.md
|
||||||
├── context.md
|
├── context.md
|
||||||
└── sshkey.md
|
│ ├── SUMMARY.md
|
||||||
|
│ └── sync_production.sh
|
||||||
```
|
```
|
||||||
|
|
||||||
### Files and Directories Example
|
### 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.
|
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`
|
- `collections`
|
||||||
- This directory contains all the markdown files needed to build all the books in the repository.
|
- 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`
|
- 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_example1.md`
|
||||||
- `collections/new_mdbook/new_mdbook_example2.md`
|
- `collections/new_mdbook/new_mdbook_example2.md`
|
||||||
- Note that each collections directory should contain a file called `.collection`. This file should be empty.
|
- Note that each collections directory should contain a file called `.collection`. This file should be empty.
|
||||||
```
|
```
|
||||||
touch .collection
|
touch .collection
|
||||||
```
|
```
|
||||||
- `heroscript`
|
- `heroscript`
|
||||||
|
- 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/
|
||||||
|
```
|
||||||
- This directory contains three files that are necessary for Hero to build the mdbook, `book_collections.md`, `context.md` and `sshkey.md`
|
- 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`
|
- `context.md` sets the proper configuration for the mdbook using the command `configure`
|
||||||
- This file is the same throughout all the `info_tfgrid` repository.
|
- This file is the same throughout all the `info_tfgrid` repository.
|
||||||
@ -101,31 +98,15 @@ Hero uses three main directories to build an mdbook `books`, `collections` and `
|
|||||||
install:true
|
install:true
|
||||||
reset:false
|
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
|
- `book_collections.md` has many purposes
|
||||||
- It is used to generate the mdbook name
|
- It is used to generate the mdbook name
|
||||||
- It points the URL where the SUMMARY.md is located
|
- It points the URL where the SUMMARY.md is located
|
||||||
- In the directory `books` as we've seen above
|
- In the directory `heroscript`
|
||||||
- It also point the URLs where the markdown files are located
|
- It also point the URLs where the markdown files are located
|
||||||
- In the directory `collections` as we've seen above
|
- In the directory `collections` as we've seen above
|
||||||
```
|
```
|
||||||
!!book.generate name:'new_mdbook' title:'New mdbook'
|
!!book.generate name:'new_mdbook' title:'New mdbook'
|
||||||
url:'https://git.ourworld.tf/tfgrid/info_tfgrid/src/branch/main/books/new_mdbook'
|
url:'https://git.ourworld.tf/tfgrid/info_tfgrid/src/branch/main/heroscript/new_mdbook'
|
||||||
|
|
||||||
|
|
||||||
!!doctree.add
|
!!doctree.add
|
||||||
@ -138,16 +119,16 @@ Hero uses three main directories to build an mdbook `books`, `collections` and `
|
|||||||
Once you've created all the necessary files for your mdbook, you can build the mdbook locally with Hero:
|
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
|
hero mdbook -p $(pwd)/heroscript/new_mdbook
|
||||||
```
|
```
|
||||||
|
|
||||||
Then you can open the mdbook locally:
|
Then you can open the mdbook locally:
|
||||||
|
|
||||||
```
|
```
|
||||||
hero mdbook -p /root/code/git.ourworld.tf/tfgrid/info_tfgrid/heroscript/new_mdbook -o
|
hero mdbook -p $(pwd)/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.
|
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_mdbook_fullvm.md) for more information on this.
|
||||||
|
|
||||||
```
|
```
|
||||||
pushd /root/hero/www/info/new_mdbook/; python3 -m http.server 5173; popd;
|
pushd /root/hero/www/info/new_mdbook/; python3 -m http.server 5173; popd;
|
||||||
|
@ -5,7 +5,6 @@
|
|||||||
- [Introduction](#introduction)
|
- [Introduction](#introduction)
|
||||||
- [Prerequisites](#prerequisites)
|
- [Prerequisites](#prerequisites)
|
||||||
- [Steps](#steps)
|
- [Steps](#steps)
|
||||||
- [Questions and Feedback](#questions-and-feedback)
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@ -17,10 +16,13 @@ You can then use a code editor, e.g. VSCodium, to change the files locally and u
|
|||||||
|
|
||||||
## Prerequisites
|
## Prerequisites
|
||||||
|
|
||||||
- Docker engine should be installed and running
|
- [Docker engine](https://docs.docker.com/engine/install/ubuntu/) should be installed and running on Linux
|
||||||
|
- [Docker Desktop](https://www.docker.com/products/docker-desktop/) should be installed and running on MacOS and Windows
|
||||||
- You need a git repository to work with (here we use **info_tfgrid**)
|
- You need a git repository to work with (here we use **info_tfgrid**)
|
||||||
- Clone the hero mdbook repo on your local machine (i.e. the host) and note the path
|
- Clone the hero mdbook repo on your local machine (i.e. the host) and note the path
|
||||||
|
|
||||||
|
For basic info on Git, read [this documentation](https://manual.grid.tf/documentation/system_administrators/computer_it_basics/git_github_basics.html).
|
||||||
|
|
||||||
## Steps
|
## Steps
|
||||||
|
|
||||||
We show the steps to use Hero with Docker.
|
We show the steps to use Hero with Docker.
|
||||||
@ -77,8 +79,4 @@ Note that you will need to adjust the local path of the git repo and the docker
|
|||||||
- If you need to update the docker Hero image, run the following line:
|
- If you need to update the docker Hero image, run the following line:
|
||||||
```
|
```
|
||||||
docker pull ghcr.io/scottyeager/hero:latest
|
docker pull ghcr.io/scottyeager/hero:latest
|
||||||
```
|
```
|
||||||
|
|
||||||
## 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.
|
|
Loading…
Reference in New Issue
Block a user