docs(deployment): promote Docker to the lead path in `self-hosting` — it is how the platform actually ships

[os-zhuang]

Blocked-by: #8904

Card 04 of the deployment restructure. Maintainer ruling, 2026-08-15: 「平台通常用 docker 发布」.

⛔ Serial constraint — read before claiming

#8904 edits this same file (content/docs/deployment/self-hosting.mdx) to remove two prose links into the retiring Vercel page, at line 11 and line 424. Do not start until #8904 has merged, then re-read the file on the merged ref — line numbers in this card are from origin/main at filing time and #8904 will move them.

The defect

self-hosting.mdx (425 lines) presents three peer options:

• ## Option 1 — Bare Node.js (systemd) (line 50)
• ## Option 2 — Docker (official image) (line 88)
• ## Option 3 — Docker Compose with Postgres (line 220)

But Docker is not one option among three — it is how the platform ships. docker/Dockerfile and .github/workflows/docker-publish.yml build and publish the official image; bare Node is the minority path for people who have a reason to avoid containers. The page's ordering tells a new reader the opposite, and ordering is the strongest signal a docs page has.

The content itself is good — official image, Compose, Kubernetes (line 297), artifact-pinned boot (line 117), health checks, reverse proxy, scaling. This is a re-framing card, not a rewrite. Resist the urge to rewrite prose that is already correct; the win is that the right thing is first.

Scope

• Lead with the official Docker image. Compose and Kubernetes follow as deployment shapes of the same path, not as alternatives to it.
• Demote bare Node.js to the minority path with a sentence on when it is the right choice — do not delete it.
• Keep this page Axis A (platform runtime). The OS_ARTIFACT_URL section stays here as operational detail; card docs(deployment): rewrite publish-and-preview to name both ways a metadata app reaches the platform #8910 references it from the app side and will not move it.
• Verify the image name, tags and registry against docker/Dockerfile and .github/workflows/docker-publish.yml from the tree — do not copy any image reference out of the current prose without checking it. A stale image tag in the lead position is worse than the current ordering.

Do not touch other deployment pages; the index rewrite is card 05.

Docs-only, skip-changeset. Check Documentation Links (lint.yml) must stay green — this page's Related section is edited by #8904 first.

[os-zhuang]

Unblocked. #8904 merged (PR #8947), which was this card's only blocker. pm:blocked removed, back to pm:queue.

⚠️ Two things changed in self-hosting.mdx — re-read it on the merged ref before doing anything.

1. Line numbers moved. This card's body cites ## Option 1 — Bare Node.js (systemd) at ~50, ## Option 2 — Docker (official image) at ~88, ## Option 3 — Docker Compose with Postgres at ~220, Kubernetes at ~297, artifact-pinned boot at ~117. Those were read from origin/main before docs(deployment): retire the Vercel and ObjectQL-migration pages, re-point their inbound redirects, and fix the prose links into them #8947. Re-derive every one of them.

2. The two Vercel links are already gone, so do not go looking for them: line 424's Related-list bullet was deleted outright, and line 11's sentence was rewritten (It complements the platform-specific [Vercel guide](…) and assumes… → It assumes…). The Related section and the page's opening paragraph are therefore both one edit newer than this card's description of them.

Nothing else about the card changes: Docker still leads, bare Node still gets demoted rather than deleted, OS_ARTIFACT_URL still stays on this page as Axis A operational detail, and the image name/tags/registry still get verified against docker/Dockerfile and .github/workflows/docker-publish.yml from the tree rather than copied out of the existing prose.

---

Generated by Claude Code