info_tfgrid/docs/hero_mdbook_fullvm.md

Hero and mdbook on a Full VM

Table of Contents

• Introduction
• Setting the Full VM
  • Remote Explorer Access
• Set the SSH Key Pair
• Install hero, crysallib and V
• Use Hero to Generate mdbooks
• Troubleshooting
  • Fix the error: "cli execution error: Cannot pull repo: /root/code/git.ourworld.tf/tfgrid/info_tfgrid because there are changes in the dir."
  • Fix: Git hangs at "Cloning into..."

---

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 to create an SSH tunnel between the local machine and the VM. This will allow the mdbook output to be displayed on a local browser.

To manage the mdbook files, we will be using the remote explorer feature of either VSCodium or VSCode.

We include some troubleshooting tips from testing the installation.

Setting the Full VM

We start by deploying a full VM with WireGuard on the TFGrid. We also set an SSH tunnel.

• Deploy a full VM with WireGuard on the TFGrid
• Set an SSH tunnel, on port 5173 for both local and VM

  ssh -4 -L 5173:127.0.0.1:5173 root@10.20.4.2
  

Instead of working on the SSH tunnel terminal window, we will be using the remote explorer feature of a source-code editor.

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 prepare the VM

  apt update && apt install curl -y && apt install openssh-client -y
  

Set the SSH Key Pair

• Generate an SSH key pair
  • To make it work with info_tfgrid, use books for the filename

ssh-keygen # save in /root/.ssh/books

• Note the public key

cat ~/.ssh/books.pub

• Add the SSH public key on git.ourworld.tf and github
  • Optional: on git.ourworld.tf, verify the key

echo -n 'token' | ssh-keygen -Y sign -n gitea -f /path/to/private/key

• Start the ssh agent

eval $(ssh-agent)

• Add private key to the agent

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
bash /tmp/build_hero.sh

Use Hero to Generate mdbooks

• You can download the repository.

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

• To open the mdbook on your local browser:

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

Note: In both cases, make sure to replace bookname by the name of your book, e.g. test.

To see the mdbook online on a local browser (via the file index.html), run the following command and open a browser with the URL localhost:5173:

pushd /root/hero/www/info/tfgrid/;  python3 -m http.server 5173; popd; 

Troubleshooting

Fix the error: "cli execution error: Cannot pull repo: /root/code/git.ourworld.tf/tfgrid/info_tfgrid because there are changes in the dir."

Remove then rerun the command

rm -r /root/code/git.ourworld.tf/tfgrid/info_tfgrid

Fix: Git hangs at "Cloning into..."

Run this command to fix this issue:

git config --global credential.provider generic

If it happens another time, you can try to download it manually:

mkdir -p /root/code/git.ourworld.tf/tfgrid && cd $_
git clone https://git.ourworld.tf/tfgrid/info_tfgrid