Skip to content

docs(selfhost): audit website docs against runtime defaults #1829

Description

@JSONbored

Parent: #1819

Context

The self-host documentation now lives in the website docs surface, with dedicated pages for maintainer self-hosting, configuration, GitHub App/Orb, AI providers, REES, RAG, operations, backup/scaling, releases/images, security, and troubleshooting.

Before official release, those docs need an accuracy audit against the actual Docker Compose defaults, .env.example, runtime behavior, dashboard provisioning, release workflow, and security posture.

REES analyzer metadata generation is tracked separately under the REES roadmap; this issue should cover the rest of the self-host docs surface.

Requirements

  • Audit website docs against current docker-compose.yml, .env.example, release workflow, Dockerfile, Sentry/OTEL runtime, backup scripts, and dashboard provisioning.
  • Remove or avoid loose standalone docs that duplicate website docs unless they are intentional root runbooks.
  • Confirm every documented env var has the right default, risk note, and prerequisite profile.
  • Confirm update, backup, release, Sentry, OTEL, Grafana, Orb, RAG, and AI provider docs match runtime behavior.
  • Keep secrets, private configs, local paths, auth material, and deployment-specific values out of docs.
  • Make docs clear about what is optional, what is enabled by default, what is operator-owned, and what is experimental.

Deliverables

  • Docs accuracy checklist with source-of-truth links to runtime files.
  • Website docs updates for any drift found outside REES analyzer metadata.
  • Docs navigation audit to ensure self-hosting is easy to find from maintainer docs.
  • Removal or consolidation plan for any stale loose docs.
  • Validation commands for docs/UI build.

Acceptance criteria

  • A new maintainer can follow website docs without relying on private chat context or random repo notes.
  • Runtime defaults and docs agree for core, backup, observability, release, and AI provider configuration.
  • Docs describe Sentry as opt-in with self-hoster-owned DSN by default.
  • No loose docs duplicate the website docs in a way that will drift.

Validation

  • Run docs/UI lint, typecheck, and build where relevant.
  • Spot-check each documented command against the current compose/release files.
  • Confirm docs navigation contains the self-hosting section and child pages.

Ownership

Maintainer-only. No gittensor:* labels.

Metadata

Metadata

Assignees

No one assigned

    Labels

    gittensor:featureGittensor-scored feature linked to a feature issue — scores a 0.25x multiplier.

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions