Hero and mdbook on a Full VM

Table of Contents

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