ADR 0003: Documentation Delivery System

Status

Accepted

Context

Infrastructure documentation must be easily accessible to all authorized users and updated automatically to reflect the current state of the repository. The documentation is authored in Markdown and managed by mdBook. We need a robust pipeline to build and deliver this documentation to a private (internal server) destination.

Decision

We will implement an automated documentation delivery system with the following components:

• Source of Truth: The homelab repository on Codeberg.
• Build Engine: Forgejo Actions (using Forgejo Runners), triggered on pushes to the main branch (specifically for changes within the doc/ directory) or via manual trigger (workflow_dispatch).
• Single-Target Delivery:
  • Private: Automated deployment to an internal server at /var/www/doc via SSH/rsync for local access.
• Security: SSH-based deployment will use a dedicated, restricted user and an SSH key stored as a secret in the CI environment.
• Serving: Nginx will be used to serve the static HTML output on the internal server.

Consequences

• Automated Consistency: Documentation is guaranteed to be up-to-date with the repository’s main branch.
• Reduced Complexity: Focusing on a single, internal delivery target simplifies the pipeline and avoids dependency on external “best-effort” services.
• Standardized Process: Leverages Forgejo Actions, providing compatibility with GitHub Actions-style workflows and existing Runner infrastructure.
• Secret Management: Requires careful handling of SSH keys within the CI platform.