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)
- [Update the Book](#update-the-book)

---

## Introduction

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

You can then use a code editor, e.g. VSCodium, to change the files locally and use Hero docker to build and serve the book.

## Prerequisites

- [Docker Engine](https://docs.docker.com/engine/install/ubuntu/) should be installed and running on Linux
- [Docker Desktop](https://www.docker.com/products/docker-desktop/) should be installed and running on MacOS and Windows
- You need a git repository to work with (here we use **info_tfgrid**)
  - Clone the hero mdbook repo on your local machine (i.e. the host) and note the path

For basic info on Git, read [this documentation](https://manual.grid.tf/documentation/system_administrators/computer_it_basics/git_github_basics.html).

## Steps

We show the steps to use Hero with Docker.

Once you've set Hero Docker, you can adjust the files at the host path in a code editor and use the docker container to build and serve the book with Hero.

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, create the code repository on the local machine
  ```
  mkdir -p ~/code/git.ourworld.tf/tfgrid
  cd ~/code/git.ourworld.tf/tfgrid
  git clone https://git.ourworld.tf/tfgrid/info_tfgrid
  ```
- Start Hero docker
  ```
  sudo docker run --net=host --name herodocker -d -v ~/code/git.ourworld.tf/tfgrid:/root/code/git.ourworld.tf/tfgrid 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/
    ```
- Execute the Hero docker container
  ```
  sudo docker exec -it herodocker bash
  ```
- Change directory
  ```
  cd ~/code/git.ourworld.tf/tfgrid/info_tfgrid
  ```
- Git configuration
  - Set git lobally with a safe directory
    ```
    git config --global --add safe.directory /root/code/git.ourworld.tf/tfgrid/info_tfgrid
    ```
- You can now use Hero normally, e.g. with **tech**
  - With a URL:
    ```
    hero mdbook -u https://git.ourworld.tf/tfgrid/info_tfgrid/src/branch/main/heroscript/tech
    ```
  - With a path:
    ```
    hero mdbook -p /root/code/git.ourworld.tf/tfgrid/info_tfgrid/heroscript/tech
    ```
    - 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/tech/
  mdbook serve -n 0.0.0.0 --port 3005
  ```
- You should be able to view the rendered book at
  ```
  http://localhost:3005/
  ```
- To stop the container, exit the Docker container with `exit` and run the following:
    ```
    sudo docker stop herodocker
    ```
- 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
    ```
- To remove the container
  ```
  sudo docker rm herodocker
  ```

## Update the Book

You can use [VSCodium](https://manual.grid.tf/documentation/system_administrators/computer_it_basics/git_github_basics.html#vs-codium) to update files of the Mdbook.

- Open VSCodium
- Open the directory where the repo is located, e.g. 
  ```
  cd ~/code/git.ourworld.tf/tfgrid/info_tfgrid
  ```
- Make changes and save the files
- Redeploy Hero Mdbook
  - With a path:
    ```
    hero mdbook -p /root/code/git.ourworld.tf/tfgrid/info_tfgrid/heroscript/tech
    ```
  - With a URL (make sure to pull the changes with `git pull`):
    ```
    hero mdbook -u https://git.ourworld.tf/tfgrid/info_tfgrid/src/branch/main/heroscript/tech
    ```