README.md

@@ -15,6 +15,7 @@ hero -help
 source ~/.zprofile 
 ```
 
+There is also a quick guide on setting mdbook and hero on a full VM running on the TFGrid. Read the [docs](./docs/hero_mdbook_fullvm.md) for more information.
 
 ## to run the book
 

docs/hero_mdbook_fullvm.md

@@ -0,0 +1,122 @@
+<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