From 7ea6889616473ba582d5a868c7c35c3a2b9d8bc7 Mon Sep 17 00:00:00 2001 From: Guanzhou Song Date: Tue, 25 Aug 2026 13:34:00 -0400 Subject: [PATCH] Fix blockers found by a cold-start test of the published page Two testers followed https://documentdb.io/docs/getting-started/packages/ verbatim in containers, with no prior knowledge of DocumentDB. The online path worked first try on both distributions. The air-gapped path could not be completed on either, and two smaller traps were found elsewhere. Air-gapped, DEB: the staging block calls dpkg-scanpackages, which lives in dpkg-dev and is not installed in ubuntu:24.04. The word dpkg-dev did not appear on the page. This failed silently in the worst way: the shell redirection still created a 0-byte Packages file, the && short-circuited before gzip, apt-get update on the target then exited 0, and the install failed an hour and 200 MB later with "E: Unable to locate package documentdb-18". Install dpkg-dev first, mirroring the RPM block, which already installs createrepo_c. Air-gapped, RPM: dnf aborts the entire transaction when any enabled repository is unreachable, and every RHEL-compatible image ships baseos, appstream and extras enabled. The bundle was read successfully and the install still failed with "Failed to download metadata for repo 'baseos'". Add --disablerepo='*' --enablerepo=documentdb-offline and explain the asymmetry with APT, which only warns and continues. Both offline install commands lacked -y while the online ones have it, so both aborted at the confirmation prompt in a container. Add it. "Smaller offline cases" listed the preconditions for skipping the bundle but omitted jq, which documentdb-common and documentdb-postgresql-tools both depend on. On an air-gapped host jq cannot be resolved from anywhere, so the case did not work as written. Also state which part of the install block to run when staging (up to apt update, not the final install), and note that what makes the bundle work is the index inside it, not the package files. Elsewhere: the blanket "in a container, drop sudo" advice breaks "sudo -u documentdb-local psql", which switches user rather than elevates -- dropping sudo there yields "bash: - : invalid option". And a bare -p makes mongosh prompt, so a non-interactive shell sends an empty password and fails with "MongoServerError: Invalid key"; that form was introduced by my own earlier change and is now inline. Finally, the non-systemd note promised that --restore stops the gateway. That is true on Debian/Ubuntu and false on a minimal RHEL image, because documentdb-setup finds the directly-started gateway with pgrep and procps-ng is not installed there. Verified both ways: on ubuntu:24.04 --restore logged "Stopping orphan (non-systemd) gateway daemon (pid 7770)" and the port went down; on rockylinux:9 it reported success while the gateway kept serving authenticated traffic. Note the prerequisite. That last one is a packaging bug rather than a documentation one -- documentdb-common declares neither procps-ng (RPM) nor procps (DEB) -- and is reported separately. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: f18515db-c52f-4197-aa50-d81359c7c763 Signed-off-by: Guanzhou Song --- app/services/articleService.ts | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/app/services/articleService.ts b/app/services/articleService.ts index d81dd51..99f3e89 100644 --- a/app/services/articleService.ts +++ b/app/services/articleService.ts @@ -133,7 +133,7 @@ ${buildRpmInstallCommand('rhel9', 'x86_64', '18')} For PostgreSQL 17, install \`documentdb-17\`; the \`documentdb\` meta package is equivalent to \`documentdb-18\`. For any other distribution, architecture or major, use the [Package Finder](/packages). > [!NOTE] -> In a container running as \`root\`, drop \`sudo\`. On Debian/Ubuntu also \`export DEBIAN_FRONTEND=noninteractive\` first, or \`tzdata\` prompts and the install hangs with no visible error. +> In a container running as \`root\`, drop the leading \`sudo\` (it is often not installed). Leave \`sudo -u \` commands alone — those switch user rather than elevate; run them as \`su -c '...'\` instead. On Debian/Ubuntu also \`export DEBIAN_FRONTEND=noninteractive\` first, or \`tzdata\` prompts and the install hangs with no visible error. > [!WARNING] > **On ARM, change three strings** — the commands above are written for x86_64. @@ -174,10 +174,10 @@ printf '%s\\n' '[mongodb-org-8.0]' 'name=MongoDB Repository' \\ sudo dnf install -y mongodb-mongosh \`\`\` -Then connect. Passing credentials as flags avoids URI escaping entirely: +Then connect. A bare \`-p\` makes \`mongosh\` **prompt** for the password, so pass it inline in scripts and CI — otherwise a non-interactive shell sends an empty password and fails with the unhelpful \`MongoServerError: Invalid key\`: \`\`\`bash -mongosh localhost:10260 -u admin -p --authenticationMechanism SCRAM-SHA-256 \\ +mongosh localhost:10260 -u admin -p '' --authenticationMechanism SCRAM-SHA-256 \\ --tls --tlsAllowInvalidCertificates --eval 'db.runCommand({ping: 1})' \`\`\` @@ -233,6 +233,9 @@ sudo systemctl stop documentdb-local@18.target **Without systemd** (containers, some dev images) the wizard starts the gateway directly and says so. \`systemctl\` will fail with *"System has not been booted with systemd"* — use \`documentdb-setup --status\` to inspect, re-run \`documentdb-setup\` to restart, \`--restore\` to stop. +> [!NOTE] +> On a **minimal RHEL-compatible image, install \`procps-ng\` first**. \`documentdb-setup\` locates the directly-started gateway with \`pgrep\`; without it \`--restore\` reports success while the gateway keeps serving, and a later re-run then fails with \`Port 10260 is already in use\`. Debian and Ubuntu images already ship \`procps\`. + ### Running SQL against the managed instance \`documentdb-setup\` runs a private instance as the \`documentdb-local\` user on a socket, so a bare \`psql\` will not find it: @@ -310,10 +313,11 @@ An air-gapped host has no route to PGDG either, and DocumentDB pulls PostgreSQL, ### Stage the bundle (connected machine) -With the same repositories configured as for an online install: +With the same repositories configured as for an online install — run the [Install](#install) command for your distribution **up to and including \`apt update\` / the \`dnf config-manager\` line, but not the final \`install\`**: \`\`\`bash # Debian / Ubuntu +sudo apt-get install -y dpkg-dev mapfile -t PKGS < <(apt-cache depends --recurse --no-recommends --no-suggests \\ --no-conflicts --no-breaks --no-replaces --no-enhances documentdb-18 \\ | grep '^[a-zA-Z0-9]' | sort -u) @@ -337,14 +341,14 @@ Expect ~200 packages / 200 MB (DEB) or ~270 / 170 MB (RPM), mostly PostGIS and G ### Install from the bundle (air-gapped target) -Copy \`bundle/\` across and point the package manager at it — the local index restores full dependency resolution: +Copy \`bundle/\` across — including the \`Packages\`/\`Packages.gz\` or \`repodata/\` index inside it, which is what makes the next step resolve — and point the package manager at it: \`\`\`bash # Debian / Ubuntu -echo "deb [trusted=yes] file:/path/to/bundle ./" \\ +echo "deb [trusted=yes] file:///path/to/bundle ./" \\ | sudo tee /etc/apt/sources.list.d/documentdb-offline.list sudo apt-get update -sudo apt install documentdb-18 +sudo apt install -y documentdb-18 \`\`\` \`\`\`bash @@ -352,16 +356,19 @@ sudo apt install documentdb-18 printf '%s\\n' '[documentdb-offline]' 'name=DocumentDB offline bundle' \\ 'baseurl=file:///path/to/bundle' 'enabled=1' 'gpgcheck=0' \\ | sudo tee /etc/yum.repos.d/documentdb-offline.repo -sudo dnf install documentdb-18 +sudo dnf install -y --disablerepo='*' --enablerepo=documentdb-offline documentdb-18 \`\`\` +> [!IMPORTANT] +> The \`--disablerepo\`/\`--enablerepo\` pair is not optional. DNF **aborts the whole transaction** if any enabled repository is unreachable, and every RHEL-compatible image ships \`baseos\`, \`appstream\` and \`extras\` enabled — so without it the install fails with \`Error: Failed to download metadata for repo 'baseos'\` even though your bundle is perfectly good. APT differs here: it only warns about unreachable sources and continues. + \`[trusted=yes]\` / \`gpgcheck=0\` accept the unsigned local directory. Upstream signatures were verified at staging time; \`sha256sum\` the transfer if it crosses an untrusted boundary. Then continue with **Set up and connect** above — \`documentdb-setup\` needs no network. ### Smaller offline cases -If the target already has PostgreSQL and the PGDG extension dependencies (\`postgresql-N-cron\`, \`-pgvector\`, \`-postgis-3\`), you do not need a bundle: +If the target already has PostgreSQL, the PGDG extension dependencies (\`postgresql-N-cron\`, \`-pgvector\`, \`-postgis-3\`) and \`jq\`, you do not need a bundle: - **Extension only, one file** — \`sudo apt install ./ubuntu24.04-postgresql-18-documentdb_0.116-0_amd64.deb\`. No gateway and no \`documentdb-setup\`. - **Full stack from the release assets** — pass all six files for your platform to a *single* \`apt install\` / \`dnf install\`. Local files resolve dependencies only against enabled repositories, so the meta package on its own fails with \`Depends: documentdb-18 ... but it is not installable\`.