Skip to content

Documentation Site

Overview

Field Value
Purpose Serve the generated MkDocs site
Business function Publish the operational reference
Owner IT Operations
Criticality High
Static service image docker.io/library/caddy:2-alpine
Route docs.kh3group.com

Architecture

Forgejo Actions builds MkDocs and writes the generated site to the rootless runner data volume on CT 101. A rootless docs-static Caddy container serves that artifact directory read-only on 192.168.2.20:30084. Ingress Caddy on CT 103 terminates HTTPS for docs.kh3group.com and proxies to that backend.

Installation

Rootless Quadlet on CT 101:

/home/podsvc/.config/containers/systemd/docs-static.container

Configuration

  • Content mount: /opt/podman/volumes/forgejo/runner-data/publish/kh3-it-infra-docs/site:/srv:ro
  • Rootless Podman network: kh3-backend
  • CT 101 host port: 30084
  • Container listen port: 8080
  • Ingress route: docs.kh3group.com -> 192.168.2.20:30084
  • Caddy DNS-01 resolver: 192.168.2.2
  • Caddy DNS-01 propagation check: disabled with propagation_timeout -1

Operational Procedures

ssh kh3-pve 'pct exec 101 -- runuser -u podsvc -- env HOME=/home/podsvc XDG_RUNTIME_DIR=/run/user/2000 bash -lc "cd /home/podsvc && podman ps --filter name=docs-static"'
ssh kh3-pve 'curl -I http://192.168.2.20:30084/'
ssh kh3-pve 'curl -k -I --resolve docs.kh3group.com:443:192.168.2.3 https://docs.kh3group.com/'

Publishing replaces the contents of /opt/podman/volumes/forgejo/runner-data/publish/kh3-it-infra-docs/site without replacing that directory itself.

Rejected Approaches

Do not serve the MkDocs artifact path directly from ingress Caddy on CT 103. The generated files live on CT 101, and CT 103 cannot read that filesystem without adding a copy, sync, or network filesystem layer.

Do not copy the generated site from CT 101 to CT 103 on every deploy. That adds a second mutable publish location and makes deployment state harder to reason about. Keep the artifact on CT 101 and serve it there through docs-static.

Do not point Caddy DNS-01 propagation checks at public resolvers from the DMZ. Direct public DNS queries from CT 103 time out under the current policy.

Troubleshooting

  • Old content: check the CI job and file timestamps.
  • 403: check directory and file read permissions in the runner data volume.
  • 404: confirm index.html exists in the mounted path.
  • Backend unavailable: check docs-static.service in the podsvc user manager on CT 101.
  • Route unavailable: check the docs.kh3group.com block in Caddy on CT 103 and certificate issuance logs.
  • TLS issuance failure: Caddy on CT 103 cannot query public resolvers directly from the DMZ. Keep DNS-01 resolver checks pointed at Technitium 192.168.2.2, and do not reintroduce 1.1.1.1 1.0.0.1 there unless DMZ DNS policy changes.