117 lines
3.9 KiB
Markdown
117 lines
3.9 KiB
Markdown
<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
|
|
``` |