129 lines
4.4 KiB
Markdown
129 lines
4.4 KiB
Markdown
<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)
|
|
- [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)
|
|
- [Serve and View the mdbook](#serve-and-view-the-mdbook)
|
|
- [Questions and Feedback](#questions-and-feedback)
|
|
|
|
***
|
|
|
|
## 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 we will access the mdbook output on a local browser. To manage the mdbook files, we will be using the remote explorer feature of either VSCodium or VSCode.
|
|
|
|
## Setting the Full VM
|
|
|
|
We start by deploying a full VM with WireGuard on the TFGrid.
|
|
|
|
To connect to the VM, we will be using a remote explorer.
|
|
|
|
### 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 upgrade 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)
|
|
```
|
|
- 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
|
|
```
|
|
|
|
## Serve and View the mdbook
|
|
|
|
- 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 --hostname 0.0.0.0 --port 3333
|
|
```
|
|
- To see the mdbook live, open a browser on the local machine and go to localhost:3333
|
|
|
|
## Questions and Feedback
|
|
|
|
If you have any questions or feedback, please let us know by either writing a post on the [ThreeFold Forum](https://forum.threefold.io/), or by chatting with us on the [TF Grid Tester Community](https://t.me/threefoldtesting) Telegram channel. |