Skip to content

Commit 9ba80b6

Browse files
andriypolanskiandriypolanski
authored
docs(selfhost): add website docs accuracy audit checklist (#1829) (#4070)
1 parent 3356fc6 commit 9ba80b6

6 files changed

Lines changed: 545 additions & 0 deletions

File tree

‎apps/gittensory-ui/src/lib/selfhost-docs-audit.ts‎

Lines changed: 246 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,246 @@
1+
/** Shared manifest for the self-host docs accuracy audit (#1829). Imported by the docs page and CI drift tests. */
2+
3+
export type SelfHostDocsPageLink = {
4+
title: string;
5+
path: string;
6+
routeFile: string;
7+
};
8+
9+
export const SELFHOST_DOCS_PAGES = [
10+
{
11+
title: "Quickstart",
12+
path: "/docs/self-hosting-quickstart",
13+
routeFile: "docs.self-hosting-quickstart.tsx",
14+
},
15+
{
16+
title: "Configuration",
17+
path: "/docs/self-hosting-configuration",
18+
routeFile: "docs.self-hosting-configuration.tsx",
19+
},
20+
{
21+
title: "GitHub App and Orb",
22+
path: "/docs/self-hosting-github-app",
23+
routeFile: "docs.self-hosting-github-app.tsx",
24+
},
25+
{
26+
title: "AI providers",
27+
path: "/docs/self-hosting-ai-providers",
28+
routeFile: "docs.self-hosting-ai-providers.tsx",
29+
},
30+
{
31+
title: "REES enrichment",
32+
path: "/docs/self-hosting-rees",
33+
routeFile: "docs.self-hosting-rees.tsx",
34+
},
35+
{
36+
title: "REES analyzer reference",
37+
path: "/docs/self-hosting-rees-analyzers",
38+
routeFile: "docs.self-hosting-rees-analyzers.tsx",
39+
},
40+
{ title: "RAG indexing", path: "/docs/self-hosting-rag", routeFile: "docs.self-hosting-rag.tsx" },
41+
{
42+
title: "Operations",
43+
path: "/docs/self-hosting-operations",
44+
routeFile: "docs.self-hosting-operations.tsx",
45+
},
46+
{
47+
title: "Backup and scaling",
48+
path: "/docs/self-hosting-backup-scaling",
49+
routeFile: "docs.self-hosting-backup-scaling.tsx",
50+
},
51+
{
52+
title: "Releases and images",
53+
path: "/docs/self-hosting-releases",
54+
routeFile: "docs.self-hosting-releases.tsx",
55+
},
56+
{
57+
title: "Release checklist",
58+
path: "/docs/self-hosting-release-checklist",
59+
routeFile: "docs.self-hosting-release-checklist.tsx",
60+
},
61+
{
62+
title: "Security",
63+
path: "/docs/self-hosting-security",
64+
routeFile: "docs.self-hosting-security.tsx",
65+
},
66+
{
67+
title: "Troubleshooting",
68+
path: "/docs/self-hosting-troubleshooting",
69+
routeFile: "docs.self-hosting-troubleshooting.tsx",
70+
},
71+
{
72+
title: "Docs accuracy audit",
73+
path: "/docs/self-hosting-docs-audit",
74+
routeFile: "docs.self-hosting-docs-audit.tsx",
75+
},
76+
] as const;
77+
78+
export type SelfHostDocsPath = (typeof SELFHOST_DOCS_PAGES)[number]["path"];
79+
80+
export type SelfHostSourceOfTruthRow = {
81+
topic: string;
82+
runtimeSources: readonly string[];
83+
docsPath: SelfHostDocsPath;
84+
driftGuard?: string;
85+
notes?: string;
86+
};
87+
88+
export type LooseDocsRow = {
89+
path: string;
90+
role: string;
91+
action: "keep" | "link-only" | "consolidated";
92+
websiteDocsPath?: SelfHostDocsPath;
93+
notes?: string;
94+
};
95+
96+
export const SELFHOST_SOURCE_OF_TRUTH_ROWS: readonly SelfHostSourceOfTruthRow[] = [
97+
{
98+
topic: "Compose stack and profiles",
99+
runtimeSources: ["docker-compose.yml", ".env.selfhost.example", ".env.example"],
100+
docsPath: "/docs/self-hosting-quickstart",
101+
notes: "Profiles (postgres, rees, observability, backup) and conservative first-boot defaults.",
102+
},
103+
{
104+
topic: "Env vars (exhaustive list)",
105+
runtimeSources: [
106+
"scripts/gen-selfhost-env-reference.mjs",
107+
"apps/gittensory-ui/src/lib/selfhost-env-reference.ts",
108+
],
109+
docsPath: "/docs/self-hosting-configuration",
110+
driftGuard: "selfhost-env-reference-script.test.ts",
111+
notes: "Generated from every env.SOMETHING read; npm run selfhost:env-reference:check in CI.",
112+
},
113+
{
114+
topic: "GitHub App manifest and setup wizard",
115+
runtimeSources: ["src/selfhost/setup-wizard.ts", ".env.selfhost.example"],
116+
docsPath: "/docs/self-hosting-github-app",
117+
driftGuard: "setup-wizard-docs-parity.test.ts",
118+
},
119+
{
120+
topic: "Activation and onboarding paths",
121+
runtimeSources: ["src/server.ts", "config/examples/global.gittensory.yml"],
122+
docsPath: "/docs/self-hosting-configuration",
123+
driftGuard: "docs-selfhost-activation-paths.test.ts",
124+
},
125+
{
126+
topic: "AI providers and unsafe Codex opt-in",
127+
runtimeSources: ["src/selfhost/ai-config.ts", "src/selfhost/ai.ts"],
128+
docsPath: "/docs/self-hosting-ai-providers",
129+
notes: "Codex PR review is fail-closed unless GITTENSORY_ENABLE_UNSAFE_CODEX_REVIEWER=1.",
130+
},
131+
{
132+
topic: "REES sidecar (compose profile)",
133+
runtimeSources: ["docker-compose.yml", "review-enrichment/Dockerfile"],
134+
docsPath: "/docs/self-hosting-rees",
135+
notes:
136+
"Analyzer metadata tables live on the REES analyzer page; generation is a separate roadmap item.",
137+
},
138+
{
139+
topic: "RAG / embeddings / Qdrant",
140+
runtimeSources: ["src/selfhost/qdrant-vectorize.ts", "docker-compose.yml"],
141+
docsPath: "/docs/self-hosting-rag",
142+
},
143+
{
144+
topic: "Update, rollback, and deploy scripts",
145+
runtimeSources: [
146+
"scripts/deploy-selfhost-image.sh",
147+
"scripts/deploy-selfhost-prebuilt.sh",
148+
"scripts/selfhost-post-update-check.sh",
149+
],
150+
docsPath: "/docs/self-hosting-operations",
151+
driftGuard: "docs-selfhost-update-rollback.test.ts",
152+
notes: "Migrations are forward-only; rollback is image-only.",
153+
},
154+
{
155+
topic: "Runner temp storage (multi-runner)",
156+
runtimeSources: ["docker-compose.yml"],
157+
docsPath: "/docs/self-hosting-operations",
158+
driftGuard: "docs-selfhost-operations-runner-tmpdir.test.ts",
159+
},
160+
{
161+
topic: "Backup, restore, and Litestream",
162+
runtimeSources: ["scripts/backup.sh", "scripts/verify-backup.sh", "scripts/backup-metrics.sh"],
163+
docsPath: "/docs/self-hosting-backup-scaling",
164+
driftGuard: "selfhost-backup-script.test.ts",
165+
},
166+
{
167+
topic: "Official orb-v* releases and GHCR tags",
168+
runtimeSources: [".github/workflows/release-selfhost.yml", "Dockerfile"],
169+
docsPath: "/docs/self-hosting-releases",
170+
notes:
171+
"Release workflow uploads source maps to Sentry; maps never ship inside the runtime image.",
172+
},
173+
{
174+
topic: "Release smoke matrix and image-contents audit",
175+
runtimeSources: ["scripts/smoke-selfhost.sh", "Dockerfile", ".dockerignore"],
176+
docsPath: "/docs/self-hosting-release-checklist",
177+
driftGuard: "docs-selfhost-release-checklist-event-names.test.ts",
178+
},
179+
{
180+
topic: "Sentry (opt-in, operator-owned DSN)",
181+
runtimeSources: ["src/selfhost/sentry.ts", "docker-compose.yml"],
182+
docsPath: "/docs/self-hosting-operations",
183+
driftGuard: "docs-selfhost-sentry-observability.test.ts",
184+
notes: "Sentry is off by default until SENTRY_DSN or SENTRY_DSN_FILE is set.",
185+
},
186+
{
187+
topic: "OTEL metrics/traces and Grafana dashboards",
188+
runtimeSources: [
189+
"src/selfhost/otel.ts",
190+
"scripts/validate-observability-configs.mjs",
191+
"grafana/dashboards/",
192+
"prometheus/rules/alerts.yml",
193+
],
194+
docsPath: "/docs/self-hosting-operations",
195+
driftGuard: "docs-selfhost-troubleshooting-metric-names.test.ts",
196+
notes: "Observability profile is optional; npm run selfhost:validate-observability in CI.",
197+
},
198+
{
199+
topic: "Security boundaries and secret handling",
200+
runtimeSources: ["src/selfhost/private-config.ts", "src/selfhost/preflight.ts"],
201+
docsPath: "/docs/self-hosting-security",
202+
},
203+
{
204+
topic: "Prometheus alert runbooks",
205+
runtimeSources: ["prometheus/rules/alerts.yml", "src/selfhost/metrics.ts"],
206+
docsPath: "/docs/self-hosting-troubleshooting",
207+
driftGuard: "docs-selfhost-troubleshooting-metric-names.test.ts",
208+
},
209+
] as const;
210+
211+
export const LOOSE_DOCS_ROWS: readonly LooseDocsRow[] = [
212+
{
213+
path: "CONVERGENCE_RUNBOOK.md",
214+
role: "Native-port convergence and hosted Cloudflare inventory (#1030 / #1826).",
215+
action: "keep",
216+
notes: "Intentional root runbook — not a duplicate of the website self-host section.",
217+
},
218+
{
219+
path: "config/examples/README.md",
220+
role: "Private config mount examples and template pointers.",
221+
action: "link-only",
222+
websiteDocsPath: "/docs/self-hosting-configuration",
223+
},
224+
{
225+
path: "review-enrichment/README.md",
226+
role: "REES analyzer developer notes for contributors.",
227+
action: "link-only",
228+
websiteDocsPath: "/docs/self-hosting-rees",
229+
},
230+
{
231+
path: "packages/gittensory-miner/DEPLOYMENT.md",
232+
role: "Miner CLI deployment — explicitly not the self-host review stack.",
233+
action: "keep",
234+
},
235+
] as const;
236+
237+
export const SELFHOST_DOCS_VALIDATION_COMMANDS = [
238+
"npm run docs:drift-check",
239+
"npm run selfhost:env-reference:check",
240+
"npm run selfhost:validate-observability",
241+
"npm run ui:lint",
242+
"npm run ui:typecheck",
243+
"npm run ui:test",
244+
"npm run ui:build",
245+
"npm run test:ci",
246+
] as const;

‎apps/gittensory-ui/src/routeTree.gen.ts‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ import { Route as DocsSelfHostingRagRouteImport } from './routes/docs.self-hosti
3535
import { Route as DocsSelfHostingQuickstartRouteImport } from './routes/docs.self-hosting-quickstart'
3636
import { Route as DocsSelfHostingOperationsRouteImport } from './routes/docs.self-hosting-operations'
3737
import { Route as DocsSelfHostingGithubAppRouteImport } from './routes/docs.self-hosting-github-app'
38+
import { Route as DocsSelfHostingDocsAuditRouteImport } from './routes/docs.self-hosting-docs-audit'
3839
import { Route as DocsSelfHostingConfigurationRouteImport } from './routes/docs.self-hosting-configuration'
3940
import { Route as DocsSelfHostingBackupScalingRouteImport } from './routes/docs.self-hosting-backup-scaling'
4041
import { Route as DocsSelfHostingAiProvidersRouteImport } from './routes/docs.self-hosting-ai-providers'
@@ -205,6 +206,12 @@ const DocsSelfHostingGithubAppRoute =
205206
path: '/self-hosting-github-app',
206207
getParentRoute: () => DocsRoute,
207208
} as any)
209+
const DocsSelfHostingDocsAuditRoute =
210+
DocsSelfHostingDocsAuditRouteImport.update({
211+
id: '/self-hosting-docs-audit',
212+
path: '/self-hosting-docs-audit',
213+
getParentRoute: () => DocsRoute,
214+
} as any)
208215
const DocsSelfHostingConfigurationRoute =
209216
DocsSelfHostingConfigurationRouteImport.update({
210217
id: '/self-hosting-configuration',
@@ -419,6 +426,7 @@ export interface FileRoutesByFullPath {
419426
'/docs/self-hosting-ai-providers': typeof DocsSelfHostingAiProvidersRoute
420427
'/docs/self-hosting-backup-scaling': typeof DocsSelfHostingBackupScalingRoute
421428
'/docs/self-hosting-configuration': typeof DocsSelfHostingConfigurationRoute
429+
'/docs/self-hosting-docs-audit': typeof DocsSelfHostingDocsAuditRoute
422430
'/docs/self-hosting-github-app': typeof DocsSelfHostingGithubAppRoute
423431
'/docs/self-hosting-operations': typeof DocsSelfHostingOperationsRoute
424432
'/docs/self-hosting-quickstart': typeof DocsSelfHostingQuickstartRoute
@@ -477,6 +485,7 @@ export interface FileRoutesByTo {
477485
'/docs/self-hosting-ai-providers': typeof DocsSelfHostingAiProvidersRoute
478486
'/docs/self-hosting-backup-scaling': typeof DocsSelfHostingBackupScalingRoute
479487
'/docs/self-hosting-configuration': typeof DocsSelfHostingConfigurationRoute
488+
'/docs/self-hosting-docs-audit': typeof DocsSelfHostingDocsAuditRoute
480489
'/docs/self-hosting-github-app': typeof DocsSelfHostingGithubAppRoute
481490
'/docs/self-hosting-operations': typeof DocsSelfHostingOperationsRoute
482491
'/docs/self-hosting-quickstart': typeof DocsSelfHostingQuickstartRoute
@@ -539,6 +548,7 @@ export interface FileRoutesById {
539548
'/docs/self-hosting-ai-providers': typeof DocsSelfHostingAiProvidersRoute
540549
'/docs/self-hosting-backup-scaling': typeof DocsSelfHostingBackupScalingRoute
541550
'/docs/self-hosting-configuration': typeof DocsSelfHostingConfigurationRoute
551+
'/docs/self-hosting-docs-audit': typeof DocsSelfHostingDocsAuditRoute
542552
'/docs/self-hosting-github-app': typeof DocsSelfHostingGithubAppRoute
543553
'/docs/self-hosting-operations': typeof DocsSelfHostingOperationsRoute
544554
'/docs/self-hosting-quickstart': typeof DocsSelfHostingQuickstartRoute
@@ -602,6 +612,7 @@ export interface FileRouteTypes {
602612
| '/docs/self-hosting-ai-providers'
603613
| '/docs/self-hosting-backup-scaling'
604614
| '/docs/self-hosting-configuration'
615+
| '/docs/self-hosting-docs-audit'
605616
| '/docs/self-hosting-github-app'
606617
| '/docs/self-hosting-operations'
607618
| '/docs/self-hosting-quickstart'
@@ -660,6 +671,7 @@ export interface FileRouteTypes {
660671
| '/docs/self-hosting-ai-providers'
661672
| '/docs/self-hosting-backup-scaling'
662673
| '/docs/self-hosting-configuration'
674+
| '/docs/self-hosting-docs-audit'
663675
| '/docs/self-hosting-github-app'
664676
| '/docs/self-hosting-operations'
665677
| '/docs/self-hosting-quickstart'
@@ -721,6 +733,7 @@ export interface FileRouteTypes {
721733
| '/docs/self-hosting-ai-providers'
722734
| '/docs/self-hosting-backup-scaling'
723735
| '/docs/self-hosting-configuration'
736+
| '/docs/self-hosting-docs-audit'
724737
| '/docs/self-hosting-github-app'
725738
| '/docs/self-hosting-operations'
726739
| '/docs/self-hosting-quickstart'
@@ -938,6 +951,13 @@ declare module '@tanstack/react-router' {
938951
preLoaderRoute: typeof DocsSelfHostingGithubAppRouteImport
939952
parentRoute: typeof DocsRoute
940953
}
954+
'/docs/self-hosting-docs-audit': {
955+
id: '/docs/self-hosting-docs-audit'
956+
path: '/self-hosting-docs-audit'
957+
fullPath: '/docs/self-hosting-docs-audit'
958+
preLoaderRoute: typeof DocsSelfHostingDocsAuditRouteImport
959+
parentRoute: typeof DocsRoute
960+
}
941961
'/docs/self-hosting-configuration': {
942962
id: '/docs/self-hosting-configuration'
943963
path: '/self-hosting-configuration'
@@ -1238,6 +1258,7 @@ interface DocsRouteChildren {
12381258
DocsSelfHostingAiProvidersRoute: typeof DocsSelfHostingAiProvidersRoute
12391259
DocsSelfHostingBackupScalingRoute: typeof DocsSelfHostingBackupScalingRoute
12401260
DocsSelfHostingConfigurationRoute: typeof DocsSelfHostingConfigurationRoute
1261+
DocsSelfHostingDocsAuditRoute: typeof DocsSelfHostingDocsAuditRoute
12411262
DocsSelfHostingGithubAppRoute: typeof DocsSelfHostingGithubAppRoute
12421263
DocsSelfHostingOperationsRoute: typeof DocsSelfHostingOperationsRoute
12431264
DocsSelfHostingQuickstartRoute: typeof DocsSelfHostingQuickstartRoute
@@ -1274,6 +1295,7 @@ const DocsRouteChildren: DocsRouteChildren = {
12741295
DocsSelfHostingAiProvidersRoute: DocsSelfHostingAiProvidersRoute,
12751296
DocsSelfHostingBackupScalingRoute: DocsSelfHostingBackupScalingRoute,
12761297
DocsSelfHostingConfigurationRoute: DocsSelfHostingConfigurationRoute,
1298+
DocsSelfHostingDocsAuditRoute: DocsSelfHostingDocsAuditRoute,
12771299
DocsSelfHostingGithubAppRoute: DocsSelfHostingGithubAppRoute,
12781300
DocsSelfHostingOperationsRoute: DocsSelfHostingOperationsRoute,
12791301
DocsSelfHostingQuickstartRoute: DocsSelfHostingQuickstartRoute,

‎apps/gittensory-ui/src/routes/docs.index.tsx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,7 @@ const AUDIENCES: Audience[] = [
7171
primary: { to: "/docs/beta-onboarding", label: "Beta onboarding" },
7272
links: [
7373
{ to: "/docs/maintainer-self-hosting", label: "Self-host reviews" },
74+
{ to: "/docs/self-hosting-docs-audit", label: "Self-host docs audit" },
7475
{ to: "/docs/maintainer-install-trust", label: "Install & trust guide" },
7576
{ to: "/docs/github-app", label: "GitHub App configuration" },
7677
{ to: "/docs/maintainer-workflow", label: "Maintainer workflow" },

‎apps/gittensory-ui/src/routes/docs.maintainer-self-hosting.tsx‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,12 @@ const SECTION_LINKS = [
100100
"Review not firing, REES silent, AI unavailable, RAG empty, queue stuck, and webhook failures.",
101101
to: "/docs/self-hosting-troubleshooting",
102102
},
103+
{
104+
title: "Docs accuracy audit",
105+
description:
106+
"Checklist mapping website docs to docker-compose, env, release, observability, and backup sources of truth.",
107+
to: "/docs/self-hosting-docs-audit",
108+
},
103109
] as const;
104110

105111
function MaintainerSelfHosting() {

0 commit comments

Comments
 (0)