Vetrix Docs

Runbook Documentation

Operator runbooks for running and maintaining a gitvetrix.com server. Each section holds task-oriented procedures for a subsystem: how to operate it, what to check when it misbehaves, and how to recover it.

Sections

  • cicd/README.md — Operating the CI/CD runners and control plane: starting workers, draining nodes, and clearing stuck jobs.
  • search/README.md — Maintaining the search index: reindexing, draining the outbox, and recovering from index drift.
  • storage/README.md — Managing content-addressable storage and backups: capacity, retention, and restore procedures.
  • migrations/README.md — Applying and verifying database migrations during upgrades and recovering from a failed migration.
  • features/README.md — Enabling, configuring, and troubleshooting optional platform features.

Contributing — operator-manual guardrail

These pages are an operator manual. Before opening a pull request, run the manual doc-lint. The command below works from any directory inside a clone:

bash "$(git rev-parse --show-toplevel)/llm-documentation/runbook-docs/doc-lint.sh"

The script switches to the repository root itself and scans every tracked Markdown and YAML file, so a single run covers all five documentation sets. Each set holds an identical copy of the script; running any one of them lints the whole tree, so this is not a per-set lint.

The script fails — listing file:line — when an operator-manual rule is violated. The Docs Reviewer enforces the same rules:

  • Use gitvetrix.com as the only product host (the .test dev host is fine).
  • Refer to the platform as Vetrix; do not use the legacy product name.
  • Keep tracker IDs out of the prose.
  • Link to other pages with relative .md paths. A markdown link whose target is an absolute git-host URL (https://www.gitvetrix.com/... or https://gitvetrix.com/...) fails the lint, because it sends the reader out of the manual and into the repository file browser; this is checked case-insensitively across inline links, reference-style link definitions, bare autolinks (a URL wrapped only in < >, no square brackets), and angle-bracket-wrapped destinations, including a userinfo-prefixed form (e.g. https://user:token@ in front of the host). Bare-text host mentions, curl examples and code blocks are unaffected.
  • Write in present-tense operator-manual tone, without decision or history narration.

doc-lint.sh must pass before review.