Restructure the packages quick start: fix ARM commands, add offline install, cut 42%

[guanzhousongmicrosoft]

Fixes an architecture bug in the install commands, adds offline guidance, and restructures the page around the install command after a clarity review.

---

1. ARM hosts get confusing errors

The Package Finder is architecture-aware and the command builders interpolate the selected architecture correctly — tests already cover amd64/arm64 and x86_64/aarch64. The static prose beneath them is rendered once with amd64/x86_64 and carried no arch-swap note, so a reader on an ARM host copies the example and hits an error that never mentions architecture:

• APT — arch=amd64 lets apt update succeed, then the install fails with documentdb-18 : Depends: postgresql-18-documentdb but it is not installable. The meta and stand-alone packages are Architecture: all and resolve either way, so only the extension package goes missing — which hides the cause.
• RPM — EL-9-x86_64 installs the wrong PGDG reporpm. The file name pgdg-redhat-repo-latest.noarch.rpm is identical for both architectures, so it installs silently, writes x86_64 URLs and keys, and the next dnf call fails with Bad GPG signature on pgdg-common while epel, crb and documentdb all verify normally.

Fixed with one substitution table listing the three strings that change, with the arch-agnostic forms (arch=$(dpkg --print-architecture), EL-9-$(uname -m)) as the primary advice — which is what PACKAGE-INSTALL.md in this repo already used. The published article had drifted from it.

The builders are deliberately untouched: dropping arch= would orphan aptArch and make the Package Finder's architecture selector meaningless.

2. Offline / air-gapped install

An air-gapped host has no route to PGDG either, and DocumentDB depends on PostgreSQL, pg_cron, pgvector and PostGIS — so downloading the release assets is not enough, and the page had nothing for that case.

Added a section covering one file, several files, and one command. Staging the dependency closure and indexing it (dpkg-scanpackages / createrepo_c) gives the target a real repository index, so the air-gapped install stays a single apt install documentdb-18 with full dependency resolution.

It also documents the trap that makes a bundle look complete and fail on arrival: apt-get install --download-only and a bare dnf download --resolve skip anything already installed on the staging machine. That is a reproduced failure, not a hypothetical — the first attempt staged 133 packages instead of 205 and died with:

postgresql-common : Depends: adduser but it is not installable
                    Depends: perl:any but it is not installable
E: Unable to correct problems, you have held broken packages.

3. Restructure after a clarity review

A review measured the page at 3,519 words with the first copyable command 617 words down, behind a package inventory, a version-tier table and a support matrix — a reference manual, not a quick start. It also found 544 words of blockquote (20% of all prose) and, notably, that the page used none of the GitHub-style alert markers the renderer supports, so all eight callouts rendered as the same blue box and the load-bearing crb warning was visually indistinguishable from Debian 13 trivia.

• Lead with the two install commands; move everything consulted-not-followed into one Other targets section.
• Delete Turn an extension-only install into a local mongosh endpoint (539 words) — a Rust-toolchain build guide (rustup, libssl-dev, su - postgres, a five-line $TERM comment) inside a packages quick start, repeating both the Docker command owned by the Docker Quick Start and the mongosh pointer given three times. One sentence survives, keeping the TERM=xterm trap.
• Troubleshooting: 13 bullets → 7, keyed by the error string a reader arrives with. Most of the old list restated earlier callouts verbatim.
• Tag callouts [!NOTE] / [!WARNING] / [!IMPORTANT] by severity.
• Put the mongosh flags form before the URI form, since it has no percent-encoding hazard.

Result

	Before	After
Rendered words	3,519	2,034 (−42%)
Words before first command	617	57
## sections	14	9

Verification

Every offline command was run verbatim as written, staging on a connected container and installing into one started with --network none (each target confirmed no DNS - host is offline first, with all repository sources removed):

Path	Closure	Result
DEB — stage ubuntu:24.04 → offline ubuntu:24.04	205 pkgs / 203 MB	apt install documentdb-18 → exit 0
RPM — stage rockylinux:9 → offline rockylinux:9	271 pkgs / 172 MB	dnf install documentdb-18 → exit 0
Single file — offline host with PGDG present	1 file	apt install ./…deb → exit 0

Repository facts checked against live endpoints: Architectures: amd64 arm64 in the Release file, both binary-*/Packages indices genuinely distinct, and EL-9-aarch64/pgdg-redhat-repo-latest.noarch.rpm → 200.

Anchors re-verified after the rename — every in-page link resolves against kebabCase(), and ## Offline / air-gapped install is deliberately unchanged so the v0.116-0 release notes keep linking to #offline-air-gapped-install. Note that slug is a single hyphen; GitHub's own slugifier produces a double, so the two are not interchangeable.

npm test 130 passed · eslint clean · tsc --noEmit clean · Next.js build green.

No shell command was altered — every flag in the generated install commands and the staging blocks is byte-identical.

Related

• Reduce the packages page to a release-asset reference, add arm64 and offline guidance docs#68 — the same fixes on the docs-repo page, reduced to a release-asset reference.
• The v0.116-0 release notes now link here for offline install, and the stale "repository hosting is not live yet" note has been removed.

[GuanzhouSong]

Superseded by #159, which is the same change opened from my personal account. Closing this one.

[guanzhousongmicrosoft]

Superseded by #159 — same change, opened from my personal account. Closing this one.