info_tfgrid/docs/hero_mdbook_docker.md

<h1>Deploy mdBook with Hero on Docker</h1>

<h2>Table of Contents</h2>

- [Introduction](#introduction)
- [Prerequisites](#prerequisites)
- [Steps](#steps)
- [Questions and Feedback](#questions-and-feedback)

---

## Introduction

We give the basic steps to use Hero on Docker to run and create mdBooks.

## Prerequisites

- Docker engine should be installed and running
- You need a git repository to work with (here we use **info_tfgrid**)
  - Clone the hero mdbook repo on your local machine and note the path

## Steps

In this setup, we will have two temrinal windows running. One window running the **docker run** command and the other running the **docker exec** command. Steps are shown in details.

Note that you will need to adjust the local path of the git repo and the docker path of the git repo.

- On a terminal window, start Hero docker
  ```
  sudo docker run --name herodocker -v /local/machine/path/to/git/repo:/docker/path/to/git/repo/ ghcr.io/scottyeager/hero:latest
  ```
  - In our case, the docker path to the repo is the following
    ```
    /root/code/git.ourworld.tf/tfgrid/info_tfgrid/
    ```
- Open a new terminal window and enter the following. We will be working on this window now.
  ```
  sudo docker exec -it herodocker bash
  ```
- Git configuration
  - Set git lobally with a safe directory
    ```
    git config --global --add safe.directory /root/code/git.ourworld.tf/tfgrid/info_tfgrid
    ```
  - Set your name and email to be able to push changes
    ```
    git config --global user.email "you@example.com"
    git config --global user.name "Your Name"
    ```
- You can now use Hero normally, e.g. with **projectinca**
  - With a URL:
    ```
    hero mdbook -u https://git.ourworld.tf/tfgrid/info_tfgrid/src/branch/main/heroscript/projectinca
    ```
  - With a path:
    ```
    hero mdbook -p /root/code/git.ourworld.tf/tfgrid/info_tfgrid/heroscript/projectinca
    ```
    - In this case, you can modify the mdbook on the local machine's git repo that you set in the prerequisites section and the changes will be shown on the docker path
- To view the mdbook on your local browser, run the lines:
  ```
  cd ~/hero/var/mdbuild/projectinca/
  mdbook serve -n 0.0.0.0
  ```
- You should be able to view the rendered book at
  ```
  http://172.17.0.2:3000/
  ```
- To stop the container, exit the current window and run the following:
    ```
    sudo docker stop herodocker
    ```
  - The first terminal window that was running **docker run** should now have exited Docker.
- To start Hero after having stopped the container, run the following:
  ```
  sudo docker start herodocker
  ```
  - You can now run the previous line **docker exec** and continue your work.
- If you need to update the docker Hero image, run the following line:
    ```
    docker pull ghcr.io/scottyeager/hero:latest
    ```

## 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.