From 9391ea20abe6de6c51f53212e6080e25826d5de8 Mon Sep 17 00:00:00 2001 From: pcone Date: Wed, 14 Feb 2024 18:47:55 -0500 Subject: [PATCH 1/2] added docs/fullvm guide --- README.md | 1 + docs/hero_mdbook_fullvm.md | 122 +++++++++++++++++++++++++++++++++++++ 2 files changed, 123 insertions(+) create mode 100644 docs/hero_mdbook_fullvm.md diff --git a/README.md b/README.md index 0a9efbc..864aa2f 100644 --- a/README.md +++ b/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 diff --git a/docs/hero_mdbook_fullvm.md b/docs/hero_mdbook_fullvm.md new file mode 100644 index 0000000..a1c1b95 --- /dev/null +++ b/docs/hero_mdbook_fullvm.md @@ -0,0 +1,122 @@ +

Hero and mdbook

+ +

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 show 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 \ No newline at end of file -- 2.40.1 From 904168926cabc06ae54070e4eac6098fc5bd0478 Mon Sep 17 00:00:00 2001 From: pcone Date: Wed, 14 Feb 2024 18:50:59 -0500 Subject: [PATCH 2/2] adjusted details --- docs/hero_mdbook_fullvm.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/hero_mdbook_fullvm.md b/docs/hero_mdbook_fullvm.md index a1c1b95..c6b2cc4 100644 --- a/docs/hero_mdbook_fullvm.md +++ b/docs/hero_mdbook_fullvm.md @@ -1,4 +1,4 @@ -

Hero and mdbook

+

Hero and mdbook on a Full VM

Table of Contents

@@ -7,10 +7,10 @@ - [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) + - [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) +- [Access the mdbook from your local machine with the SSH tunnel](#access-the-mdbook-from-your-local-machine-with-the-ssh-tunnel) *** @@ -32,7 +32,7 @@ On the full VM, you will need to install the following: - pkg-config - libssl-dev -Steps will be show to install those prerequisites. +Steps will be shown to install those prerequisites. ## Setting the Full VM @@ -70,7 +70,7 @@ Once you install cargo, all mdbook dependencies will be installed via the hero s apt-get install redis -y ``` -## Install pkg-config, gcc and libssl +### Install pkg-config, gcc and libssl - Install other packages ``` @@ -113,7 +113,7 @@ Once you install cargo, all mdbook dependencies will be installed via the hero s mdbook build ``` -### Access the mdbook from your local machine with the SSH tunnel +## 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) ``` -- 2.40.1