Skip to content

Home / 🟠 AREAS / Knowledge Management / Playbook preview

Playbook preview

Check a change before it is pushed: MkDocs runs on ERATO in a throwaway container, and an SSH tunnel brings the site to the Mac at http://localhost:8002.

A push to main publishes the playbook, so every change is first looked at in the preview. Nothing is installed for it.

Start the preview

1. Start the container on ERATO

cd ~/LAB/PROJECTS/nd_Abitello/ABITELLO-playbook
docker run --rm --name abitello-playbook-preview \
  -p 127.0.0.1:8002:8000 -v "$PWD":/docs \
  --entrypoint sh squidfunk/mkdocs-material:9.8.0 \
  -c "pip install -q --root-user-action=ignore -r requirements.txt && mkdocs serve -a 0.0.0.0:8000 --livereload"

The server is ready when Serving on http://0.0.0.0:8000/ appears. Port 8002 keeps it apart from the other playbooks' previews (8000 and 8001), so all can run at once.

2. Open the tunnel on the Mac

ssh -N -L 8002:localhost:8002 erato

3. Open the browser

http://localhost:8002. The preview reloads itself when a file in docs/ or mkdocs.yml changes.

Check the build

Before a commit, the build must pass with no warning, because Cloudflare builds the same way and refuses a page that fails:

docker run --rm -v "$PWD":/docs --entrypoint sh squidfunk/mkdocs-material:9.8.0 \
  -c "pip install -q --root-user-action=ignore -r requirements.txt && mkdocs build --strict -d /tmp/site"

It has passed when it ends with Documentation built and no line starts with WARNING -.

Stop the preview

  • Tunnel: Ctrl+C on the Mac.
  • Container: Ctrl+C on ERATO, or docker stop abitello-playbook-preview.