info_tfgrid/docs/hero_mdbook_fullvm.md

<h1>Hero and mdbook on a Full VM</h1>

<h2>Table of Contents</h2>

- [Introduction](#introduction)
- [Setting the Full VM](#setting-the-full-vm)
  - [Remote Explorer Access](#remote-explorer-access)
- [Set the SSH Key Pair](#set-the-ssh-key-pair)
- [Install Hero, Crystallib and V](#install-hero-crystallib-and-v)
- [Use Hero to Generate mdbooks](#use-hero-to-generate-mdbooks)
- [Troubleshooting](#troubleshooting)
  - [Fix the error: "cli execution error: Cannot pull repo..."](#fix-the-error-cli-execution-error-cannot-pull-repo)
  - [Fix: Git hangs at "Cloning into..."](#fix-git-hangs-at-cloning-into)
- [Distinctions between mdbook and hero mdbook](#distinctions-between-mdbook-and-hero-mdbook)

***

## Introduction

In this tutorial, we show all the steps to deploy an mdbook with the [Hero](https://github.com/freeflowuniverse/crystallib/tree/development/cli/hero) tool. 

For this guide, we show an example using the mdbook from the repository [info_tfgrid](https://git.ourworld.tf/tfgrid/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 also include some troubleshooting tips.

## 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](https://marketplace.visualstudio.com/items?itemName=ms-vscode.remote-repositories) and [VSCodium](https://open-vsx.org/extension/jeanp413/open-remote-ssh) 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, save it here: `/root/.ssh/books`
```
ssh-keygen
```
- Note the public key
```
cat /root/.ssh/books.pub
```
- Add the SSH public key on [git.ourworld.tf](https://git.ourworld.tf/user/settings/keys) and [github](https://github.com/settings/keys)
  - Optional: on git.ourworld.tf, verify the key. Make sure to put the proper token.
```
echo -n 'token' | ssh-keygen -Y sign -n gitea -f /root/.ssh/books
```
- Start the ssh agent
```
eval $(ssh-agent)
```
- Add private key to the agent
```
ssh-add /root/.ssh/books
```

## Install Hero, Crystallib and V

We install hero, Crystallib and V with a script.

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

## Use Hero to Generate mdbooks

We generate mdbooks with Hero.

Download the git repository from a URL:

- Download the repository
```
hero mdbook -u https://git.ourworld.tf/tfgrid/info_tfgrid/src/branch/main/heroscript/bookname -gp
```
  - The line above will clone the repository `info_tfgrid` at the path `/root/code/git.ourworld.tf/tfgrid`. The same result can be obtained by running the following lines:
    ```
    mkdir -p /root/code/git.ourworld.tf/tfgrid
    cd /root/code/git.ourworld.tf/tfgrid
    git clone https://git.ourworld.tf/tfgrid/info_tfgrid
    ```

For the next steps, you can either run the commands locally (with -p and the proper path) or remotely (with -u and the proper URL). Running the command locally is useful when you are doing changes to the mdbook and you want to test them before pushing the new files to the remote repository.

- Build the book
  - Note: add the parameter `-o` at the end of the line to open the book with your local browser
  - Option 1: Build the book with a URL
  ```
  hero mdbook -u https://git.ourworld.tf/tfgrid/info_tfgrid/src/branch/main/heroscript/bookname
  ```

  - Option 2: Build the book with a local path
  ```
  hero mdbook -p /path/to/tfgrid/info_tfgrid/src/branch/main/heroscript/bookname
  ```

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

If you are running hero on a VM with an SSH tunnel, to preview the mdbook on a local browser (via the file **index.html**), run the following command and open a browser with the URL **localhost:5173**. Make sure to replace `<book_name>` with the name of the book.
```
pushd /root/hero/www/info/<book_name>/;  python3 -m http.server 5173; popd; 
```

## Troubleshooting

### Fix the error: "cli execution error: Cannot pull repo..."

If you get the following error: "cli execution error: Cannot pull repo: /root/code/git.ourworld.tf/tfgrid/info_tfgrid because there are changes in the dir.", you can try the following as a fix:

```
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
```

## Distinctions between mdbook and hero mdbook

There are some distinctions between mdbook and hero mdbook. This is subject to change since hero is continually being improved.

- hero mdbook cannot use parentheses in tables of contents (e.g. in SUMMARY.md)
- hero mdbook uses the following include template:
    ```
    \!!wiki.include page:'collection_name:file_name.md'
    ```
- hero mdbook cannot parse codes with tabs or spaces
- list contents are parsed as paragraphs (e.g. defs, comments, text, links), they can't contain code blocks