Hero and mdbook on a Full VM

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

<h2>Table of Contents</h2>

- [Introduction](#introduction)
- [Prerequisites](#prerequisites)
- [Setting the Full VM](#setting-the-full-vm)
  - [Install cargo](#install-cargo)
  - [Install redis](#install-redis)
  - [Install pkg-config, gcc and libssl](#install-pkg-config-gcc-and-libssl)
- [Set Hero](#set-hero)
- [Generate the mdbook](#generate-the-mdbook)
- [Access the mdbook from your local machine with the SSH tunnel](#access-the-mdbook-from-your-local-machine-with-the-ssh-tunnel)

***

## Introduction

We show how to work with mdbook using 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 guide can be done locally or on a VM. It should be run as root. We show the steps for a full VM deployed on the TFGrid with WireGuard.

## Prerequisites

On the full VM, you will need to install the following:

- cargo
- redis
- gcc
- pkg-config
- libssl-dev

Steps will be shown to install those prerequisites.

## Setting the Full VM

- Deploy a full VM with WireGuard on the TFGrid
- Connect to the full VM with an SSH tunnel on port 3333 on both local and VM
    ```
    ssh -4 -L 3333:127.0.0.1:3333 root@10.20.4.2
    ```
- Preprare 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) # start the 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
    ```

## Access the mdbook from your local machine with the SSH tunnel

- 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 --port 3333 
    ```
- To see the mdbook live, open a browser on the local machine and go to localhost:3333