diff --git a/app/services/articleService.ts b/app/services/articleService.ts index cfc85b9..d81dd51 100644 --- a/app/services/articleService.ts +++ b/app/services/articleService.ts @@ -114,80 +114,40 @@ 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\`. The \`documentdb\` meta package is equivalent to \`documentdb-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. + +> [!WARNING] +> **On ARM, change three strings** — the commands above are written for x86_64. +> +> | 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. ## Set up and connect @@ -199,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 @@ -214,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: @@ -271,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: @@ -318,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. +## Offline / air-gapped install -### 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/) +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. -Run the PostgreSQL and gateway steps from an unprivileged user account, not \`root\`. PostgreSQL will not initialize as \`root\`. +### Stage the bundle (connected machine) -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. - -\`\`\`bash -# from a root shell inside the container -su - postgres -\`\`\` - -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 +# 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/build_and_start_gateway.sh -c \\ - -u \\ - -p \\ - -P 9712 +\`\`\`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 \`\`\` -\`./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. +\`[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. -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. +Then continue with **Set up and connect** above — \`documentdb-setup\` needs no network. -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\`. +### Smaller offline cases -Then connect with \`mongosh\`: +If the target already has PostgreSQL and the PGDG extension dependencies (\`postgresql-N-cron\`, \`-pgvector\`, \`-postgis-3\`), you do not need a bundle: -\`\`\`bash -mongosh localhost:10260 \\ - -u \\ - -p \\ - --authenticationMechanism SCRAM-SHA-256 \\ - --tls \\ - --tlsAllowInvalidCertificates -\`\`\` +- **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\`. -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. - -## 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