Self-hosting

Docs accuracy audit

Before a self-host release, use this checklist to confirm website docs still match runtime defaults. Each row links a docs page to the files and CI drift guards that must stay aligned.

Scope (#1829)

This page is the in-repo paper trail for the self-host docs audit under roadmap #1819. REES analyzer metadata generation is tracked separately on the REES roadmap — the analyzer reference page covers names and shapes; auto-generated metadata tables are out of scope here.

Website docs navigation

Self-hosting docs live on the website under Self-hosted reviews. Every child page below is linked from that index and from the maintainer docs hub.

Quickstart — apps/gittensory-ui/src/routes/docs.self-hosting-quickstart.tsx
Configuration — apps/gittensory-ui/src/routes/docs.self-hosting-configuration.tsx
GitHub App and Orb — apps/gittensory-ui/src/routes/docs.self-hosting-github-app.tsx
AI providers — apps/gittensory-ui/src/routes/docs.self-hosting-ai-providers.tsx
REES enrichment — apps/gittensory-ui/src/routes/docs.self-hosting-rees.tsx
REES analyzer reference — apps/gittensory-ui/src/routes/docs.self-hosting-rees-analyzers.tsx
RAG indexing — apps/gittensory-ui/src/routes/docs.self-hosting-rag.tsx
Operations — apps/gittensory-ui/src/routes/docs.self-hosting-operations.tsx
Backup and scaling — apps/gittensory-ui/src/routes/docs.self-hosting-backup-scaling.tsx
Releases and images — apps/gittensory-ui/src/routes/docs.self-hosting-releases.tsx
Release checklist — apps/gittensory-ui/src/routes/docs.self-hosting-release-checklist.tsx
Security — apps/gittensory-ui/src/routes/docs.self-hosting-security.tsx
Troubleshooting — apps/gittensory-ui/src/routes/docs.self-hosting-troubleshooting.tsx
Docs accuracy audit — apps/gittensory-ui/src/routes/docs.self-hosting-docs-audit.tsx

Source-of-truth checklist

When you change runtime behavior, update the docs page and extend the drift guard test when one exists. Env vars must stay aligned with npm run selfhost:env-reference; observability configs with npm run selfhost:validate-observability.

Topic	Runtime sources	Docs page	Drift guard
Compose stack and profiles Profiles (postgres, rees, observability, backup) and conservative first-boot defaults.	`docker-compose.yml` `.env.selfhost.example` `.env.example`	self-hosting-quickstart	—
Env vars (exhaustive list) Generated from every env.SOMETHING read; npm run selfhost:env-reference:check in CI.	`scripts/gen-selfhost-env-reference.mjs` `apps/gittensory-ui/src/lib/selfhost-env-reference.ts`	self-hosting-configuration	`test/unit/selfhost-env-reference-script.test.ts`
GitHub App manifest and setup wizard	`src/selfhost/setup-wizard.ts` `.env.selfhost.example`	self-hosting-github-app	`test/unit/setup-wizard-docs-parity.test.ts`
Activation and onboarding paths	`src/server.ts` `config/examples/global.gittensory.yml`	self-hosting-configuration	`test/unit/docs-selfhost-activation-paths.test.ts`
AI providers and unsafe Codex opt-in Codex PR review is fail-closed unless GITTENSORY_ENABLE_UNSAFE_CODEX_REVIEWER=1.	`src/selfhost/ai-config.ts` `src/selfhost/ai.ts`	self-hosting-ai-providers	—
REES sidecar (compose profile) Analyzer metadata tables live on the REES analyzer page; generation is a separate roadmap item.	`docker-compose.yml` `review-enrichment/Dockerfile`	self-hosting-rees	—
RAG / embeddings / Qdrant	`src/selfhost/qdrant-vectorize.ts` `docker-compose.yml`	self-hosting-rag	—
Update, rollback, and deploy scripts Migrations are forward-only; rollback is image-only.	`scripts/deploy-selfhost-image.sh` `scripts/deploy-selfhost-prebuilt.sh` `scripts/selfhost-post-update-check.sh`	self-hosting-operations	`test/unit/docs-selfhost-update-rollback.test.ts`
Runner temp storage (multi-runner)	`docker-compose.yml`	self-hosting-operations	`test/unit/docs-selfhost-operations-runner-tmpdir.test.ts`
Backup, restore, and Litestream	`scripts/backup.sh` `scripts/verify-backup.sh` `scripts/backup-metrics.sh`	self-hosting-backup-scaling	`test/unit/selfhost-backup-script.test.ts`
Official orb-v* releases and GHCR tags Release workflow uploads source maps to Sentry; maps never ship inside the runtime image.	`.github/workflows/release-selfhost.yml` `Dockerfile`	self-hosting-releases	—
Release smoke matrix and image-contents audit	`scripts/smoke-selfhost.sh` `Dockerfile` `.dockerignore`	self-hosting-release-checklist	`test/unit/docs-selfhost-release-checklist-event-names.test.ts`
Sentry (opt-in, operator-owned DSN) Sentry is off by default until SENTRY_DSN or SENTRY_DSN_FILE is set.	`src/selfhost/sentry.ts` `docker-compose.yml`	self-hosting-operations	`test/unit/docs-selfhost-sentry-observability.test.ts`
OTEL metrics/traces and Grafana dashboards Observability profile is optional; npm run selfhost:validate-observability in CI.	`src/selfhost/otel.ts` `scripts/validate-observability-configs.mjs` `grafana/dashboards/` `prometheus/rules/alerts.yml`	self-hosting-operations	`test/unit/docs-selfhost-troubleshooting-metric-names.test.ts`
Security boundaries and secret handling	`src/selfhost/private-config.ts` `src/selfhost/preflight.ts`	self-hosting-security	—
Prometheus alert runbooks	`prometheus/rules/alerts.yml` `src/selfhost/metrics.ts`	self-hosting-troubleshooting	`test/unit/docs-selfhost-troubleshooting-metric-names.test.ts`

Defaults, optional services, and experimental surfaces

Core stack (default): gittensory + Redis + SQLite on the mounted data volume; SELFHOST_DEPLOYMENT_MODE=dry-run in .env.selfhost.example.
Optional profiles: Postgres, REES sidecar, observability (Prometheus, Grafana, OTEL, Tempo, Loki), and backup — each documented on its concern page; none are required for a first healthy instance.
Sentry: opt-in and off by default — set an operator-owned SENTRY_DSN or mount SENTRY_DSN_FILE; see Operations.
AI / RAG / REES: off in the starter env until webhook delivery and deterministic review are verified; each has explicit enablement switches.
Operator-owned paths: gittensory-config/, gittensory-data, and secrets via .env or *_FILE mounts — never baked into images.

Loose docs consolidation

Root-level markdown outside the website must either link to the canonical website page or stay intentionally separate (convergence runbooks, contributor notes). Do not duplicate self-host operator instructions in a second place that will drift.

CONVERGENCE_RUNBOOK.md — Native-port convergence and hosted Cloudflare inventory (#1030 / #1826). — Intentional root runbook — not a duplicate of the website self-host section.
config/examples/README.md — Private config mount examples and template pointers. (canonical: /docs/self-hosting-configuration)
review-enrichment/README.md — REES analyzer developer notes for contributors. (canonical: /docs/self-hosting-rees)
packages/gittensory-miner/DEPLOYMENT.md — Miner CLI deployment — explicitly not the self-host review stack.

Validation commands

Run from the repo root before merging docs or cutting an orb release:

npm run docs:drift-check
npm run selfhost:env-reference:check
npm run selfhost:validate-observability
npm run ui:lint
npm run ui:typecheck
npm run ui:test
npm run ui:build
npm run test:ci

Spot-check documented shell commands against the current docker-compose.yml profiles and release scripts when you touch operator-facing prose — CI drift guards cover the highest-risk surfaces but not every copy-pasted example.