From 825c60f3dc921bde178045e094101b105b2bf2fe Mon Sep 17 00:00:00 2001 From: Guanzhou Song Date: Tue, 25 Aug 2026 11:20:39 -0400 Subject: [PATCH 1/4] Note the arm64 substitutions in the package quick-start examples The Package Finder is architecture-aware and buildAptInstallCommand / buildRpmInstallCommand interpolate the selected architecture correctly -- tests already assert that for amd64/arm64 and x86_64/aarch64. The static prose beneath them, however, is rendered once with 'amd64' and 'x86_64' and carried no arch-swap note, even though the same article already tells readers to swap amd64 -> arm64 for release assets. Readers on ARM hosts copy the example and hit an error that never mentions architecture. Add a callout under each example: * APT -- arch=amd64 on an arm64 host lets `apt update` succeed and then 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 real cause. * RPM -- EL-9-x86_64 on an aarch64 host installs the wrong PGDG reporpm. The file name pgdg-redhat-repo-latest.noarch.rpm is identical for both architectures, so it installs without complaint, writes x86_64 repository URLs and keys, and the next dnf call fails with "Bad GPG signature" on pgdg-common while epel, crb and documentdb all verify normally. Each callout also gives the arch-agnostic form -- arch=$(dpkg --print-architecture) and EL-9-$(uname -m) -- which is what PACKAGE-INSTALL.md in this repository already uses. 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 | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/app/services/articleService.ts b/app/services/articleService.ts index cfc85b9..45d8981 100644 --- a/app/services/articleService.ts +++ b/app/services/articleService.ts @@ -179,6 +179,10 @@ ${buildAptInstallCommand('ubuntu24', 'amd64', '18')} For PostgreSQL 17 on the same host, install \`documentdb-17\` instead of \`documentdb-18\`. The \`documentdb\` meta package is equivalent to \`documentdb-18\`. +> **On arm64, swap \`arch=amd64\` → \`arch=arm64\`** in the \`documentdb.list\` line. The repository publishes both (\`Architectures: amd64 arm64\`), so nothing else in the command changes. To make the line arch-agnostic, use \`arch=$(dpkg --print-architecture)\` instead. +> +> Leaving \`amd64\` on an ARM host fails in a way that does not name the architecture: \`apt update\` succeeds, then the install reports \`documentdb-18 : Depends: postgresql-18-documentdb but it is not installable\`. The meta and stand-alone packages are \`Architecture: all\` and resolve fine; only the extension package is arch-specific, so it is the one that goes missing. + ### RPM example (RHEL-compatible 9, PostgreSQL 18) \`\`\`bash @@ -187,6 +191,10 @@ ${buildRpmInstallCommand('rhel9', 'x86_64', '18')} For PostgreSQL 17, install \`documentdb-17\`. The \`documentdb\` meta package is equivalent to \`documentdb-18\`. +> **On aarch64, swap \`EL-9-x86_64\` → \`EL-9-aarch64\`** in the PGDG repository RPM URL, and \`codeready-builder-for-rhel-9-x86_64-rpms\` → \`codeready-builder-for-rhel-9-aarch64-rpms\` in the fallback \`config-manager\` line. On EL8 the same swap applies to \`EL-8-x86_64\`. To make the URL arch-agnostic, use \`EL-9-$(uname -m)\` instead. +> +> PGDG ships a *separate* \`pgdg-redhat-repo\` package per architecture, and the file name \`pgdg-redhat-repo-latest.noarch.rpm\` is identical for both — so the wrong one installs without complaint. It writes x86_64 repository URLs and keys, and the next \`dnf\` call fails with \`Bad GPG signature\` on \`pgdg-common\` even though \`epel\`, \`crb\` and \`documentdb\` all verify normally. The signature error names the repository but never the architecture, so it reads like a broken mirror. + > **Why the \`crb\` line matters.** DocumentDB's extension depends on PostGIS, which pulls in \`gdal*-libs\`, which needs \`libqhull_r.so.7\` — and that library ships only in **CRB** (CodeReady Builder; \`powertools\` on EL8). If CRB is not enabled, \`dnf install\` fails with dozens of lines like \`nothing provides libqhull_r.so.7()(64bit) needed by gdal313-libs\`, naming GDAL but never the missing repository. Do not drop that line. ## Set up and connect From 618e5fcdd583ceb9841039ea07916189f2124bc0 Mon Sep 17 00:00:00 2001 From: Guanzhou Song Date: Tue, 25 Aug 2026 11:49:39 -0400 Subject: [PATCH 2/4] Add an offline / air-gapped install section to the packages guide A host with no route to the DocumentDB repository also has no route to PGDG, and the extension depends on PostgreSQL itself plus pg_cron, pgvector and PostGIS, which are PGDG packages. Downloading the release assets alone is therefore not enough, and the guide had nothing to say about that case. Document staging the full dependency closure on a connected machine and serving it to the target as a local repository, for both DEB and RPM. Because the target then has a real repository index, the air-gapped install stays a single `apt install documentdb-18` / `dnf install documentdb-18` with full dependency resolution rather than an ordered list of files. Smaller cases are covered too: the extension alone from one file, and the full stack from the six release assets. Call out 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, so a clean target dies with errors like "Depends: adduser but it is not installable". Use `apt-cache depends --recurse` and `dnf download --alldeps`, which ignore local install state. Verified on v0.116-0 with every command run verbatim, staging on a connected container and installing into one started with --network none: * DEB: closure 205 packages / 203 MB staged on ubuntu:24.04, then `apt install documentdb-18` on an offline ubuntu:24.04 -> exit 0. * RPM: closure 271 packages / 172 MB staged on rockylinux:9, then `dnf install documentdb-18` on an offline rockylinux:9 -> exit 0. * Single file: `apt install ./postgresql-18-documentdb_0.116-0_amd64.deb` on an offline host with the PGDG prerequisites present -> exit 0. The first attempt used --download-only and produced exactly the failure now documented (133 packages staged instead of 205), which is why it is called out rather than left as a footnote. 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 | 63 ++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) diff --git a/app/services/articleService.ts b/app/services/articleService.ts index 45d8981..6f3b1a7 100644 --- a/app/services/articleService.ts +++ b/app/services/articleService.ts @@ -197,6 +197,69 @@ For PostgreSQL 17, install \`documentdb-17\`. The \`documentdb\` meta package is > **Why the \`crb\` line matters.** DocumentDB's extension depends on PostGIS, which pulls in \`gdal*-libs\`, which needs \`libqhull_r.so.7\` — and that library ships only in **CRB** (CodeReady Builder; \`powertools\` on EL8). If CRB is not enabled, \`dnf install\` fails with dozens of lines like \`nothing provides libqhull_r.so.7()(64bit) needed by gdal313-libs\`, naming GDAL but never the missing repository. Do not drop that line. +## Offline / air-gapped install + +A host with no route to this repository also has no route to PGDG — and DocumentDB depends on PostgreSQL itself plus \`pg_cron\`, \`pgvector\` and PostGIS, which are PGDG packages. Downloading the DocumentDB release assets alone is not enough. Stage the whole dependency closure on a connected machine and carry it across. + +Run the staging step on a machine with the **same distribution, release and architecture** as the target; the closure is specific to all three. + +### Stage the bundle (connected machine) + +Configure the repositories exactly as in the examples above, then download the closure and index it: + +\`\`\`bash +# Debian / Ubuntu +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) +mkdir -p bundle && cd bundle +apt-get download "\${PKGS[@]}" +dpkg-scanpackages . /dev/null > Packages && gzip -k Packages +\`\`\` + +\`\`\`bash +# RHEL-compatible +sudo dnf install -y dnf-plugins-core createrepo_c +mkdir -p bundle +sudo dnf download --resolve --alldeps --destdir bundle documentdb-18 +createrepo_c bundle +\`\`\` + +> **Use the full-closure flags, not \`--download-only\`.** \`apt-get install --download-only\` and a bare \`dnf download --resolve\` skip anything already installed on the staging machine. The bundle looks complete and then fails on a clean target with errors like \`Depends: adduser but it is not installable\`. \`apt-cache depends --recurse\` and \`dnf download --alldeps\` ignore local install state, which is what you want here. + +Expect roughly 200 packages / 200 MB for the DEB closure and 270 packages / 170 MB for the RPM closure — mostly PostGIS and its GDAL dependencies. Two warnings from the DEB step are harmless: \`Download is performed unsandboxed as root\`, and a long \`dpkg-scanpackages: warning: Packages in archive but missing from override file\` list, which is just an artifact of passing \`/dev/null\` as the override file. + +### Install from the bundle (air-gapped target) + +Copy \`bundle/\` across and point the package manager at it. Because the target now has a real repository index, this is a single command with full dependency resolution — no ordered list of files: + +\`\`\`bash +# Debian / Ubuntu +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 +\`\`\` + +\`\`\`bash +# RHEL-compatible +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 +\`\`\` + +\`[trusted=yes]\` and \`gpgcheck=0\` tell the package manager to accept a local directory that has no repository signature of its own. The upstream signatures were verified when the bundle was staged; if it crosses an untrusted boundary, check the transfer with \`sha256sum\`. + +Then continue with **Set up and connect** below — \`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: + +- **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\`. They must go in one command: \`apt\` and \`dnf\` resolve dependencies only from repository indexes, so a dependency on a bare local file is unresolvable and the meta package on its own fails with \`Depends: documentdb-18 ... but it is not installable\`. That is not a defect in the packages — it happens to any local \`.deb\` or \`.rpm\` whose dependencies are not in an enabled repository. + ## Set up and connect Installing the packages puts files on disk; it does not create a database or start the endpoint. The setup wizard does that: From 2effa046cf7b84093981c280712c401cb2daa6ef Mon Sep 17 00:00:00 2001 From: Guanzhou Song Date: Tue, 25 Aug 2026 12:04:00 -0400 Subject: [PATCH 3/4] Tighten the architecture and offline callouts after a clarity review A documentation review measured 544 words of blockquote on this page -- 20% of all prose -- and singled out the two architecture callouts added earlier as the worst offenders at 204 words between them. Replace both with a single substitution table: three rows for the three strings that actually change on ARM, with the arch-agnostic forms as the primary advice so most readers need no decision at all. Both searchable error strings survive, so anyone who hits the symptom and googles it still lands here. The page also used none of the GitHub-style alert markers the renderer supports (app/components/Markdown.tsx handles [!NOTE], [!WARNING], [!IMPORTANT], [!TIP] and [!CAUTION] with distinct colours), so all eight callouts rendered as the same blue box and the load-bearing crb warning was visually indistinguishable from Debian 13 trivia. Tag the ARM callout [!WARNING], crb [!IMPORTANT] and the offline staging note [!NOTE]. Also cut the offline prose: merge the two-paragraph opener, drop the harmless-warnings trivia to a clause, and delete the defensive "that is not a defect in the packages" sentence, which changes nothing a reader types. 3,519 -> 3,239 rendered words. No shell command was altered -- every flag in the staging and install blocks is byte-identical, since those were verified by installing into containers with the network disabled. 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 | 37 ++++++++++++++++++---------------- 1 file changed, 20 insertions(+), 17 deletions(-) diff --git a/app/services/articleService.ts b/app/services/articleService.ts index 6f3b1a7..797e346 100644 --- a/app/services/articleService.ts +++ b/app/services/articleService.ts @@ -179,33 +179,35 @@ ${buildAptInstallCommand('ubuntu24', 'amd64', '18')} For PostgreSQL 17 on the same host, install \`documentdb-17\` instead of \`documentdb-18\`. The \`documentdb\` meta package is equivalent to \`documentdb-18\`. -> **On arm64, swap \`arch=amd64\` → \`arch=arm64\`** in the \`documentdb.list\` line. The repository publishes both (\`Architectures: amd64 arm64\`), so nothing else in the command changes. To make the line arch-agnostic, use \`arch=$(dpkg --print-architecture)\` instead. -> -> Leaving \`amd64\` on an ARM host fails in a way that does not name the architecture: \`apt update\` succeeds, then the install reports \`documentdb-18 : Depends: postgresql-18-documentdb but it is not installable\`. The meta and stand-alone packages are \`Architecture: all\` and resolve fine; only the extension package is arch-specific, so it is the one that goes missing. - ### RPM example (RHEL-compatible 9, PostgreSQL 18) \`\`\`bash ${buildRpmInstallCommand('rhel9', 'x86_64', '18')} \`\`\` -For PostgreSQL 17, install \`documentdb-17\`. The \`documentdb\` meta package is equivalent to \`documentdb-18\`. +For PostgreSQL 17, install \`documentdb-17\`. -> **On aarch64, swap \`EL-9-x86_64\` → \`EL-9-aarch64\`** in the PGDG repository RPM URL, and \`codeready-builder-for-rhel-9-x86_64-rpms\` → \`codeready-builder-for-rhel-9-aarch64-rpms\` in the fallback \`config-manager\` line. On EL8 the same swap applies to \`EL-8-x86_64\`. To make the URL arch-agnostic, use \`EL-9-$(uname -m)\` instead. +> [!WARNING] +> **On ARM, change three strings** — the commands above are written for x86_64. > -> PGDG ships a *separate* \`pgdg-redhat-repo\` package per architecture, and the file name \`pgdg-redhat-repo-latest.noarch.rpm\` is identical for both — so the wrong one installs without complaint. It writes x86_64 repository URLs and keys, and the next \`dnf\` call fails with \`Bad GPG signature\` on \`pgdg-common\` even though \`epel\`, \`crb\` and \`documentdb\` all verify normally. The signature error names the repository but never the architecture, so it reads like a broken mirror. +> | In | Replace | With | +> | --- | --- | --- | +> | APT \`documentdb.list\` line | \`arch=amd64\` | \`arch=$(dpkg --print-architecture)\` | +> | RPM PGDG URL | \`EL-9-x86_64\` | \`EL-9-$(uname -m)\` (same for \`EL-8-x86_64\`) | +> | RPM \`config-manager\` fallback | \`codeready-builder-for-rhel-9-x86_64-rpms\` | \`...-aarch64-rpms\` | +> +> Neither failure names the architecture. APT reports \`documentdb-18 : Depends: postgresql-18-documentdb but it is not installable\` — only the extension package is arch-specific, so it is the one that goes missing. DNF reports \`Bad GPG signature\` on \`pgdg-common\`, because PGDG ships a separate reporpm per architecture under an identical file name. -> **Why the \`crb\` line matters.** DocumentDB's extension depends on PostGIS, which pulls in \`gdal*-libs\`, which needs \`libqhull_r.so.7\` — and that library ships only in **CRB** (CodeReady Builder; \`powertools\` on EL8). If CRB is not enabled, \`dnf install\` fails with dozens of lines like \`nothing provides libqhull_r.so.7()(64bit) needed by gdal313-libs\`, naming GDAL but never the missing repository. Do not drop that line. +> [!IMPORTANT] +> **Do not drop the \`crb\` line.** PostGIS pulls in \`gdal*-libs\`, which needs \`libqhull_r.so.7\`, and that ships only in CRB (\`powertools\` on EL8). Without it \`dnf install\` fails with \`nothing provides libqhull_r.so.7()(64bit)\`, naming GDAL but never the missing repository. ## Offline / air-gapped install -A host with no route to this repository also has no route to PGDG — and DocumentDB depends on PostgreSQL itself plus \`pg_cron\`, \`pgvector\` and PostGIS, which are PGDG packages. Downloading the DocumentDB release assets alone is not enough. Stage the whole dependency closure on a connected machine and carry it across. - -Run the staging step on a machine with the **same distribution, release and architecture** as the target; the closure is specific to all three. +An air-gapped host has no route to PGDG either, and DocumentDB pulls PostgreSQL, \`pg_cron\`, \`pgvector\` and PostGIS from there — the release assets alone are not enough. Stage the full dependency closure on a connected machine with the **same distribution, release and architecture** as the target. ### Stage the bundle (connected machine) -Configure the repositories exactly as in the examples above, then download the closure and index it: +With the same repositories configured as for an online install: \`\`\`bash # Debian / Ubuntu @@ -225,13 +227,14 @@ sudo dnf download --resolve --alldeps --destdir bundle documentdb-18 createrepo_c bundle \`\`\` -> **Use the full-closure flags, not \`--download-only\`.** \`apt-get install --download-only\` and a bare \`dnf download --resolve\` skip anything already installed on the staging machine. The bundle looks complete and then fails on a clean target with errors like \`Depends: adduser but it is not installable\`. \`apt-cache depends --recurse\` and \`dnf download --alldeps\` ignore local install state, which is what you want here. +> [!NOTE] +> **Use the full-closure flags, not \`--download-only\`.** \`apt-get install --download-only\` and a bare \`dnf download --resolve\` skip whatever is already installed on the staging machine; the bundle looks complete and the target dies with \`Depends: adduser but it is not installable\`. -Expect roughly 200 packages / 200 MB for the DEB closure and 270 packages / 170 MB for the RPM closure — mostly PostGIS and its GDAL dependencies. Two warnings from the DEB step are harmless: \`Download is performed unsandboxed as root\`, and a long \`dpkg-scanpackages: warning: Packages in archive but missing from override file\` list, which is just an artifact of passing \`/dev/null\` as the override file. +Expect ~200 packages / 200 MB (DEB) or ~270 / 170 MB (RPM), mostly PostGIS and GDAL. The \`unsandboxed as root\` and \`dpkg-scanpackages ... override file\` warnings are harmless. ### Install from the bundle (air-gapped target) -Copy \`bundle/\` across and point the package manager at it. Because the target now has a real repository index, this is a single command with full dependency resolution — no ordered list of files: +Copy \`bundle/\` across and point the package manager at it — the local index restores full dependency resolution: \`\`\`bash # Debian / Ubuntu @@ -249,7 +252,7 @@ printf '%s\\n' '[documentdb-offline]' 'name=DocumentDB offline bundle' \\ sudo dnf install documentdb-18 \`\`\` -\`[trusted=yes]\` and \`gpgcheck=0\` tell the package manager to accept a local directory that has no repository signature of its own. The upstream signatures were verified when the bundle was staged; if it crosses an untrusted boundary, check the transfer with \`sha256sum\`. +\`[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** below — \`documentdb-setup\` needs no network. @@ -258,7 +261,7 @@ Then continue with **Set up and connect** below — \`documentdb-setup\` needs n If the target already has PostgreSQL and the PGDG extension dependencies (\`postgresql-N-cron\`, \`-pgvector\`, \`-postgis-3\`), 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\`. They must go in one command: \`apt\` and \`dnf\` resolve dependencies only from repository indexes, so a dependency on a bare local file is unresolvable and the meta package on its own fails with \`Depends: documentdb-18 ... but it is not installable\`. That is not a defect in the packages — it happens to any local \`.deb\` or \`.rpm\` whose dependencies are not in an enabled repository. +- **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\`. ## Set up and connect From 1b551358bfe8cb5128fddb91c6f21222a72dced8 Mon Sep 17 00:00:00 2001 From: Guanzhou Song Date: Tue, 25 Aug 2026 12:15:36 -0400 Subject: [PATCH 4/4] Restructure the packages guide around the install command A clarity review found the page worked as a reference manual and failed as a quick start: the first copyable command sat 617 words down, behind a package inventory, a version-tier table and a support matrix that nobody needs before installing. Lead with the two install commands. Everything a reader consults rather than follows -- the package roles, which version each target serves, the per-distribution component table, the extension-only rules and the Debian 11/13 caveats -- merges into one "Other targets" section below the operational content. The five callouts that used to precede the command become one [!NOTE] beside it. Delete "Turn an extension-only install into a local mongosh endpoint" (539 words). It is a Rust-toolchain build guide -- rustup, libssl-dev, su - postgres, a five-line comment about $TERM -- living inside a packages quick start, and it repeated both the Docker command owned by the Docker Quick Start and the mongosh install pointer given three separate times on the page. What survives is one sentence in "Other targets" pointing at the two scripts, keeping the TERM=xterm trap. Rewrite troubleshooting from 13 bullets to 7, keyed by the error string a reader actually arrives with instead of by category. Most of the old list restated callouts verbatim from earlier in the page. Put the mongosh flags form before the URI form, since it has no percent-encoding hazard to warn about. 3,519 -> 2,034 rendered words; first copyable command at word 57. Section count 14 -> 9. Every anchor still resolves, and the "Offline / air-gapped install" heading is unchanged so the v0.116-0 release notes keep linking to it. No shell command was altered. 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 | 326 +++++++++------------------------ 1 file changed, 86 insertions(+), 240 deletions(-) diff --git a/app/services/articleService.ts b/app/services/articleService.ts index 797e346..d81dd51 100644 --- a/app/services/articleService.ts +++ b/app/services/articleService.ts @@ -114,78 +114,26 @@ const linuxPackagesGuideContent = `# Linux Packages Quick Start Install DocumentDB on Debian, Ubuntu, or RHEL-compatible hosts from the published package repository. -## What you get +## Install -Since v0.116-0 DocumentDB ships as a set of packages rather than a lone extension: +**Ubuntu 24.04 and RHEL-compatible 9, on PostgreSQL 17 or 18**, get the full stack — extension, gateway, setup wizard and systemd units. Every other target is extension-only: see [Other targets](#other-targets). -| Package | Role | -| --- | --- | -| \`documentdb\` (meta) | Convenience package for the paved road — it simply depends on \`documentdb-18\`. | -| \`documentdb-N\` | Full stand-alone install for PostgreSQL major N. Pulls in the extension, gateway, tools and \`documentdb-common\`, and owns the systemd lifecycle. | -| \`postgresql-N-documentdb\` | The PostgreSQL extension itself (files only). | -| \`documentdb-gateway\` | Wire-protocol runtime serving the MongoDB-compatible endpoint. | -| \`documentdb-postgresql-tools\` | Admin helpers: \`documentdb-tune\`, \`documentdb-createcluster\`, \`documentdb-register-gateway\`, \`documentdb-gateway-admin\`. | -| \`documentdb-common\` | Shared payload: \`documentdb-setup\`, the systemd units, helper scripts, sample data. | - -> **The full stack is published for Ubuntu 24.04 and RHEL-compatible 9, on PostgreSQL 17 and 18 only.** -> -> **PostgreSQL 16 is extension-only everywhere**, including Ubuntu 24.04 and RHEL 9. There is no \`documentdb-16\` — asking for it fails with *"has no installation candidate"* (APT) or *"No match for argument"* (DNF). On PostgreSQL 16 you get \`postgresql-16-documentdb\` alone: no gateway, no \`documentdb-setup\`, no systemd units. -> -> Ubuntu 22.04, Debian 11/12/13 and RHEL-compatible 8 are extension-only on every major — see [Extension-only hosts](#extension-only-hosts). - -### Which version you get - -The repository serves the newest release that was actually built for your target, so the version differs by tier: - -| Target | Version served | -| --- | --- | -| Ubuntu 24.04 / RHEL 9 on PostgreSQL 17 or 18 | **0.116** (\`0.116-0\` on DEB, \`0.116.0-1.el9\` on RPM) | -| PostgreSQL 16, any distribution | **0.114** | -| Ubuntu 22.04, Debian 11/12/13, RHEL-compatible 8 | **0.114** | - -The examples below use the 0.116 strings. Substitute what your target serves — \`apt-cache madison \` and \`dnf --showduplicates list \` always show the truth. - -## Choose the right package command - -The [Package Finder](/packages) generates the command for any distro, architecture and PostgreSQL version. It needs JavaScript, so every combination is also written out below for scripted and headless installs. - -> The package commands assume a regular Linux host where you use \`sudo\`. In a clean container running as \`root\`, omit \`sudo\`. -> -> On Debian and Ubuntu in a clean container, also run \`export DEBIAN_FRONTEND=noninteractive\` first. Without it, \`tzdata\` prompts for input during \`apt install\` and the install hangs with no visible error. - -### The APT repository component and package for each target - -The DocumentDB APT repository is \`https://documentdb.io/deb stable \`. Pick the component that matches your distribution: - -| Distribution | PGDG suite | DocumentDB component | Install | -| --- | --- | --- | --- | -| Ubuntu 24.04 | \`noble-pgdg\` | \`ubuntu24\` | \`documentdb-18\` or \`documentdb-17\` (full stack) | -| Ubuntu 22.04 | \`jammy-pgdg\` | \`ubuntu22\` | \`postgresql-18-documentdb\` (extension only) | -| Debian 11 | \`bullseye-pgdg\` | \`deb11\` | \`postgresql-17-documentdb\` (extension only; **PostgreSQL 18 is not installable here**) | -| Debian 12 | \`bookworm-pgdg\` | \`deb12\` | \`postgresql-18-documentdb\` (extension only) | -| Debian 13 | \`trixie-pgdg\` | \`deb13\` | \`postgresql-18-documentdb\` (extension only) | - -For RPM the repository is \`https://documentdb.io/rpm/rhel9\` or \`https://documentdb.io/rpm/rhel8\`. RHEL 9 installs \`documentdb-18\` / \`documentdb-17\` (full stack); RHEL 8 installs \`postgresql18-documentdb\` (extension only) and uses \`EL-8\` in the PGDG and EPEL URLs, with \`--set-enabled powertools\` instead of \`crb\`. - -> **Debian 13 only:** \`apt.postgresql.org\` also publishes DocumentDB extension packages for Trixie, and its version string (\`0.114-0-1.pgdg13+1\`) sorts above the one in this repository (\`0.114-0\`), so PGDG's build is what installs by default. It is a different build of the same release. Pin explicitly with \`apt install postgresql-18-documentdb=\` if you need this repository's copy. - -## Install the packages - -### APT example (Ubuntu 24.04, PostgreSQL 18) +### Ubuntu 24.04, PostgreSQL 18 (APT) \`\`\`bash ${buildAptInstallCommand('ubuntu24', 'amd64', '18')} \`\`\` -For PostgreSQL 17 on the same host, install \`documentdb-17\` instead of \`documentdb-18\`. The \`documentdb\` meta package is equivalent to \`documentdb-18\`. - -### RPM example (RHEL-compatible 9, PostgreSQL 18) +### RHEL-compatible 9, PostgreSQL 18 (RPM) \`\`\`bash ${buildRpmInstallCommand('rhel9', 'x86_64', '18')} \`\`\` -For PostgreSQL 17, install \`documentdb-17\`. +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. > [!WARNING] > **On ARM, change three strings** — the commands above are written for x86_64. @@ -201,68 +149,6 @@ For PostgreSQL 17, install \`documentdb-17\`. > [!IMPORTANT] > **Do not drop the \`crb\` line.** PostGIS pulls in \`gdal*-libs\`, which needs \`libqhull_r.so.7\`, and that ships only in CRB (\`powertools\` on EL8). Without it \`dnf install\` fails with \`nothing provides libqhull_r.so.7()(64bit)\`, naming GDAL but never the missing repository. -## Offline / air-gapped install - -An air-gapped host has no route to PGDG either, and DocumentDB pulls PostgreSQL, \`pg_cron\`, \`pgvector\` and PostGIS from there — the release assets alone are not enough. Stage the full dependency closure on a connected machine with the **same distribution, release and architecture** as the target. - -### Stage the bundle (connected machine) - -With the same repositories configured as for an online install: - -\`\`\`bash -# Debian / Ubuntu -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) -mkdir -p bundle && cd bundle -apt-get download "\${PKGS[@]}" -dpkg-scanpackages . /dev/null > Packages && gzip -k Packages -\`\`\` - -\`\`\`bash -# RHEL-compatible -sudo dnf install -y dnf-plugins-core createrepo_c -mkdir -p bundle -sudo dnf download --resolve --alldeps --destdir bundle documentdb-18 -createrepo_c bundle -\`\`\` - -> [!NOTE] -> **Use the full-closure flags, not \`--download-only\`.** \`apt-get install --download-only\` and a bare \`dnf download --resolve\` skip whatever is already installed on the staging machine; the bundle looks complete and the target dies with \`Depends: adduser but it is not installable\`. - -Expect ~200 packages / 200 MB (DEB) or ~270 / 170 MB (RPM), mostly PostGIS and GDAL. The \`unsandboxed as root\` and \`dpkg-scanpackages ... override file\` warnings are harmless. - -### Install from the bundle (air-gapped target) - -Copy \`bundle/\` across and point the package manager at it — the local index restores full dependency resolution: - -\`\`\`bash -# Debian / Ubuntu -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 -\`\`\` - -\`\`\`bash -# RHEL-compatible -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 -\`\`\` - -\`[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** below — \`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: - -- **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\`. - ## Set up and connect Installing the packages puts files on disk; it does not create a database or start the endpoint. The setup wizard does that: @@ -273,7 +159,7 @@ sudo documentdb-setup --admin-user admin It creates the PostgreSQL instance, installs the extensions, bootstraps the admin user, starts the gateway, and enables \`documentdb-local@.target\` so the stack survives reboot. It **prompts for the admin password**; for servers and CI pass \`--admin-password-file \` or \`--admin-password-stdin\` together with \`--yes\`. -\`mongosh\` is not shipped by these packages. Install it from MongoDB's own repository — these are the commands for the two paved-road targets, and the [official instructions](https://www.mongodb.com/docs/mongodb-shell/install/) cover every other platform: +\`mongosh\` is not shipped by these packages. Install it from MongoDB's own repository — these are the two paved-road targets, and the [official instructions](https://www.mongodb.com/docs/mongodb-shell/install/) cover every other platform: \`\`\`bash # Ubuntu 24.04 @@ -288,18 +174,18 @@ printf '%s\\n' '[mongodb-org-8.0]' 'name=MongoDB Repository' \\ sudo dnf install -y mongodb-mongosh \`\`\` -Then connect: +Then connect. Passing credentials as flags avoids URI escaping entirely: \`\`\`bash -mongosh 'mongodb://admin:@127.0.0.1:10260/mydb?tls=true&tlsAllowInvalidCertificates=true' \\ - --eval 'db.runCommand({ping: 1})' +mongosh localhost:10260 -u admin -p --authenticationMechanism SCRAM-SHA-256 \\ + --tls --tlsAllowInvalidCertificates --eval 'db.runCommand({ping: 1})' \`\`\` -If the password contains \`@\`, \`:\`, \`/\` or other reserved characters it must be percent-encoded in the URI (\`@\` becomes \`%40\`), otherwise the URI misparses. To avoid encoding entirely, pass the credentials as flags instead: +Or as a URI — percent-encode reserved characters in the password (\`@\` becomes \`%40\`), or it misparses: \`\`\`bash -mongosh localhost:10260 -u admin -p --authenticationMechanism SCRAM-SHA-256 \\ - --tls --tlsAllowInvalidCertificates --eval 'db.runCommand({ping: 1})' +mongosh 'mongodb://admin:@127.0.0.1:10260/mydb?tls=true&tlsAllowInvalidCertificates=true' \\ + --eval 'db.runCommand({ping: 1})' \`\`\` A database and collection are created on first write: @@ -345,41 +231,38 @@ sudo systemctl restart documentdb-local@18.target sudo systemctl stop documentdb-local@18.target \`\`\` -**On hosts without systemd** — containers and some dev images — the wizard says so at the end of setup and starts the gateway directly instead. The \`systemctl\` commands above will fail with *"System has not been booted with systemd"*; use \`documentdb-setup --status\` to inspect it and re-run \`documentdb-setup\` to restart it. \`documentdb-setup --restore\` stops the directly-started gateway for you. +**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. ### Running SQL against the managed instance -\`documentdb-setup\` creates a private PostgreSQL instance owned by the \`documentdb-local\` system user, listening on a socket rather than TCP, so a bare \`psql\` will not find it. Connect as that user through the per-major socket directory: +\`documentdb-setup\` runs a private instance as the \`documentdb-local\` user on a socket, so a bare \`psql\` will not find it: \`\`\`bash sudo -u documentdb-local psql -h /run/documentdb-local/18/postgresql -p 9718 -d postgres \`\`\` -That is the connection to use for the \`ALTER EXTENSION\` statements under [Upgrading](#upgrading), and to read the installed versions: +Use that connection for the \`ALTER EXTENSION\` statements under [Upgrading](#upgrading), and to read the installed versions: \`\`\`sql SELECT extname, extversion FROM pg_extension WHERE extname LIKE 'documentdb%'; \`\`\` -Remove or reset: +### Remove or reset \`\`\`bash # Stop the stack first — package removal deletes files but does not stop a # running gateway. On systemd hosts: sudo systemctl stop documentdb-local@18.target -# Without systemd the wizard started the gateway directly; kill that process. -sudo documentdb-setup --restore # detach the managed integration -sudo documentdb-local-reset --pg-version 18 --confirm-destroy # DESTROYS the data directory +sudo documentdb-setup --restore # detach the managed integration +sudo documentdb-local-reset --pg-version 18 --confirm-destroy # DESTROYS the data directory # Name the package you installed AND the extension: autoremove does not reap -# postgresql-18-documentdb, and \`remove\` would leave config behind. +# postgresql-18-documentdb, and 'remove' would leave config behind. sudo apt purge --autoremove documentdb-18 postgresql-18-documentdb sudo dnf remove documentdb-18 postgresql18-documentdb && sudo dnf autoremove \`\`\` -(If you installed the \`documentdb\` meta package rather than \`documentdb-18\`, name that instead.) - ## Upgrading A package upgrade only replaces files. Afterwards, update the extensions in every database that has DocumentDB installed: @@ -392,143 +275,106 @@ ALTER EXTENSION documentdb_extended_rum UPDATE; -- only if installed PostgreSQL applies intermediate upgrade scripts automatically. In-place upgrades are not yet a fully tested path, so take a backup first. -## Extension-only hosts +## Other targets -Ubuntu 22.04, Debian 11/12/13 and RHEL-compatible 8 serve the extension package alone — no gateway, setup helper, or systemd units — and so does **PostgreSQL 16 on every distribution**. On those targets the install command ends in \`postgresql--documentdb\` (APT) or \`postgresql-documentdb\` (RPM), there is no \`documentdb-setup\`, and the version served is 0.114. See the component and package table under [Choose the right package command](#choose-the-right-package-command) for the exact repository line per distribution. +The full stack is published only for **Ubuntu 24.04 and RHEL-compatible 9 on PostgreSQL 17 or 18**. Everywhere else — including **PostgreSQL 16 on every distribution** — you get the extension package alone: no gateway, no \`documentdb-setup\`, no systemd units. There is no \`documentdb-16\`; asking for it fails with *"has no installation candidate"* (APT) or *"No match for argument"* (DNF). -**Debian 11 does not support PostgreSQL 18.** \`apt install postgresql-18-documentdb\` there fails with \`Depends: postgresql-18-postgis-3 but it is not installable\` — the upstream Bullseye PostGIS build does not exist. Use PostgreSQL 16 or 17. +| Distribution | PGDG suite | Repository component | Install | +| --- | --- | --- | --- | +| Ubuntu 24.04 | \`noble-pgdg\` | \`ubuntu24\` | \`documentdb-18\` / \`documentdb-17\` — full stack | +| RHEL-compatible 9 | — | \`rpm/rhel9\` | \`documentdb-18\` / \`documentdb-17\` — full stack | +| Ubuntu 22.04 | \`jammy-pgdg\` | \`ubuntu22\` | \`postgresql-18-documentdb\` | +| Debian 11 | \`bullseye-pgdg\` | \`deb11\` | \`postgresql-17-documentdb\` — **PG 18 not installable** | +| Debian 12 | \`bookworm-pgdg\` | \`deb12\` | \`postgresql-18-documentdb\` | +| Debian 13 | \`trixie-pgdg\` | \`deb13\` | \`postgresql-18-documentdb\` | +| RHEL-compatible 8 | — | \`rpm/rhel8\` | \`postgresql18-documentdb\` — \`EL-8\` URLs, \`powertools\` not \`crb\` | -Confirm the extension landed with package metadata: +The APT repository is \`https://documentdb.io/deb stable \`; the RPM baseurl is \`https://documentdb.io/rpm/\`. It serves **0.116** on the full-stack targets and **0.114** everywhere else — \`apt-cache madison \` / \`dnf --showduplicates list \` show the truth. -\`\`\`bash -# APT -apt-cache policy postgresql-18-documentdb -dpkg -L postgresql-18-documentdb | grep -E 'documentdb.*\\.(control|sql|so)$' | head +**Debian 11 has no PostgreSQL 18** — the upstream Bullseye PostGIS build does not exist, so the install fails with \`Depends: postgresql-18-postgis-3 but it is not installable\`. Use 16 or 17. -# RPM -dnf info postgresql18-documentdb -rpm -ql postgresql18-documentdb | grep -E 'documentdb.*\\.(control|sql|so)$' | head -\`\`\` +**Debian 13:** \`apt.postgresql.org\` also publishes this extension and its version sorts higher, so PGDG's build installs by default. Pin with \`apt install postgresql-18-documentdb=\` for this repository's copy. -For the fastest gateway-backed endpoint on those hosts, use the Docker quick start: +Confirm the extension landed: \`\`\`bash -docker run -dt --name documentdb \\ - -p 10260:10260 \\ - ghcr.io/documentdb/documentdb/documentdb-local:latest \\ - --username \\ - --password +apt-cache policy postgresql-18-documentdb # or: dnf info postgresql18-documentdb +dpkg -L postgresql-18-documentdb | grep -E 'documentdb.*\\.(control|sql|so)$' | head \`\`\` -Otherwise, run the gateway from the source repository against your host PostgreSQL, as described below. - -## Turn an extension-only install into a local \`mongosh\` endpoint - -On Ubuntu 24.04 and RHEL 9 use \`documentdb-setup\` above instead — this section is only for distributions where the gateway is not packaged yet. +For a MongoDB-compatible endpoint on these hosts, use the [Docker Quick Start](/docs/getting-started/docker), or run the gateway from source against your host PostgreSQL with \`scripts/start_oss_server.sh\` and \`scripts/build_and_start_gateway.sh\` in the [DocumentDB repository](https://github.com/documentdb/documentdb). Run those as an unprivileged user, and \`export TERM=xterm\` first in non-interactive shells or the script aborts on \`tput\`. -If you want to keep PostgreSQL on the host and still connect with \`mongosh\`, install the extension package first and then run the gateway from the source repository against that PostgreSQL instance. - -### Prerequisites for the host gateway step - -- [Git](https://git-scm.com/) -- \`curl\` -- Native build tools for Rust crates that link against OpenSSL -- A current Rust toolchain via \`rustup\` -- [mongosh](https://www.mongodb.com/docs/mongodb-shell/install/) - -Run the PostgreSQL and gateway steps from an unprivileged user account, not \`root\`. PostgreSQL will not initialize as \`root\`. +## Offline / air-gapped install -If you are following these steps in a clean container that starts as \`root\`, finish the package-install commands as \`root\`, then switch to an unprivileged account such as \`postgres\` before you start PostgreSQL or the gateway. +An air-gapped host has no route to PGDG either, and DocumentDB pulls PostgreSQL, \`pg_cron\`, \`pgvector\` and PostGIS from there — the release assets alone are not enough. Stage the full dependency closure on a connected machine with the **same distribution, release and architecture** as the target. -\`\`\`bash -# from a root shell inside the container -su - postgres -\`\`\` +### Stage the bundle (connected machine) -Install the host prerequisites with your distro package manager before continuing. Examples: +With the same repositories configured as for an online install: \`\`\`bash # Debian / Ubuntu -sudo apt install -y git curl build-essential pkg-config libssl-dev - -# RHEL-compatible -sudo dnf install -y git curl gcc gcc-c++ make pkgconf-pkg-config openssl-devel +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) +mkdir -p bundle && cd bundle +apt-get download "\${PKGS[@]}" +dpkg-scanpackages . /dev/null > Packages && gzip -k Packages \`\`\` -Install a current Rust toolchain with \`rustup\`, then load it into your shell: - \`\`\`bash -curl https://sh.rustup.rs -sSf | sh -s -- -y -. "$HOME/.cargo/env" +# RHEL-compatible +sudo dnf install -y dnf-plugins-core createrepo_c +mkdir -p bundle +sudo dnf download --resolve --alldeps --destdir bundle documentdb-18 +createrepo_c bundle \`\`\` -In a clean container that starts as \`root\`, install the system packages above and install \`mongosh\` while you are still \`root\`. Then switch to the unprivileged user and run the \`rustup\` commands plus the remaining gateway steps from that user's shell. - -### Host setup example +> [!NOTE] +> **Use the full-closure flags, not \`--download-only\`.** \`apt-get install --download-only\` and a bare \`dnf download --resolve\` skip whatever is already installed on the staging machine; the bundle looks complete and the target dies with \`Depends: adduser but it is not installable\`. -Replace \`\` with the PostgreSQL major version you installed from the package repository, such as \`16\`, \`17\`, or \`18\`. +Expect ~200 packages / 200 MB (DEB) or ~270 / 170 MB (RPM), mostly PostGIS and GDAL. The \`unsandboxed as root\` and \`dpkg-scanpackages ... override file\` warnings are harmless. -If you do not already have \`mongosh\`, install it with the official MongoDB shell instructions for your distro before continuing: +### Install from the bundle (air-gapped target) -- https://www.mongodb.com/docs/mongodb-shell/install/ +Copy \`bundle/\` across and point the package manager at it — the local index restores full dependency resolution: \`\`\`bash -git clone https://github.com/documentdb/documentdb.git -cd documentdb - -export PG_VERSION_USED= - -# Required in non-interactive shells (CI, \`docker exec\` without \`-t\`, -# \`docker exec -d\`, \`nohup\`, background \`&\`). build_and_start_gateway.sh -# calls \`tput\` for colored output and aborts under \`set -u\` / \`set -e\` if -# TERM is unset or set to \`dumb\`. Skip this line in a normal interactive -# terminal where TERM is already \`xterm\`, \`xterm-256color\`, etc. -export TERM=xterm - -./scripts/start_oss_server.sh -c -u -a - -./scripts/build_and_start_gateway.sh -c \\ - -u \\ - -p \\ - -P 9712 +# Debian / Ubuntu +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 \`\`\` -\`./scripts/start_oss_server.sh -c\` initializes a fresh local PostgreSQL data directory under \`~/.documentdb/data\`. \`./scripts/build_and_start_gateway.sh -c\` forces a clean gateway rebuild; after the first successful build, you can omit \`-c\` on later restarts. +\`\`\`bash +# RHEL-compatible +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 +\`\`\` -The first gateway build downloads several hundred Rust crates and typically takes a few minutes on a fresh machine before the gateway begins listening on port \`10260\`. Subsequent runs without \`-c\` are much faster. +\`[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. -Keep the gateway command running in the foreground. It starts the MongoDB-compatible endpoint on port \`10260\` and connects it to PostgreSQL on port \`9712\`. +Then continue with **Set up and connect** above — \`documentdb-setup\` needs no network. -Then connect with \`mongosh\`: +### Smaller offline cases -\`\`\`bash -mongosh localhost:10260 \\ - -u \\ - -p \\ - --authenticationMechanism SCRAM-SHA-256 \\ - --tls \\ - --tlsAllowInvalidCertificates -\`\`\` +If the target already has PostgreSQL and the PGDG extension dependencies (\`postgresql-N-cron\`, \`-pgvector\`, \`-postgis-3\`), you do not need a bundle: -Use this flow when you want a package-backed host install plus a local MongoDB-compatible endpoint. Use the Docker quick start instead when you want the shortest local setup path. +- **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\`. -## Troubleshooting and debugging +## Troubleshooting -If something does not work on the first try: - -- Confirm the packages are installed: \`documentdb-\` on a full-stack target, or \`postgresql--documentdb\` (APT) / \`postgresql-documentdb\` (RPM) on an extension-only target -- On a full-stack target, run \`sudo documentdb-setup --status\` first: it reports the gateway listener, the service states and the resolved paths -- Re-run the Package Finder command for the exact distro, architecture, and PostgreSQL version you selected -- Confirm the PostgreSQL upstream repository was added before the DocumentDB package install -- If you are running in a clean container as \`root\`, omit \`sudo\` from the package-install commands and switch to an unprivileged user before the gateway steps -- If \`apt install\` hangs forever in a clean container, run \`export DEBIAN_FRONTEND=noninteractive\` in that shell and re-run the install; the default front-end is waiting for a \`tzdata\` prompt that never gets typed -- If you use the host gateway flow, confirm \`PG_VERSION_USED\` matches the PostgreSQL major version you installed -- If \`./scripts/build_and_start_gateway.sh\` exits immediately with \`tput: No value for $TERM\` (or silently with \`set -e\` when \`TERM=dumb\`), set \`export TERM=xterm\` before re-running, or run the script from an interactive shell (for Docker, \`docker exec -it ...\`) -- If \`./scripts/build_and_start_gateway.sh\` fails, confirm \`git\`, \`curl\`, native build tools, \`pkg-config\`, OpenSSL headers, and a current Rust toolchain are installed on the host -- If the gateway build fails while reading \`Cargo.lock\`, switch to a current Rust toolchain from \`rustup\` instead of the distro-packaged \`cargo\` -- If \`mongosh\` cannot connect, confirm the gateway script is still running and listening on port \`10260\` -- For Debian 11, use PostgreSQL 16 or 17; PostgreSQL 18 is blocked by the upstream Bullseye PostGIS dependency -- If you need a gateway endpoint on an extension-only distribution, use DocumentDB Local with Docker or build and run the gateway from source +- \`sudo documentdb-setup --status\` reports the listener, service states and resolved paths +- \`has no installation candidate\` / \`No match for argument\` — that target is extension-only, or PGDG was not added first. See [Other targets](#other-targets) +- \`nothing provides libqhull_r.so.7\` — the \`crb\` line did not run +- \`Depends: postgresql-N-documentdb but it is not installable\` — wrong \`arch=\` for the host +- \`Bad GPG signature\` on \`pgdg-common\` — wrong architecture in the PGDG reporpm URL +- \`apt install\` hangs in a container — \`export DEBIAN_FRONTEND=noninteractive\` +- Debian 11 has no PostgreSQL 18 (no upstream Bullseye PostGIS); use 16 or 17 ## Next steps