From 4225973e70f0a3da4a9bf7e3f1b20e3f545afeef Mon Sep 17 00:00:00 2001 From: Guanzhou Song Date: Tue, 25 Aug 2026 11:27:19 -0400 Subject: [PATCH 1/5] Note the arm64 asset names and why local package installs need one command Two small gaps in the downloaded-assets section. The DEB and RPM examples are written for amd64 and x86_64 and give no arm64 equivalent, even though the release publishes both architectures and the release notes carry the swap note. Add it to each example, and record that only the gateway and extension assets are architecture- specific -- the other four are _all.deb / noarch and are the same file on either architecture, so a reader swapping names does not have to guess which of the six change. The stated reason the meta package cannot be installed alone is also slightly off. It is not that the packages depend on each other: apt and dnf resolve dependencies only from repository indexes, so a dependency on a bare local file is unresolvable regardless of how simple it is. A meta package with a single dependency fails identically. Say that instead, and note it is not a defect in the packages, since the error reads like one. Verified against v0.116-0: dropping the six release assets into a local apt repository and running a bare `apt install documentdb` resolves the whole graph unaided (documentdb -> documentdb-18 -> documentdb-common + postgresql-18-documentdb -> documentdb-gateway + documentdb-postgresql-tools), which confirms the package metadata is correct and the repository index is the only missing piece. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: f18515db-c52f-4197-aa50-d81359c7c763 Signed-off-by: Guanzhou Song --- getting-started/prebuilt-packages.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/getting-started/prebuilt-packages.md b/getting-started/prebuilt-packages.md index 0122416..0dfef7d 100644 --- a/getting-started/prebuilt-packages.md +++ b/getting-started/prebuilt-packages.md @@ -60,16 +60,18 @@ The repository also keeps the most recent package for distributions a given rele ## Install from downloaded assets -The packages depend on each other, so **installing the meta package on its own fails**: +`apt` and `dnf` resolve dependencies only from repository indexes, so a dependency on a bare local file is unresolvable and **installing the meta package on its own fails**: ```text documentdb : Depends: documentdb-18 (>= 0.116.0) but it is not installable ``` -Pass the whole set for your platform to one command. +This is not a defect in the packages — the same thing happens to any local `.deb` or `.rpm` whose dependencies are not in an enabled repository. Pass the whole set for your platform to one command. ### DEB (Ubuntu 24.04, PostgreSQL 18, amd64) +For arm64 swap `amd64` → `arm64`; for PostgreSQL 17 swap `18` → `17`. Only the gateway and extension assets carry an architecture — the other four are `_all.deb` and are the same file on both. + ```bash sudo apt install ./ubuntu24.04-documentdb_0.116.0_all.deb \ ./ubuntu24.04-documentdb-18_0.116.0_all.deb \ @@ -81,6 +83,8 @@ sudo apt install ./ubuntu24.04-documentdb_0.116.0_all.deb \ ### RPM (RHEL-compatible 9, PostgreSQL 18, x86_64) +For arm64 swap `x86_64` → `aarch64`; for PostgreSQL 17 swap `18` → `17`. As with DEB, only the gateway and extension assets are architecture-specific; the other four are `noarch`. + ```bash sudo dnf install ./documentdb-0.116.0-1.noarch.rpm \ ./documentdb-18-0.116.0-1.noarch.rpm \ From af2bf25fbc5f25b598213ba7b68a2ccbcc89cefa Mon Sep 17 00:00:00 2001 From: Guanzhou Song Date: Tue, 25 Aug 2026 11:43:38 -0400 Subject: [PATCH 2/5] Add an offline / air-gapped install section An air-gapped host needs more than the DocumentDB release assets: the packages depend on PostgreSQL itself and on pg_cron, pgvector and PostGIS from PGDG, none of which are on the release page. The page had no guidance for that case, so the only documented offline path was the six-asset command, which still assumes the host can reach PGDG. 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. The local index restores full dependency resolution, so the air-gapped install is a single `apt install documentdb-18` / `dnf install documentdb-18` rather than an ordered list of files. 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. Also add the single-file case -- the extension alone, onto a host that already has PostgreSQL and the PGDG extension dependencies -- so the page now covers one file, several files, and one command. Verified on v0.116-0 with the documented commands run verbatim, installing into containers 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 PGDG prerequisites present -> exit 0. The first attempt used --download-only and produced exactly the failure now documented, which is why it is called out. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: f18515db-c52f-4197-aa50-d81359c7c763 Signed-off-by: Guanzhou Song --- getting-started/prebuilt-packages.md | 68 ++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) diff --git a/getting-started/prebuilt-packages.md b/getting-started/prebuilt-packages.md index 0dfef7d..0a03d05 100644 --- a/getting-started/prebuilt-packages.md +++ b/getting-started/prebuilt-packages.md @@ -68,6 +68,8 @@ documentdb : Depends: documentdb-18 (>= 0.116.0) but it is not installable This is not a defect in the packages — the same thing happens to any local `.deb` or `.rpm` whose dependencies are not in an enabled repository. Pass the whole set for your platform to one command. +This still assumes the host can reach PGDG for PostgreSQL itself. If it cannot, see [Offline / air-gapped install](#offline--air-gapped-install), which stages the whole dependency closure and restores single-command installs. + ### DEB (Ubuntu 24.04, PostgreSQL 18, amd64) For arm64 swap `amd64` → `arm64`; for PostgreSQL 17 swap `18` → `17`. Only the gateway and extension assets carry an architecture — the other four are `_all.deb` and are the same file on both. @@ -98,6 +100,72 @@ The `ubuntu24.04-` and `rhel9-` filename prefixes disambiguate release assets; t Both families need the PostgreSQL upstream (PGDG) repository enabled first, and RHEL-compatible hosts additionally need EPEL and CRB. See [Package Installation](https://documentdb.io/packages) for those prerequisites. +### Extension only, from a single file + +If the target already has PostgreSQL and the PGDG extension dependencies (`postgresql-N-cron`, `-pgvector`, `-postgis-3`), the extension package installs from one file, with no gateway and no `documentdb-setup`: + +```bash +sudo apt install ./ubuntu24.04-postgresql-18-documentdb_0.116-0_amd64.deb +``` + +## Offline / air-gapped install + +An air-gapped host needs more than the DocumentDB assets: the packages depend on PostgreSQL itself and on `pg_cron`, `pgvector` and PostGIS from PGDG, none of which are on the release page. Stage the whole dependency closure on a connected machine first. + +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 for an online install, 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 then looks complete but 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. + +Expect roughly 200 packages / 200 MB for the DEB closure and 270 packages / 170 MB for the RPM closure, dominated by PostGIS and its GDAL dependencies. + +Two warnings from the DEB staging step are expected and 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, point the package manager at it, and install with one command — the local index gives you full dependency resolution, so you do not have to name the packages individually or order them correctly: + +```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 the local directory, which has no repository signature of its own. The upstream signatures were already verified when the bundle was staged; verify the transfer itself with `sha256sum` if the bundle crosses an untrusted boundary. + +Then continue with [Set up and connect](#set-up-and-connect) as normal — `documentdb-setup` needs no network. + ## Set up and connect Installing the packages puts files on disk. The setup wizard creates the PostgreSQL instance, installs the extensions, bootstraps the admin user and starts the gateway: From 9850415c1f983dd86a6e4526d64bc56e086906cd Mon Sep 17 00:00:00 2001 From: Guanzhou Song Date: Tue, 25 Aug 2026 12:03:07 -0400 Subject: [PATCH 3/5] Point Pre-built Packages links at the live page, not the redirect stub Four pages link to /docs/getting-started/prebuilt-packages/, which documentdb.io serves as a 'this page has moved' stub -- 440 characters of visible text against 20,563 on the page it points to. Link straight to /docs/getting-started/packages/ so readers land on the content. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: f18515db-c52f-4197-aa50-d81359c7c763 Signed-off-by: Guanzhou Song --- documentdb-local/index.md | 2 +- getting-started/index.md | 2 +- getting-started/python-setup.md | 2 +- kubernetes-operator/index.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/documentdb-local/index.md b/documentdb-local/index.md index 086af1e..93c8476 100644 --- a/documentdb-local/index.md +++ b/documentdb-local/index.md @@ -175,7 +175,7 @@ For mongosh info see: https://www.mongodb.com/docs/mongodb-shell/ DocumentDB Local runs a single container on one machine, with no replication and no failover, which is what makes it convenient for development and testing. For other ways to run DocumentDB: - [Kubernetes Operator](https://documentdb.io/docs/kubernetes-operator/) - run DocumentDB as a replicated service, with automatic failover, backup and restore, and rolling upgrades. -- [Pre-built packages](https://documentdb.io/docs/getting-started/prebuilt-packages/) - add the DocumentDB extension to a PostgreSQL server you already run. +- [Pre-built packages](https://documentdb.io/docs/getting-started/packages/) - add the DocumentDB extension to a PostgreSQL server you already run. ## Reporting issues diff --git a/getting-started/index.md b/getting-started/index.md index f47031b..a497e8c 100644 --- a/getting-started/index.md +++ b/getting-started/index.md @@ -70,7 +70,7 @@ Choose the getting started guide that best fits your needs: - [Node.js Setup Guide](https://documentdb.io/docs/getting-started/nodejs-setup/) - Using DocumentDB with Node.js applications ### Deployment Options -- [Pre-built Packages](https://documentdb.io/docs/getting-started/prebuilt-packages/) - Download and install ready-to-use packages +- [Pre-built Packages](https://documentdb.io/docs/getting-started/packages/) - Download and install ready-to-use packages - [Kubernetes Operator](https://documentdb.io/docs/kubernetes-operator/) - Run DocumentDB as a replicated service on Kubernetes ## Community and Support diff --git a/getting-started/python-setup.md b/getting-started/python-setup.md index 5a22e70..d46fbf1 100644 --- a/getting-started/python-setup.md +++ b/getting-started/python-setup.md @@ -11,7 +11,7 @@ Learn how to set up and use DocumentDB with Python using the official MongoDB Py - Python 3.7+ - pip package manager -- DocumentDB installed and running (see [Pre-built Packages](https://documentdb.io/docs/getting-started/prebuilt-packages/)) +- DocumentDB installed and running (see [Pre-built Packages](https://documentdb.io/docs/getting-started/packages/)) - Docker (if DocumentDB is not set up yet) - Git installed (for cloning the repository) diff --git a/kubernetes-operator/index.md b/kubernetes-operator/index.md index c8b2086..f776bcd 100644 --- a/kubernetes-operator/index.md +++ b/kubernetes-operator/index.md @@ -14,7 +14,7 @@ The operator is a separate project, with its own repository, release cadence, an | Option | Best for | |---|---| | [DocumentDB Local](https://documentdb.io/docs/documentdb-local/) | A single container for development, prototyping, and integration tests. | -| [Pre-built packages](https://documentdb.io/docs/getting-started/prebuilt-packages/) | Adding DocumentDB to a PostgreSQL server you already run and operate yourself. | +| [Pre-built packages](https://documentdb.io/docs/getting-started/packages/) | Adding DocumentDB to a PostgreSQL server you already run and operate yourself. | | Kubernetes Operator | Running DocumentDB as a replicated service, with automatic failover, rolling upgrades, backup and restore, and multi-region deployments. | ## What your cluster needs From 630de4e916835a6ebc27119b599cd4c345fb5b89 Mon Sep 17 00:00:00 2001 From: Guanzhou Song Date: Tue, 25 Aug 2026 12:03:31 -0400 Subject: [PATCH 4/5] Tighten the packages page after a clarity review A documentation review flagged the page as a reference manual rather than a quick start. Three concrete problems, all fixed here. The PGDG/EPEL/CRB prerequisite was printed *after* both install blocks it gates, so a reader copy-pasted, failed, and only then met the fix. Move it above the commands. The offline section added earlier duplicated the one just added to documentdb.io, and the two had already diverged on the day they landed -- the website files the single-file case under "Smaller offline cases", this file filed it under "Install from downloaded assets". Since documentdb.io is the canonical page and this file renders as a redirect stub there, reduce the section to a pointer plus the one thing a reader cannot rediscover: that `--download-only` silently stages an incomplete bundle. The verified commands stay in exactly one place. Trim the rest: the three-paragraph "why the meta package fails" preamble becomes one sentence that keeps the searchable error string, and the arm64 notes drop their restatement while keeping the fact that only two of the six asset names change. 1,565 -> 1,150 words. No 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 --- getting-started/prebuilt-packages.md | 74 +++------------------------- 1 file changed, 7 insertions(+), 67 deletions(-) diff --git a/getting-started/prebuilt-packages.md b/getting-started/prebuilt-packages.md index 0a03d05..0e2de34 100644 --- a/getting-started/prebuilt-packages.md +++ b/getting-started/prebuilt-packages.md @@ -60,19 +60,13 @@ The repository also keeps the most recent package for distributions a given rele ## Install from downloaded assets -`apt` and `dnf` resolve dependencies only from repository indexes, so a dependency on a bare local file is unresolvable and **installing the meta package on its own fails**: +Needs the PostgreSQL upstream (PGDG) repository enabled first; RHEL-compatible hosts also need EPEL and CRB — see [Package Installation](https://documentdb.io/packages). If the host cannot reach PGDG either, see [Offline / air-gapped](#offline--air-gapped). -```text -documentdb : Depends: documentdb-18 (>= 0.116.0) but it is not installable -``` - -This is not a defect in the packages — the same thing happens to any local `.deb` or `.rpm` whose dependencies are not in an enabled repository. Pass the whole set for your platform to one command. - -This still assumes the host can reach PGDG for PostgreSQL itself. If it cannot, see [Offline / air-gapped install](#offline--air-gapped-install), which stages the whole dependency closure and restores single-command installs. +Pass all six files for your platform to **one** command. `apt` and `dnf` resolve dependencies only from repository indexes, so the meta package alone fails with `documentdb : Depends: documentdb-18 (>= 0.116.0) but it is not installable`. ### DEB (Ubuntu 24.04, PostgreSQL 18, amd64) -For arm64 swap `amd64` → `arm64`; for PostgreSQL 17 swap `18` → `17`. Only the gateway and extension assets carry an architecture — the other four are `_all.deb` and are the same file on both. +For arm64 swap `amd64` → `arm64`; for PostgreSQL 17 swap `18` → `17`. Only the gateway and extension assets are arch-specific — the other four are `_all.deb`. ```bash sudo apt install ./ubuntu24.04-documentdb_0.116.0_all.deb \ @@ -98,73 +92,19 @@ sudo dnf install ./documentdb-0.116.0-1.noarch.rpm \ The `ubuntu24.04-` and `rhel9-` filename prefixes disambiguate release assets; they are not part of the package name. -Both families need the PostgreSQL upstream (PGDG) repository enabled first, and RHEL-compatible hosts additionally need EPEL and CRB. See [Package Installation](https://documentdb.io/packages) for those prerequisites. - ### Extension only, from a single file -If the target already has PostgreSQL and the PGDG extension dependencies (`postgresql-N-cron`, `-pgvector`, `-postgis-3`), the extension package installs from one file, with no gateway and no `documentdb-setup`: +If the target already has PostgreSQL and the PGDG extension dependencies (`postgresql-N-cron`, `-pgvector`, `-postgis-3`), the extension installs from one file — no gateway, no `documentdb-setup`: ```bash sudo apt install ./ubuntu24.04-postgresql-18-documentdb_0.116-0_amd64.deb ``` -## Offline / air-gapped install - -An air-gapped host needs more than the DocumentDB assets: the packages depend on PostgreSQL itself and on `pg_cron`, `pgvector` and PostGIS from PGDG, none of which are on the release page. Stage the whole dependency closure on a connected machine first. - -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 for an online install, 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 then looks complete but 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. - -Expect roughly 200 packages / 200 MB for the DEB closure and 270 packages / 170 MB for the RPM closure, dominated by PostGIS and its GDAL dependencies. - -Two warnings from the DEB staging step are expected and 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, point the package manager at it, and install with one command — the local index gives you full dependency resolution, so you do not have to name the packages individually or order them correctly: - -```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 -``` +## Offline / air-gapped -`[trusted=yes]` and `gpgcheck=0` tell the package manager to accept the local directory, which has no repository signature of its own. The upstream signatures were already verified when the bundle was staged; verify the transfer itself with `sha256sum` if the bundle crosses an untrusted boundary. +Release assets alone are not enough — DocumentDB also needs PostgreSQL, `pg_cron`, `pgvector` and PostGIS from PGDG. Stage the full dependency closure on a connected machine of the **same distro, release and architecture**, serve it to the target as a local repository, then install with one command. Commands: [Offline / air-gapped install](https://documentdb.io/docs/getting-started/packages/#offline-air-gapped-install). -Then continue with [Set up and connect](#set-up-and-connect) as normal — `documentdb-setup` needs no network. +> Stage with `apt-cache depends --recurse` / `dnf download --alldeps`. `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`. ## Set up and connect From 0bbed618b47df4dad81e2eb7cf15f8d8c82ed855 Mon Sep 17 00:00:00 2001 From: Guanzhou Song Date: Tue, 25 Aug 2026 12:17:54 -0400 Subject: [PATCH 5/5] Reduce the packages page to a release-asset reference A clarity review found this file competing with documentdb.io rather than complementing it. documentdb.io/docs/getting-started/packages/ is the canonical guide -- repository setup, CRB, architecture, connect, network exposure, verify/operate, upgrade, extension-only hosts, troubleshooting -- and this page renders there as a "this page has moved" stub, so it is read almost entirely by people browsing this repository. It duplicated most of that content, and 44% of the page came before the first install command. Keep only what the website does not own: the release-asset filenames, the six-file install commands, SHA256SUMS, the package-set table, the build matrix, and the container tags. Everything else becomes a link. Lead with the repository install as the easiest path, then the assets. Merge "Latest Release", "What ships in a release" and "Package Matrix" into one "What each release publishes" section and move it below the install, since it is consulted rather than followed. Drop the per-release changelog paragraph, which duplicates the release notes and goes stale every release, and the version-grammar paragraph, which the asset-name examples already demonstrate. Drop `docker pull` and `docker tag` from the container section: the tag it creates is never used again on the page, and `docker run` implies the pull. The two note blockquotes become one line. Switch the mongosh example to the credential-flag form, which needs no percent-encoding caveat. 1,565 -> 878 words. All five external links verified to return 200, including the documentdb.io offline anchor. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: f18515db-c52f-4197-aa50-d81359c7c763 Signed-off-by: Guanzhou Song --- getting-started/prebuilt-packages.md | 115 ++++++++++----------------- 1 file changed, 44 insertions(+), 71 deletions(-) diff --git a/getting-started/prebuilt-packages.md b/getting-started/prebuilt-packages.md index 0e2de34..1d2e6e5 100644 --- a/getting-started/prebuilt-packages.md +++ b/getting-started/prebuilt-packages.md @@ -1,66 +1,17 @@ --- title: Pre-built Packages -description: Download and install DocumentDB using the pre-built Linux packages and container image published with each release. +description: Install DocumentDB from the package repository, or from the release assets and container image published with each release. --- # Pre-built Packages -Download and install DocumentDB using the pre-built packages and container image published with each release. +**Easiest path:** install from the package repository — the package manager resolves the dependency graph for you. See [Linux Packages Quick Start](https://documentdb.io/docs/getting-started/packages/) for the exact command for your distribution, or the [Package Finder](https://documentdb.io/packages). -## Latest Release - -The current release is [`v0.116-0`](https://github.com/documentdb/documentdb/releases/tag/v0.116-0), published on 2026-08-20. It also carries the changes prepared for `v0.115-0`, which was never published. - -This release introduces a redesigned Linux packaging layout (see below), fixes a gateway connection-pool bug that evicted pools while they were still in use, fixes a backend crash on insert into a sharded collection from a pooled session on PostgreSQL 18.6 or newer, defaults TOAST compression to `lz4`, and stamps build provenance into the `documentdb-local` image. - -> `v0.116-0` publishes Linux packages only. macOS and Windows installers are not part of this release. - -## What ships in a release - -Before `v0.116-0` a release published a single package per PostgreSQL major — the extension. It now publishes a set: - -| Package | Role | -| --- | --- | -| `documentdb` (meta) + `documentdb-N` | Full stand-alone install. Pins PostgreSQL major N and its extension, and owns the systemd lifecycle. The meta package pins PostgreSQL 18. | -| `postgresql-N-documentdb` | The PostgreSQL extension for major N (files only). | -| `documentdb-gateway` | Wire-protocol runtime that serves the MongoDB-compatible endpoint. | -| `documentdb-postgresql-tools` | Administrator helpers: `documentdb-tune`, `documentdb-createcluster`, `documentdb-register-gateway`, `documentdb-gateway-admin`. | -| `documentdb-common` | Shared, PostgreSQL-agnostic payload: `documentdb-setup`, the systemd template units, helper scripts and sample data. | - -Two version grammars are in play by design: on DEB the extension keeps the control-file form `0.116-0` while every other package uses `0.116.0`; on RPM everything is `0.116.0` (the extension's `-0` becomes the RPM release field, giving `0.116.0-1`). - -## Package Matrix - -`v0.116-0` builds and tests a first-party matrix of Ubuntu 24.04 and RHEL-compatible 9: - -| Package family | Distributions | PostgreSQL versions | Architectures | Downloads | -| --- | --- | --- | --- | --- | -| DEB | Ubuntu 24.04 | 17, 18 | amd64, arm64 | [v0.116-0 release assets](https://github.com/documentdb/documentdb/releases/tag/v0.116-0) | -| RPM | RHEL-compatible 9 | 17, 18 | x86_64, aarch64 | [v0.116-0 release assets](https://github.com/documentdb/documentdb/releases/tag/v0.116-0) | - -Other combinations — PostgreSQL 15/16, Debian 11/12/13, Ubuntu 22.04, RHEL-compatible 8 — are not built by first-party CI for this release. Build them on demand from the tag with the scripts in [`packaging/`](https://github.com/documentdb/documentdb/blob/main/packaging/README.md), or install the newest release that did build them from the package repository (see below). PostgreSQL 15 is extension-only: `documentdb-setup` and `documentdb-register-gateway` require PostgreSQL 16 or newer. - -Choose the asset whose filename matches your distribution, PostgreSQL major version, and CPU architecture. For example: - -- `ubuntu24.04-documentdb_0.116.0_all.deb` -- `ubuntu24.04-postgresql-18-documentdb_0.116-0_amd64.deb` -- `rhel9-postgresql18-documentdb-0.116.0-1.el9.x86_64.rpm` - -Every release also ships `SHA256SUMS` and `manifest.txt`. Verify what you downloaded: - -```bash -gh release download v0.116-0 -R documentdb/documentdb -D pkgs && cd pkgs && sha256sum -c SHA256SUMS -``` - -## Repository-backed install (recommended) - -Installing from is easier than downloading assets, because the package manager resolves the dependencies between the packages for you. See [Package Installation](https://documentdb.io/packages) for the exact command for your distribution. - -The repository also keeps the most recent package for distributions a given release did not build, so Ubuntu 22.04, Debian 11/12/13 and RHEL-compatible 8 continue to resolve the extension package from an earlier release. +This page covers the **release assets** instead: what each release publishes, and how to install from downloaded files. ## Install from downloaded assets -Needs the PostgreSQL upstream (PGDG) repository enabled first; RHEL-compatible hosts also need EPEL and CRB — see [Package Installation](https://documentdb.io/packages). If the host cannot reach PGDG either, see [Offline / air-gapped](#offline--air-gapped). +Enable the PostgreSQL upstream (PGDG) repository first; RHEL-compatible hosts also need EPEL and CRB — see [Package Installation](https://documentdb.io/packages). Pass all six files for your platform to **one** command. `apt` and `dnf` resolve dependencies only from repository indexes, so the meta package alone fails with `documentdb : Depends: documentdb-18 (>= 0.116.0) but it is not installable`. @@ -79,7 +30,7 @@ sudo apt install ./ubuntu24.04-documentdb_0.116.0_all.deb \ ### RPM (RHEL-compatible 9, PostgreSQL 18, x86_64) -For arm64 swap `x86_64` → `aarch64`; for PostgreSQL 17 swap `18` → `17`. As with DEB, only the gateway and extension assets are architecture-specific; the other four are `noarch`. +For arm64 swap `x86_64` → `aarch64`; for PostgreSQL 17 swap `18` → `17`. Only the gateway and extension assets are arch-specific; the other four are `noarch`. ```bash sudo dnf install ./documentdb-0.116.0-1.noarch.rpm \ @@ -94,13 +45,13 @@ The `ubuntu24.04-` and `rhel9-` filename prefixes disambiguate release assets; t ### Extension only, from a single file -If the target already has PostgreSQL and the PGDG extension dependencies (`postgresql-N-cron`, `-pgvector`, `-postgis-3`), the extension installs from one file — no gateway, no `documentdb-setup`: +If the host already has PostgreSQL and the PGDG extension dependencies (`postgresql-N-cron`, `-pgvector`, `-postgis-3`), the extension installs from one file — no gateway, no `documentdb-setup`: ```bash sudo apt install ./ubuntu24.04-postgresql-18-documentdb_0.116-0_amd64.deb ``` -## Offline / air-gapped +### Offline / air-gapped Release assets alone are not enough — DocumentDB also needs PostgreSQL, `pg_cron`, `pgvector` and PostGIS from PGDG. Stage the full dependency closure on a connected machine of the **same distro, release and architecture**, serve it to the target as a local repository, then install with one command. Commands: [Offline / air-gapped install](https://documentdb.io/docs/getting-started/packages/#offline-air-gapped-install). @@ -117,32 +68,54 @@ sudo documentdb-setup --admin-user admin It prompts for the admin password; for servers and CI pass `--admin-password-file ` or `--admin-password-stdin` together with `--yes`. Then connect (`mongosh` is not shipped by these packages): ```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})' ``` -> The gateway binds all interfaces (`0.0.0.0:10260`) by default, even though the connect string above says `127.0.0.1`. Firewall the port and supply a real certificate before exposing it to a network. +> The gateway binds all interfaces (`0.0.0.0:10260`) by default, even though it is reached at `127.0.0.1` above. Firewall the port and supply a real certificate before exposing it to a network. + +## What each release publishes + +[`v0.116-0`](https://github.com/documentdb/documentdb/releases/tag/v0.116-0) (2026-08-20) — Linux packages only; no macOS or Windows installers. It also carries the unpublished `v0.115-0` changes. Fix list: [release notes](https://github.com/documentdb/documentdb/releases/tag/v0.116-0). + +Since `v0.116-0` a release publishes a package set rather than a lone extension: + +| Package | Role | +| --- | --- | +| `documentdb` (meta) + `documentdb-N` | Full stand-alone install. Pins PostgreSQL major N and its extension, and owns the systemd lifecycle. The meta package pins PostgreSQL 18. | +| `postgresql-N-documentdb` | The PostgreSQL extension for major N (files only). | +| `documentdb-gateway` | Wire-protocol runtime that serves the MongoDB-compatible endpoint. | +| `documentdb-postgresql-tools` | Administrator helpers: `documentdb-tune`, `documentdb-createcluster`, `documentdb-register-gateway`, `documentdb-gateway-admin`. | +| `documentdb-common` | Shared, PostgreSQL-agnostic payload: `documentdb-setup`, the systemd template units, helper scripts and sample data. | + +First-party CI builds and tests Ubuntu 24.04 (DEB) and RHEL-compatible 9 (RPM), on PostgreSQL 17 and 18, for both architectures: -## Docker Images +| Family | Architectures | Asset name | +| --- | --- | --- | +| DEB | amd64, arm64 | `ubuntu24.04-postgresql-18-documentdb_0.116-0_amd64.deb` | +| RPM | x86_64, aarch64 | `rhel9-postgresql18-documentdb-0.116.0-1.el9.x86_64.rpm` | -Use the official `documentdb-local` image from GHCR: +Note the two version grammars: on DEB the extension keeps `0.116-0` while every other package uses `0.116.0`; on RPM everything is `0.116.0-1`. + +Everything else — PostgreSQL 15/16, Debian 11/12/13, Ubuntu 22.04, RHEL-compatible 8 — is not built by first-party CI for this release. The [package repository](https://documentdb.io/packages) serves those targets the extension package from an earlier release, or build from the tag with the scripts in [`packaging/`](https://github.com/documentdb/documentdb/blob/main/packaging/README.md). PostgreSQL 15 is extension-only: `documentdb-setup` needs 16 or newer. + +Every release also ships `SHA256SUMS` and `manifest.txt`: ```bash -# Pull the published image -docker pull ghcr.io/documentdb/documentdb/documentdb-local:latest +gh release download v0.116-0 -R documentdb/documentdb -D pkgs && cd pkgs && sha256sum -c SHA256SUMS +``` -# Tag the image for convenience -docker tag ghcr.io/documentdb/documentdb/documentdb-local:latest documentdb +## Container image -# Run the container with your chosen username and password -docker run -dt -p 10260:10260 --name documentdb-container ghcr.io/documentdb/documentdb/documentdb-local:latest --username --password +```bash +docker run -dt -p 10260:10260 --name documentdb-container \ + ghcr.io/documentdb/documentdb/documentdb-local:latest \ + --username --password ``` -> **Note:** Replace `` and `` with your desired credentials. You must set these when creating the container for authentication to work. -> -> **Port Note:** Port `10260` is used by default in these instructions to avoid conflicts with other local database services. You can use port `27017` (the standard MongoDB port) or any other available port if you prefer. If you do, be sure to update the port number in both your `docker run` command and your connection string accordingly. +Credentials must be set at create time or authentication will not work. Port `10260` avoids clashing with a local MongoDB; if you prefer `27017`, change both the `-p` flag and your connection string. -`v0.116-0` publishes the following multi-architecture tags (linux/amd64 and linux/arm64) to GHCR: +`v0.116-0` publishes these multi-architecture tags (linux/amd64 and linux/arm64): - `ghcr.io/documentdb/documentdb/documentdb-local:pg15-0.116.0` - `ghcr.io/documentdb/documentdb/documentdb-local:pg16-0.116.0`