Skip to content

Publishing and CI

This repository is published by CI, not by a local mkdocs build on the workstation.

Current Build Pipeline

Item Value
CI system Drone and Forgejo Actions
Pipeline files .drone.yml, .forgejo/workflows/docs.yml
Build image squidfunk/mkdocs-material:9 in Forgejo Actions
Output target /opt/podman/volumes/forgejo/runner-data/publish/kh3-it-infra-docs/site
Serving route https://docs.kh3group.com through Caddy to 192.168.2.20:30084

Pipeline Steps

The Forgejo Actions pipeline does the following:

  1. Installs the Python dependencies from requirements.txt
  2. Runs mkdocs build
  3. Copies the generated site/ directory into the mounted runner data volume
  4. Makes the published site writable by the target host process

The workflow is expected to run on a dedicated mkdocs runner label backed by the squidfunk/mkdocs-material:9 container image. The workflow mounts the rootless runner data directory into the job container so the built site lands on CT 101, not only inside the ephemeral job filesystem.

Publish Target

The Forgejo Actions workflow mounts the host path:

/opt/podman/volumes/forgejo/runner-data

and publishes the generated site under:

/opt/podman/volumes/forgejo/runner-data/publish/kh3-it-infra-docs/site

This is a rootless Podman runner artifact path on CT 101. The docs-static rootless Caddy container on CT 101 serves that directory read-only on host port 30084, and ingress Caddy on CT 103 proxies docs.kh3group.com to 192.168.2.20:30084.

Forgejo Runner Requirement

To make the Forgejo workflow publish successfully, the Forgejo runner on CT 101 needs to expose:

/opt/podman/volumes/forgejo/runner-data:/runner-data

and the runner config needs to allow /opt/podman/volumes/forgejo/runner-data as a valid volume.

The workflow now uses a shell-based checkout step, so the docs job no longer depends on Node.js. The build container needs to provide:

  • git
  • python3
  • python3 -m pip
  • mkdocs

The job container also declares:

  • /opt/podman/volumes/forgejo/runner-data:/runner-data

The publish step verifies that /runner-data appears in the container mount table before copying files. This prevents a successful job from writing only to an ephemeral /site directory when the runner rejects or omits the bind mount. It replaces the contents of /runner-data/publish/kh3-it-infra-docs/site.

Do not change the workflow back to Docker-era paths such as /root/nginx/data/mkdocs, /root/kh3-dev-site, or a Caddy CT-local static directory. Those paths are not the rootless runner artifact source of truth.

The current ubuntu-latest runner label is kept for other jobs.

The runner daemon must be started with its configuration file explicitly:

forgejo-runner daemon --config /config.yml

Setting CONFIG_FILE=/config.yml alone does not make Forgejo Runner load that file. If the config is not loaded, the runner ignores container.valid_volumes and logs that the publish source is not a valid volume.

What This Means Operationally

  • You do not need a local MkDocs install to publish this site.
  • The repo should be validated by the CI pipeline.
  • If the docs fail to publish, inspect the Forgejo job logs first.
  • Treat is not a valid volume, will be ignored as a publish failure even if the remaining job steps succeed.
  • If the generated site looks wrong, check the MkDocs config, the Markdown content, and the host path mounted by the pipeline.
  • .drone.yml
  • mkdocs.yml
  • requirements.txt
  • docs/current/index.md

Notes

  • Forgejo Actions can publish the site once the runner volume and the mkdocs runner label are both configured on the Docker host.
  • The build target should stay aligned with the rootless runner artifact path under /opt/podman/volumes/forgejo/runner-data/publish/kh3-it-infra-docs/site.
  • The public documentation URL is https://docs.kh3group.com.