Home

How it works

On startup, this application clones/pulls a target git repository containing mdBook documentation.
The repository should contain the "book.toml" file and "src" directory.
After pulling the repo it gets built using "mdbook build".
Finally, an HTTP server is started that serves the built book.

Afterward, based on the chosen update method, the repository gets pulled and updated.

At the end of the documentation, there are run commands for each update method.
It is recommended to read through the steps below to understand what to put where and why to make it work.

Setup

For ease of use, the application is available as a docker container.
Depending on the preferred update method you choose you will have to use different environment variables in the run command.

Update methods

You have to choose at least one of them.
However, it is usually unnecessary to enable multiple at the same time.

There are 2 update methods available:

1. Interval updates
2. Web hook updates

Interval updates

Updates happen on a set interval set in hours.
This is the simple method but it also doesn't update immediately when you push changes like the web-hook method.

Environment variables to control this method:

• USE_PULL_ON_INTERVAL='1' - Enables interval-based updates
• REPO_PULL_INTERVAL_HOURS='24' - Sets the interval in hours (24 by default if not set)

Web hook updates

Updates happen when the web hook receives a request.
You put the link to it into your repository and configure it to make a request to it on a push/commit event.

This method is more advanced but ensures that the documentation is always up-to-date since it gets updated the moment you push an update to it.
There is also no unnecessary pulling when nothing happens for a long time.

• USE_WEB_HOOK='1' - Enables webhook based updates

The web hook will listen on port 8080 at the "/hook" path

Target repository

To set the target repository you also define an environment variable.
Use the SSH repo link

• GIT_REPO_LINK='YOUR_GIT_REPO_LINK'

SSH Keys

The application uses SSH repo links so it needs a SSH key pair.
Public repositories are always accessible but in the case of private ones, you will need to add the generated public key to give it access.
The application only ever pulls the repository so only read-only access should be granted if possible.

When running the container you should bind the "/root/.ssh" directory to the host.
You can pick where the keys are stored, for an example I used the same path:

-v /root/.ssh:/root/.ssh

The keys get generated if they don't exist and the public key gets written out in the log.
You can see it using:

docker logs <containerId>

Or you can go into the key directory and copy it from there.

Ports

The application hosts the built book on the standard HTTP port 80.
The webhook - if used - listens on port 8080.

Make sure you forward the ports when running the container:

-p 80:80
-p 8080:8080

You can adjust the host side as needed.
If you require the application to bind to different ports due to a different networking structure - let me know, make an issue, it can be changed if needed.

Docker run commands

Adjust them to your configuration as explained above.

In case you want to use interval updates:

docker run -d --name mdBookGitAutoBuilder \
-e GIT_REPO_LINK='YOUR_GIT_REPO_LINK' \
-e USE_PULL_ON_INTERVAL='1' \
-e REPO_PULL_INTERVAL_HOURS='24' \
-v /root/.ssh:/root/.ssh \
-p 80:80 \
--restart unless-stopped \
lukassoo/mdbook-git-auto-build:latest

In case you want to use webhook updates:

docker run -d --name mdBookGitAutoBuilder \
-e GIT_REPO_LINK='YOUR_GIT_REPO_LINK' \
-e USE_WEB_HOOK='1' \
-v /root/.ssh:/root/.ssh \
-p 80:80 \
-p 8080:8080 \
--restart unless-stopped \
lukassoo/mdbook-git-auto-build:latest

(--restart unless-stopped - makes sure the container gets back up after a system reboot)

The web hook will listen on port 8080 at the "/hook" path