Fix disproved day-2 instructions and split the Linux packages guide into three pages - #163
Open
GuanzhouSong wants to merge 8 commits into
Open
Fix disproved day-2 instructions and split the Linux packages guide into three pages#163GuanzhouSong wants to merge 8 commits into
GuanzhouSong wants to merge 8 commits into
Conversation
Adversarial testing of the published instructions found that the container substitution this page recommends does not work: su documentdb-local -c 'psql ...' This account is currently not available. documentdb-local is a service account with /usr/sbin/nologin as its shell, so su needs -s to override it. This note was added by an earlier fix round and was never executed -- it replaced one broken instruction with another. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: f18515db-c52f-4197-aa50-d81359c7c763 Signed-off-by: Guanzhou Song <guanzhou.song@gmail.com>
Five testers exercised the published packages against install, stop, restart, removal and reset, mostly in ways the happy path does not cover. Four instructions on this page turned out to be wrong or incomplete. All findings below were reproduced against 0.116 on Ubuntu 24.04 and RHEL 9. The non-systemd day-2 line said to re-run documentdb-setup to restart and --restore to stop. Neither is reliable. Re-running can hang forever after printing SUCCESS, because the restarted PostgreSQL inherits the caller's stdout and never releases it; interrupting it -- the only way out -- also stops the gateway, because it is nohup'd rather than setsid'd, so the service ends up down after a success message. And --restore --pg-version N skips the orphan sweep by design, printing SUCCESS while leaving a live endpoint accepting authenticated writes with its state file deleted. Only an unscoped --restore stops it, and on a multi-major host that stops every major. --status is also unreliable there: it infers active from anything holding port 10260. Replaced with an honest warning and a recommendation to prefer systemd, which was exercised the same way without failures. The hardening step said re-running documentdb-setup rewrites gateway.env. It does more than that: it silently reverts DOCUMENTDB_LISTEN_ADDR to a wildcard bind, re-exposing the endpoint on every interface with no warning, and --status never prints the bind address, so there is no supported way to notice. Say so, and give the grep to re-check. The extension-only note claimed unsupported majors get no gateway, no documentdb-setup and no systemd units. documentdb-setup --pg-version 16 returns 0 and builds a working appliance -- a 0.116 gateway over a 0.114 catalog -- with no warning. The same is true for any major whose documentdb-N package is absent, which leaves an install nothing owns and that a later autoremove can dismantle. The removal block gave a systemd-only stop, so non-systemd readers had no working stop at all. It also did not mention that --autoremove can reap the shared documentdb-common payload out from under another major that is still running, or that documentdb-local-reset reports success for majors it never touched. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: f18515db-c52f-4197-aa50-d81359c7c763 Signed-off-by: Guanzhou Song <guanzhou.song@gmail.com>
…mand A PM review of the rendered docs found the packages page had become an allocation problem rather than a verbosity one: 2,708 words on how the Linux install can go wrong, against 20 words on what the product is, with 63% of a "Quick Start" given over to operator content. It counted nine severity callouts on this page against one on the Docker page, which it rated the best on the site. Its sharpest point was that roughly 600 words were engineering backlog written in prose -- fix the thing and the paragraph deletes itself. The ARM warning was the clearest case. It existed only because the published example baked in amd64/x86_64, so it spent 172 words teaching readers to edit three strings, and repeated two error messages the page's own troubleshooting list already carried. Add an "auto" architecture to the command builders that resolves on the host, and use it for the published examples. The doc page now shells out for the architecture in both the APT sources line and the PGDG/CodeReady URLs, so the same command works unchanged on amd64 and arm64 and the warning is gone rather than reworded. The Package Finder still passes a literal architecture, because there the user has explicitly chosen one; both paths are covered by tests. Also compress the day-2 material added in this branch. Each note keeps what changes what a reader types and drops the forensics: the non-systemd block goes from a four-part verified-against-0.116 breakdown to one sentence naming the three commands that misreport, the listener-hardening note keeps the fact and the grep, the unsupported-major warning becomes two sentences of prose, and the removal note keeps the check and the multi-major hazard. 2,708 -> 2,335 words, nine callouts -> seven, 37 blockquoted lines -> 15. No fact was dropped; the ARM one was made unnecessary. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: f18515db-c52f-4197-aa50-d81359c7c763 Signed-off-by: Guanzhou Song <guanzhou.song@gmail.com>
guanzhousongmicrosoft
approved these changes
Aug 26, 2026
…fline pages The Linux Packages Quick Start had grown to 2,335 words and 7 callouts, mixing a first-install path with day-2 operations, air-gapped installs and platform caveats. A reader installing on a supported host had to skip most of the page to find the five commands they needed. Split it into three pages: - Linux Packages Quick Start (842 words) - install, set up, connect, verify. One callout, kept because it corrects a genuinely misleading default: the wizard binds all interfaces while the connect string says 127.0.0.1. - Linux Packages: Operations - securing the listener, services and paths, running SQL, upgrading, removal, non-systemd hosts, known issues in 0.116. - Linux Packages: Offline Install - staging a dependency closure and installing on an air-gapped target. All three are registered in getAllArticlePaths and the Getting Started sidebar, so neither new page is reachable only through in-content links. No install instruction changed; this is a reorganisation of existing text.
GuanzhouSong
changed the title
Four independent product reviews of the split-out quick start converged on the same verdict: the page was still too long for what it now owns, and the excess sat entirely after the success moment. Their targets were 500-600 words against 842. This applies the points all four agreed on. Cut: - "Other targets" (115 words) - it restated the intro and duplicated the Package Finder, which is the single source of truth for the matrix. - Troubleshooting from 8 bullets to 4, keeping only errors reachable from this page's own commands. Moved to the operations page (nothing lost): - Debian 11/13, PGDG GPG-arch and container bullets, under a new Troubleshooting section. - The db.version()/buildInfo caveat, which ended the page on a prohibition directly under its own success line. - The --pg-version foot-gun and the CI password flags, both day-2 concerns. Fixed: - The connect command used --eval, which exits, and the next block assumed an interactive session. Two reviewers hit the backtrack and a third narrowly avoided it. The sibling Docker page already opens an interactive shell; this now matches, and shows the returned document. - The security callout claimed "the connect string below says 127.0.0.1" while the connect string said localhost:10260. Trimmed to two lines, action first. Added, because all four reviewers lost real time to it: - mongosh install commands for both distros. Every reviewer reached the verify step without a client and had to leave the page. Both commands verified in ubuntu:24.04 and rockylinux:9 containers (mongosh 2.10.0); the RPM repo uses $basearch rather than a hardcoded architecture. - That the wizard creates its own PostgreSQL instance, and that the install adds PGDG. Two reviewers stopped at "PostgreSQL 17 or 18" wondering whether they needed one already, or would lose the one they had. Result: 842 -> 683 words, of which 424 are prose. The Docker sibling is 665 words with 541 prose, so the packages page now carries less prose than the page it is benchmarked against, while covering an extra install step.
The active-state test used item.link.includes(file), a substring match. Any sibling whose slug starts with the current one also matched, so opening Linux Packages Quick Start highlighted all three of Linux Packages Quick Start, Linux Packages: Operations and Linux Packages: Offline Install. The bug was latent until this section gained slugs sharing a prefix. Every navigation link is already a full /docs/<section>/<file> path, so the exact comparison on the line above covers all of them and this clause is redundant as well as wrong. Kept as a filename fallback, but comparing the final path segment exactly: 'packages-operations' no longer matches 'packages'. Verified against the rendered HTML that exactly one sidebar entry carries the active class on each of packages, packages-operations, packages-offline, docker, nodejs-setup and the section index.
Getting Started should hold quick starts. Putting "Operating a package install" and "Offline / air-gapped install" in its sidebar made three of the seven entries variations on the same install, and pushed the other quick starts down the list. They now live in their own docs section, Linux Packages, which parallels DocumentDB Local: a quick start in Getting Started for the fast path, and a longer-form deployment guide in its own section for everything after that. - /docs/getting-started/packages quick start (unchanged URL) - /docs/linux-packages operating a package install - /docs/linux-packages/offline offline / air-gapped install The quick start links to both, so nothing becomes harder to find; it just stops competing with them for sidebar space. Sections were previously enumerated only from the cloned articles/ tree, which is gitignored and owned by the docs repo, so this adds a small virtualSections map for sections served from this file. getAllSections, getAllArticlePaths and getArticleNavigation consult it, and getArticleContent splices the section into the docs landing page, which is also cloned. Neither moved URL was ever published - both were added in this same unmerged PR, and documentdb.io/docs/getting-started/packages-operations returns 404 - so no redirects are needed. The quick start URL is unchanged. Verified: tsc clean, 132 tests pass, all three routes 200 with exactly one active sidebar entry each, every cross-page anchor resolves, and the old slugs now 404.
Three agents ran every command on the three Linux package pages verbatim, in containers, against the live documentdb.io repository. The quick start passed end to end on both Ubuntu 24.04 and Rocky 9. The other two pages did not. Each fix below was reproduced independently before being applied. Offline, blocker. The page said to configure repositories by running the quick start Install block "up to and including the dnf config-manager line". On RHEL the DocumentDB repository is written by the tee documentdb.repo line *after* that, so following the page literally produced an empty bundle: "Error: No package documentdb-18 available." Now says to run the whole block except the final install line. This also fixes two smaller problems with the same sentence: the block is a single && chain that cannot simply be stopped partway, and the APT block has two apt update lines, so "up to and including apt update" was ambiguous. Operations, log paths. Both documented log files are absent on a systemd host; the setup script only uses them in its non-systemd nohup fallback (confirmed at documentdb-setup:3808). Rows are now conditional and name the journalctl units. Operations, known issues. "On a systemd host none of them apply" was false. The status false-positive reproduces anywhere, and the missing ALTER EXTENSION documentdb_core UPDATE is absent from the setup script regardless of init system - it has only documentdb and documentdb_extended_rum at lines 3234 and 3241. The table now marks which rows affect any host. Operations, multiple majors. The claim that setup "will happily configure a major whose package is absent" is wrong for 0.116: there is an explicit guard at documentdb-setup:2037. Replaced with the real error, plus the --gateway-port requirement, which was missing and blocks every second major. Operations, wrong account. su failing on /usr/sbin/nologin was attributed to postgres, which actually has /bin/bash. It is documentdb-local that has nologin. Also corrected Debian 11: PGDG does ship PostgreSQL 18 there, what is missing is postgresql-18-postgis-3. Quick start, package count. "around 200 packages" measured 161 on Ubuntu and 165 on Rocky. Now "around 160 packages (about 140 MB)", with the offline page noting its larger closure counts packages already present on the staging host. Quick start, error strings. "has no installation candidate" is not what apt prints for documentdb-18. Replaced with the two real messages: "Unable to locate package documentdb-18" when the DocumentDB repository is missing, and "documentdb-18 : Depends: postgresql-18 but it is not installable" when PGDG was not added first. Offline, mongosh. The page handed readers to a verify step whose client is not in the bundle and cannot be fetched from an air-gapped host. Now says to stage it or verify with documentdb-setup --status.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this does
Two things, both driven by testing the 0.116-0 packages against a clean host and by product review of the resulting page.
1. Correct day-2 instructions that adversarial testing disproved
Several instructions on the Linux packages page did not survive contact with a real install. Fixed here, each verified in a container:
su <user> -cwas recommended for non-systemd hosts; it fails because thepostgresuser's shell is/usr/sbin/nologin. Replaced withsu -s /bin/bash.2. Restructure the Linux packages page
The page had grown to 2,335 words and 7 warning callouts, mixing a first-install path with day-2 operations, air-gapped installs and platform caveats. A reader installing on a supported host had to skip most of the page to reach the five commands they needed.
It is now three pages:
The quick start keeps exactly one callout, because it corrects a genuinely misleading default: the setup wizard binds all interfaces while the connect string shown says
127.0.0.1.All three pages are registered in
getAllArticlePaths()and in the Getting Started sidebar, so neither new page is reachable only through in-content links.Supporting change
packageInstall.tsgained anautoarchitecture that emits the shell substitutions fordpkg --print-architectureanduname -m. This let the arm64 warning paragraph be deleted rather than reworded, because the copy-paste command is now correct on both architectures. Two tests added; 132 pass.Verification
npx tsc --noEmitcleannpm test- 132 passed