Hero and mdbook on a Full VM

Introduction
Setting the Full VM
Set Hero
Generate the mdbook
Serve and View the mdbook
Questions and Feedback

Introduction

In this tutorial, we show all the steps to deploy an mdbook with the hero tool.

For this guide, we show an example using the mdbook from the repository info_tfgrid. This setup can be done locally or on a VM. Note that it should be run as root.

We show the steps for a full VM deployed on the TFGrid with WireGuard. We use 10.20.4.2 as a WireGuard IP address. Adjust according to your own setup.

We will be using SSH to connect to the VM and we will access the mdbook output on a local browser. To manage the mdbook files, we will be using the remote explorer feature of either VSCodium or VSCode.

Setting the Full VM

We start by deploying a full VM with WireGuard on the TFGrid.

To connect to the VM, we will be using a remote explorer.

Remote Explorer Access

You can use the remote explorer feature of both VSCode and VSCodium to manage the mdbook.

Open the window Remote Explorer, click on Add New and write the following in the SSH config file:
```
Host 10.20.4.2
    HostName 10.20.4.2
    User root
```
Click on Connect to Host
Open the main /root directory
Right-click on the main window of the directory and select Open in Integrated Terminal
Update and upgrade the VM
```
apt update && apt upgrade -y
```

Install cargo

Once you install cargo, all mdbook dependencies will be installed via the hero script.

Install cargo rust for linux and mac (with default installation)
```
curl https://sh.rustup.rs -sSf | sh
```
Configure the current shell
```
source "$HOME/.cargo/env"
```

Install redis

Install redis on the VM

apt install lsb-release curl gpg
curl -fsSL https://packages.redis.io/gpg | gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb $(lsb_release -cs) main" | tee /etc/apt/sources.list.d/redis.list
apt-get update
apt-get install redis -y

Install pkg-config, gcc and libssl

Install other packages

apt install pkg-config -y
apt-get install gcc -y
apt install libssl-dev

Set Hero

Download the hero installation script

curl https://raw.githubusercontent.com/freeflowuniverse/crystallib/development/scripts/installer_hero.sh > /tmp/hero_install.sh

Run the script as root
```
bash /tmp/hero_install.sh
```
Run hero to confirm the installation is done properly
```
hero -help
```

Generate the mdbook

Start the ssh-agent
```
eval $(ssh-agent)
```

Generate the mdbook with hero

hero mdbook -u https://git.ourworld.tf/tfgrid/info_tfgrid/src/branch/main/heroscript

Change directory to where the book is built
```
cd /root/hero/var/mdbuild/book_name
```
You can then edit the content of the book as with any mdbook
```
mdbook build
```

Serve and View the mdbook

To serve on your local machine, make sure to use the same part as the one set in your SSH tunnel (here it's port 3333)
```
mdbook serve --hostname 0.0.0.0 --port 3333
```
To see the mdbook live, open a browser on the local machine and go to localhost:3333

Questions and Feedback

If you have any questions or feedback, please let us know by either writing a post on the ThreeFold Forum, or by chatting with us on the TF Grid Tester Community Telegram channel.

4.4 KiB Raw Blame History