From f8b64993729f8231f1aaf214558e3192338c4a50 Mon Sep 17 00:00:00 2001 From: Guanzhou Song Date: Thu, 10 Sep 2026 11:15:49 -0400 Subject: [PATCH 1/4] Document the retired package repositories and their cleanup The 0.117 page already states that other targets are outside the hosted package matrix and that older packages are not retained, but it stops short of what an operator on a retired target actually has to do. Record that the withdrawal also pulled the older PostgreSQL 16 extension packages from the Ubuntu 24.04 and RHEL-compatible 9 repositories, that empty signed metadata is deliberately parked at the retired repository URLs so package-manager refreshes keep working, and how to remove the repository configuration. Name the three packaging entry points so a community build of an unhosted target does not require reading the packaging tree first. Verified against the live documentdb.io package guidance and against packaging/build_packages.sh, packaging/gateway/build_gateway_packages.sh and packaging/build_extra_packages.sh in the source repository. Claude-Session: https://claude.ai/code/session_01Bg344Sg5hCgoxD6aPsbp5b --- getting-started/prebuilt-packages.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/getting-started/prebuilt-packages.md b/getting-started/prebuilt-packages.md index aff7103..79c3bf7 100644 --- a/getting-started/prebuilt-packages.md +++ b/getting-started/prebuilt-packages.md @@ -132,6 +132,20 @@ Note the two version grammars: on DEB the extension keeps `0.117-0` while every Other targets — PostgreSQL 15/16, Debian 11/12/13, Ubuntu 22.04, and RHEL-compatible 8 — are not in the current hosted package matrix. The [package repository](https://documentdb.io/packages) does not retain older packages for those targets. Existing installations keep running, but cannot receive updates or reinstall those packages from that repository. Use matching older GitHub release assets or build from the chosen tag; the [0.117 packaging guide](https://github.com/documentdb/documentdb/blob/v0.117-0/packaging/README.md) describes build-on-demand options. PostgreSQL 15 is extension-only: `documentdb-setup` needs 16 or newer. +That withdrawal, which began with v0.116, also covers the older PostgreSQL 16 extension packages previously served from the Ubuntu 24.04 and RHEL-compatible 9 repositories, so a host on one of those repositories can no longer reinstall the package it was set up from. Empty signed metadata remains at the retired repository URLs so package-manager refreshes do not break unrelated operations. Remove the repository configuration on a host that will not move to the current matrix: + +```bash +# Debian / Ubuntu +sudo rm -f /etc/apt/sources.list.d/documentdb.list +sudo apt update + +# RHEL-compatible +sudo rm -f /etc/yum.repos.d/documentdb.repo +sudo dnf clean all +``` + +Community builds for other targets are welcome; the packaging scripts stay version-parametric. `build_packages.sh` builds the extension, `gateway/build_gateway_packages.sh` builds the gateway, and `build_extra_packages.sh` builds the common, tools, stand-alone, and meta packages. + ## Container image ```bash From 41a95676ab4381711e061e386ec7a0b21bef2907 Mon Sep 17 00:00:00 2001 From: Guanzhou Song Date: Thu, 10 Sep 2026 12:01:10 -0400 Subject: [PATCH 2/4] Clarify package installation paths and distribution options Lead with stand-alone setup and explain component-level PostgreSQL and gateway workflows. Document PGDG and source builds, with release assets and retired-target guidance kept as reference. Copilot-Session: e7d486f5-141c-47f0-ad9e-8bce20fdb52f Signed-off-by: Guanzhou Song --- getting-started/prebuilt-packages.md | 270 +++++++++++++++++---------- 1 file changed, 173 insertions(+), 97 deletions(-) diff --git a/getting-started/prebuilt-packages.md b/getting-started/prebuilt-packages.md index 79c3bf7..5986ffe 100644 --- a/getting-started/prebuilt-packages.md +++ b/getting-started/prebuilt-packages.md @@ -1,74 +1,112 @@ --- title: Pre-built Packages -description: Install DocumentDB from the package repository, or from the release assets and container image published with each release. +description: Install the complete DocumentDB stack with a setup wizard, or choose individual PostgreSQL and gateway packages. Includes PGDG and source-build options. --- # Pre-built Packages -**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). +Install a complete MongoDB-compatible service, or add only the components you need to PostgreSQL you manage. Since v0.116, DocumentDB's packages include a setup wizard, administrator tools, and systemd integration. -This page covers the **release assets** instead: what each release publishes, and how to install from downloaded files. +Get first-party packages from [documentdb.io](https://documentdb.io/packages), extension packages from [PGDG](#pgdg-extension-packages), or [build packages for another target](#community-builds) with the provided scripts. -## Download and verify +## Choose an installation path -The current release is [`v0.117-0`](https://github.com/documentdb/documentdb/releases/tag/v0.117-0), published on **2026-09-10**. It includes 22 Linux packages, plus `SHA256SUMS` and `manifest.txt`. +| You want | Installation | +| --- | --- | +| A working DocumentDB instance with minimal setup | **[Stand-alone stack](#set-up-and-connect), recommended:** install `documentdb` and run the wizard. | +| MongoDB-compatible access to PostgreSQL you manage | [Extension + gateway](#add-a-gateway): configure the components separately and retain your PostgreSQL service lifecycle. | +| DocumentDB through SQL, without a gateway | [Extension only](#extension-only-installation): install the extension and optional administrator tools. | -```bash -gh release download v0.117-0 -R documentdb/documentdb -D pkgs && cd pkgs && sha256sum -c SHA256SUMS -``` +## First-party packages -This downloads both package formats, both architectures, and both supported PostgreSQL majors. Install only the matching subset below, not every downloaded file. The [release notes](https://github.com/documentdb/documentdb/releases/tag/v0.117-0) describe the changes in this version. +The current release is [`v0.117-0`](https://github.com/documentdb/documentdb/releases/tag/v0.117-0), published on **2026-09-10**. First-party CI builds and tests the full stack for: -## Install from downloaded assets +| Distribution | PostgreSQL | Architectures | +| --- | --- | --- | +| Ubuntu 24.04 (DEB) | 17, 18 | amd64, arm64 | +| RHEL-compatible 9 (RPM) | 17, 18 | x86_64, aarch64 | -Enable the PostgreSQL upstream (PGDG) repository first; RHEL-compatible hosts also need EPEL and CRB — see [Package Installation](https://documentdb.io/packages). +Ubuntu 24.04 with PostgreSQL 18 is the recommended default. Other targets may be available through PGDG or the build scripts; they are not part of this hosted matrix. -Pass the matching package set to **one** command. `apt` and `dnf` need all local dependencies in the same transaction, so the meta package alone fails with `documentdb : Depends: documentdb-18 (>= 0.117.0) but it is not installable`. +## Set up and connect -### DEB (Ubuntu 24.04, PostgreSQL 18, amd64) +These steps are for a **new stand-alone installation**. For an existing deployment, read [Upgrades and retired targets](#upgrades-and-retired-targets) first. + +### 1. Install the stack -For arm64 swap `amd64` → `arm64`. Only the gateway and extension assets are arch-specific — the other four are `_all.deb`. +Use the [Package Finder](https://documentdb.io/packages) or [Linux Packages Quick Start](https://documentdb.io/docs/getting-started/packages/) to configure the repositories for your distribution and architecture. First-party packages depend on PostgreSQL and extensions from PGDG; EL9 also needs EPEL and CRB / CodeReady Builder. + +With the repositories configured, install the stack on Ubuntu: ```bash -sudo apt install ./ubuntu24.04-documentdb_0.117.0_all.deb \ - ./ubuntu24.04-documentdb-18_0.117.0_all.deb \ - ./ubuntu24.04-documentdb-common_0.117.0_all.deb \ - ./ubuntu24.04-documentdb-postgresql-tools_0.117.0_all.deb \ - ./ubuntu24.04-documentdb-gateway_0.117.0_amd64.deb \ - ./ubuntu24.04-postgresql-18-documentdb_0.117-0_amd64.deb +sudo apt install documentdb ``` -For PostgreSQL 17, select `documentdb-17` and `postgresql-17-documentdb` instead and **omit `ubuntu24.04-documentdb_0.117.0_all.deb`**. The meta package always selects PG18; the PG17 installation uses five files. +On EL9, use `sudo dnf install documentdb`. Both `documentdb` (the PG18 default) and `documentdb-18` (used by the Package Finder) install the complete stack. -### RPM (RHEL-compatible 9, PostgreSQL 18, x86_64) +### 2. Run the setup wizard -For arm64 swap `x86_64` → `aarch64`. Only the gateway and extension assets are arch-specific; the other four are `noarch`. +> The gateway listens on all interfaces by default. Restrict access to port `10260` before setup on a network-accessible host; use a trusted certificate before allowing remote clients. ```bash -sudo dnf install ./documentdb-0.117.0-1.noarch.rpm \ - ./documentdb-18-0.117.0-1.noarch.rpm \ - ./documentdb-common-0.117.0-1.noarch.rpm \ - ./documentdb-postgresql-tools-0.117.0-1.noarch.rpm \ - ./documentdb-gateway-0.117.0-1.el9.x86_64.rpm \ - ./rhel9-postgresql18-documentdb-0.117.0-1.el9.x86_64.rpm +sudo documentdb-setup --pg-version 18 --use-new-postgres-instance --admin-user admin ``` -For PostgreSQL 17, select `documentdb-17` and `rhel9-postgresql17-documentdb` instead and **omit `documentdb-0.117.0-1.noarch.rpm`**. The meta package always selects PG18; the PG17 installation uses five files. - -The `ubuntu24.04-` and `rhel9-` filename prefixes disambiguate release assets; they are not part of the package name. +The wizard prompts for the admin password, creates a private PostgreSQL 18 instance, configures extensions and the admin user, and starts the gateway. On systemd hosts it also enables the stack at boot. -### Extension-only installation +### 3. Connect -If the host already has PostgreSQL and the PGDG extension dependencies (`postgresql-N-cron`, `-pgvector`, `-postgis-3`), install the extension payload together with the administrator tools. This does not install the stand-alone gateway or `documentdb-setup`: +Install [mongosh](https://www.mongodb.com/docs/mongodb-shell/install/) separately, then connect interactively: ```bash -sudo apt install ./ubuntu24.04-documentdb-postgresql-tools_0.117.0_all.deb \ - ./ubuntu24.04-postgresql-18-documentdb_0.117-0_amd64.deb +mongosh localhost:10260 --authenticationMechanism SCRAM-SHA-256 \ + --tls --tlsAllowInvalidCertificates -u admin -p +``` + +Enter the password set in the wizard, then run: + +```javascript +db.runCommand({ ping: 1 }) ``` -For PostgreSQL 17, use `ubuntu24.04-postgresql-17-documentdb_0.117-0_amd64.deb` instead. For arm64, replace `amd64` with `arm64` in the extension filename; the tools package is PostgreSQL- and architecture-independent. +The local example accepts the generated self-signed certificate. A bare `-p` prompts for a password; non-interactive scripts must supply a password explicitly. -In 0.117, `documentdb_extended_rum` is required by default on every supported PostgreSQL major. For the default PostgreSQL 18 cluster on Ubuntu, configure it, restart it, and create both extensions in the `postgres` database: +### Optional setup controls + +| Requirement | How | +| --- | --- | +| Use PostgreSQL 17 | Install `documentdb-17` instead of `documentdb`, and use `--pg-version 17`. | +| Preview changes | Add `--dry-run` before applying setup. | +| Change the gateway port | Add `--listen-port 27017`, or another unused port. | +| Load sample data | Add `--load-sample-data` to load [StoreData](https://documentdb.io/docs/documentdb-local/#built-in-sample-data); requires `mongosh`. | +| Automate setup | Use `--yes` with `--admin-password-file /path/to/protected-file` (mode `0600`) or `--admin-password-stdin`. | +| Adopt an existing local PostgreSQL instance | Replace `--use-new-postgres-instance` with `--target-postgres-instance 18/main`; review the proposed changes and plan PostgreSQL restarts. | + +Inspect state with `sudo documentdb-setup --pg-version 18 --status`. On systemd, restart this stack with `sudo systemctl restart documentdb-local@18.target`; adopted PostgreSQL retains its own lifecycle. See [Operating a package install](https://documentdb.io/docs/linux-packages/) for TLS and other operational guidance. + +## What each release publishes + +`N` is the PostgreSQL major. The package manager installs the dependencies of your selected package. + +| Package | Purpose | +| --- | --- | +| `documentdb` | Convenience meta package selecting `documentdb-18`; also provides the `documentdb-local.target` alias. | +| `documentdb-N` | Complete stand-alone stack for major N; owns its systemd lifecycle. | +| `postgresql-N-documentdb` (DEB) / `postgresqlN-documentdb` (RPM) | Extension libraries and SQL files only; does not configure existing PostgreSQL instances. | +| `documentdb-postgresql-tools` | `documentdb-tune`, `documentdb-createcluster`, `documentdb-register-gateway`, and `documentdb-gateway-admin`. | +| `documentdb-gateway` | MongoDB wire-protocol runtime and its service; does not configure PostgreSQL. | +| `documentdb-common` | Shared wizard, service templates, helpers, and sample data, pulled in by `documentdb-N`. | + +## Extension-only installation + +This **alternative** uses first-party packages on Ubuntu 24.04 with an administrator-managed PostgreSQL 18 cluster named `main`. Install only the extension and tools, not `documentdb` or `documentdb-N`: + +```bash +sudo apt install postgresql-18-documentdb documentdb-postgresql-tools +sudo documentdb-tune --pg-version 18 --cluster main --dry-run +``` + +Review the proposed configuration, then apply it during a suitable restart window: ```bash sudo documentdb-tune --pg-version 18 --cluster main --yes @@ -78,102 +116,140 @@ sudo -u postgres /usr/bin/psql --cluster 18/main -d postgres -v ON_ERROR_STOP=1 -c "CREATE EXTENSION IF NOT EXISTS documentdb_extended_rum CASCADE;" ``` -Change `18` and `main` to the PostgreSQL major and cluster you are configuring. `documentdb-tune` prints the appropriate restart and connection commands for non-default instances. Both extension statements must run after the restart; `CREATE EXTENSION documentdb CASCADE` does not create `documentdb_extended_rum` automatically. See the [PostgreSQL package setup procedure](https://documentdb.io/docs/getting-started/packages/) for other instance layouts. +In 0.117, both extension statements are required after the restart; `CASCADE` does not create `documentdb_extended_rum`. Adjust the major and cluster name for your instance. For other layouts, follow the restart and connection commands printed by `documentdb-tune`. -### Offline / air-gapped +For a **new** Debian/Ubuntu cluster, `sudo documentdb-createcluster 18 docdb --start` combines cluster creation, tuning, startup, and extension creation. Choose a cluster name that does not already exist. -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/linux-packages/offline/). +### Add a gateway -> 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`. +After the extension-only steps, install and register a gateway. Store the admin password in a protected file (mode `0600`) and substitute its path below: -## Set up and connect +```bash +sudo apt install documentdb-gateway +sudo documentdb-register-gateway --target-postgres-instance 18/main \ + --admin-user admin --admin-password-file /path/to/admin-password --yes +sudo systemctl reload postgresql@18-main +sudo systemctl enable --now documentdb-gateway +``` + +Registration configures authentication and the admin user. Connect with `mongosh` as above. This path uses `documentdb-gateway.service`, not the stand-alone target, and requires PostgreSQL on the **same host**; remote TCP/password backends are not supported by package-managed registration. -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: +## PGDG extension packages + +DocumentDB is also included in the **PostgreSQL Global Development Group (PGDG) APT repository**, with packaging maintained by the Debian PostgreSQL team. This is an extension-only distribution: it does not include the first-party gateway, setup wizard, or administrator tools. + +For example, as of **2026-09-10**, PGDG publishes DocumentDB **0.116** for Debian 13 (`trixie-pgdg`), PostgreSQL **15-18**, on **amd64 and arm64**. Versions and targets differ from first-party releases; consult the [PGDG package pool](https://apt.postgresql.org/pub/repos/apt/pool/main/d/documentdb/). + +For a new Debian 13 installation, follow the [PGDG repository setup instructions](https://www.postgresql.org/download/linux/debian/#apt), then inspect the candidate for your chosen PostgreSQL major: ```bash -sudo documentdb-setup --admin-user admin +sudo apt update +apt-cache policy postgresql-16-documentdb ``` -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). A bare `-p` makes `mongosh` prompt, so pass the password inline in scripts — a non-interactive shell otherwise sends an empty one and fails with the unhelpful `MongoServerError: Invalid key`: +If PGDG provides a candidate for your host, install it: ```bash -mongosh localhost:10260 -u admin -p '' --authenticationMechanism SCRAM-SHA-256 \ - --tls --tlsAllowInvalidCertificates --eval 'db.runCommand({ping: 1})' +sudo apt install postgresql-16-documentdb ``` -> 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. - -Add `--load-sample-data` to the setup command to load the optional `StoreData` dataset. This requires `mongosh`; see [Built-in sample data](https://documentdb.io/docs/documentdb-local/#built-in-sample-data) for the collection contents. +Configure PostgreSQL and create the extensions for that packaged version separately; the first-party helper commands above do not apply. Do not use another distribution's repository to obtain a missing package, or treat a provider switch as an in-place upgrade. -> **Pre-GA:** In-place package upgrades from earlier releases are not supported yet. Use a clean host or a newly created PostgreSQL instance. Removing packages preserves the existing PostgreSQL data directory and does not turn that instance into a clean installation; do not reset or reuse an adopted instance as an upgrade workaround. +## Community builds -## What each release publishes +Can't find a package for your target? The supplied scripts build DEB or RPM packages with Docker; select the distribution and PostgreSQL major rather than writing packaging files yourself. -The `v0.117-0` native assets are Linux packages; there are no macOS or Windows installers. Use the container image below on those hosts. +Use a Linux build environment with Git, Docker, Bash 4+, and GNU utilities, on the target architecture. For example, build the extension for Debian 12 and PostgreSQL 18: -Since `v0.116-0` a release publishes a package set rather than a lone extension: +```bash +git clone --depth 1 --branch v0.117-0 https://github.com/documentdb/documentdb.git +cd documentdb +./packaging/build_packages.sh --os deb12 --pg 18 --output-dir packages +``` -| 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` (DEB) / `postgresqlN-documentdb` (RPM) | 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. | +For the full stand-alone DEB set, make `dpkg-deb` available on the build host, then build the gateway and shared packages: -First-party CI builds and tests Ubuntu 24.04 (DEB) and RHEL-compatible 9 (RPM), on PostgreSQL 17 and 18, for both architectures: +```bash +./packaging/gateway/build_gateway_packages.sh --os deb12 --pg 18 \ + --version 0.117.0 --output-dir packages +./packaging/build_extra_packages.sh --type deb --pg 18 \ + --version 0.117.0 --output-dir packages +``` -| Family | Architectures | Asset name | -| --- | --- | --- | -| DEB | amd64, arm64 | `ubuntu24.04-postgresql-18-documentdb_0.117-0_amd64.deb` | -| RPM | x86_64, aarch64 | `rhel9-postgresql18-documentdb-0.117.0-1.el9.x86_64.rpm` | +Outputs go into `packages/`. RPM extras instead require host `rpmbuild` and applicable RPM macros. The [versioned packaging guide](https://github.com/documentdb/documentdb/blob/v0.117-0/packaging/README.md) lists targets, prerequisites, and clean-install checks. -Note the two version grammars: on DEB the extension keeps `0.117-0` while every other package uses `0.117.0`; on RPM the version is `0.117.0`, with release `1` or `1.el9`. +Validate builds for targets outside the first-party CI matrix in your environment. PostgreSQL 15 is extension-only; package-managed gateway setup requires PostgreSQL 16 or newer. -Other targets — PostgreSQL 15/16, Debian 11/12/13, Ubuntu 22.04, and RHEL-compatible 8 — are not in the current hosted package matrix. The [package repository](https://documentdb.io/packages) does not retain older packages for those targets. Existing installations keep running, but cannot receive updates or reinstall those packages from that repository. Use matching older GitHub release assets or build from the chosen tag; the [0.117 packaging guide](https://github.com/documentdb/documentdb/blob/v0.117-0/packaging/README.md) describes build-on-demand options. PostgreSQL 15 is extension-only: `documentdb-setup` needs 16 or newer. +## Download and verify -That withdrawal, which began with v0.116, also covers the older PostgreSQL 16 extension packages previously served from the Ubuntu 24.04 and RHEL-compatible 9 repositories, so a host on one of those repositories can no longer reinstall the package it was set up from. Empty signed metadata remains at the retired repository URLs so package-manager refreshes do not break unrelated operations. Remove the repository configuration on a host that will not move to the current matrix: +Use release assets when you need an exact first-party version rather than a repository install. `v0.117-0` includes 22 Linux packages, `SHA256SUMS`, and `manifest.txt`. ```bash -# Debian / Ubuntu -sudo rm -f /etc/apt/sources.list.d/documentdb.list -sudo apt update +gh release download v0.117-0 -R documentdb/documentdb -D pkgs && cd pkgs && sha256sum -c SHA256SUMS +``` -# RHEL-compatible -sudo rm -f /etc/yum.repos.d/documentdb.repo -sudo dnf clean all +This downloads both formats, architectures, and PostgreSQL majors. Install only the matching subset below, not every downloaded file. + +## Install from downloaded assets + +Enable the dependency repositories first: PGDG, plus EPEL and CRB / CodeReady Builder on EL9. Pass the matching local files to **one** `apt` or `dnf` command so dependencies resolve in the same transaction. + +These examples install `documentdb-18` and its dependencies; the optional `documentdb` meta package is not needed. + +### DEB (Ubuntu 24.04, PostgreSQL 18, amd64) + +For arm64, replace `amd64` with `arm64`. Only the gateway and extension files are architecture-specific. + +```bash +sudo apt install ./ubuntu24.04-documentdb-18_0.117.0_all.deb \ + ./ubuntu24.04-documentdb-common_0.117.0_all.deb \ + ./ubuntu24.04-documentdb-postgresql-tools_0.117.0_all.deb \ + ./ubuntu24.04-documentdb-gateway_0.117.0_amd64.deb \ + ./ubuntu24.04-postgresql-18-documentdb_0.117-0_amd64.deb ``` -Community builds for other targets are welcome; the packaging scripts stay version-parametric. `build_packages.sh` builds the extension, `gateway/build_gateway_packages.sh` builds the gateway, and `build_extra_packages.sh` builds the common, tools, stand-alone, and meta packages. +### RPM (RHEL-compatible 9, PostgreSQL 18, x86_64) -## Container image +For arm64, replace `x86_64` with `aarch64`; leave `noarch` files unchanged. ```bash -read -r -p 'DocumentDB username: ' DOCUMENTDB_USERNAME -read -r -s -p 'DocumentDB password: ' DOCUMENTDB_PASSWORD -printf '\n' -export DOCUMENTDB_USERNAME DOCUMENTDB_PASSWORD - -docker run -dt -p 127.0.0.1:10260:10260 --name documentdb-container \ - ghcr.io/documentdb/documentdb/documentdb-local:pg17-0.117.0 \ - --username "${DOCUMENTDB_USERNAME:?DocumentDB username cannot be empty}" \ - --password "${DOCUMENTDB_PASSWORD:?DocumentDB password cannot be empty}" +sudo dnf install ./documentdb-18-0.117.0-1.noarch.rpm \ + ./documentdb-common-0.117.0-1.noarch.rpm \ + ./documentdb-postgresql-tools-0.117.0-1.noarch.rpm \ + ./documentdb-gateway-0.117.0-1.el9.x86_64.rpm \ + ./rhel9-postgresql18-documentdb-0.117.0-1.el9.x86_64.rpm ``` -The guards reject empty credentials so the container cannot fall through to its public defaults. The example binds only to the local host. To use host port `27017` while keeping the gateway on container port `10260`, publish `-p 127.0.0.1:27017:10260` and connect to `localhost:27017`. To change the internal gateway port too, add `--documentdb-port 27017`. +For PostgreSQL 17, replace the two PostgreSQL-specific files with their `17` equivalents; the shared packages stay the same. The `documentdb` meta package always selects PG18. + +For extension-only use, install the extension and tools files, then [configure PostgreSQL](#extension-only-installation). For a full stack, [run the wizard](#2-run-the-setup-wizard) with the installed major: use `--pg-version 17` for PG17. + +Filename prefixes such as `ubuntu24.04-` and `rhel9-` identify release assets, not package names. DEB extensions use version `0.117-0`, while other packages use `0.117.0`; RPMs use `0.117.0` with release `1` or `1.el9`. + +### Offline / air-gapped -`v0.117-0` publishes these multi-architecture tags (linux/amd64 and linux/arm64): +Release assets do not include the full dependency set. Stage PostgreSQL, its required extensions, and all other dependencies on a connected machine of the **same distro, release, and architecture**. Include dependencies already installed on the staging machine. Follow [Offline / air-gapped install](https://documentdb.io/docs/linux-packages/offline/) to serve the bundle as a local repository. -- `ghcr.io/documentdb/documentdb/documentdb-local:pg15-0.117.0` -- `ghcr.io/documentdb/documentdb/documentdb-local:pg16-0.117.0` -- `ghcr.io/documentdb/documentdb/documentdb-local:pg17-0.117.0` -- `ghcr.io/documentdb/documentdb/documentdb-local:pg18-0.117.0` -- `ghcr.io/documentdb/documentdb/documentdb-local:latest` (currently aliases `pg17-0.117.0`) +## Upgrades and retired targets -Use a versioned tag when you need a reproducible release rather than whichever version `latest` points to later. +**Pre-GA:** in-place package upgrades from earlier releases are not supported yet. Use a clean host or a new, empty PostgreSQL instance and plan data migration separately. Removing packages preserves PostgreSQL data; do not reset or reuse an adopted instance as an upgrade workaround. -Each image records the release it was built from in `/version.txt` and in its OCI labels: +The hosted matrix excludes PostgreSQL 15/16, Debian 11/12/13, Ubuntu 22.04, and RHEL-compatible 8. Since v0.116, older packages for retired targets are not carried forward, including PG16 extensions formerly hosted for Ubuntu 24.04 and EL9. Existing installations keep running, but cannot update or reinstall those packages from documentdb.io. + +For older installations, use matching [GitHub release assets](https://github.com/documentdb/documentdb/releases), including their dependencies, or consider PGDG and source builds where available. Changing provider or platform requires compatibility and recovery planning; it is not an automatic migration. + +Retired URLs retain empty signed metadata so package-manager refreshes do not disrupt unrelated operations. If a host will no longer use first-party packages, remove its DocumentDB repository entry. This removes neither packages nor data; keep PGDG if other packages still use it. ```bash -docker run --rm --entrypoint cat ghcr.io/documentdb/documentdb/documentdb-local:pg18-0.117.0 /version.txt +# Debian / Ubuntu +sudo rm -f /etc/apt/sources.list.d/documentdb.list +sudo apt update + +# RHEL-compatible +sudo rm -f /etc/yum.repos.d/documentdb.repo +sudo dnf clean all ``` + +## Container image + +For macOS, Windows, or a container-based installation, follow [DocumentDB Local](../documentdb-local/index.md). Release 0.117 provides Linux amd64/arm64 images for PostgreSQL 15-18; use a versioned tag rather than `latest` when you need a reproducible version. From 8109f1daaef6b913537ca687b57a580919909501 Mon Sep 17 00:00:00 2001 From: Guanzhou Song Date: Thu, 10 Sep 2026 12:17:50 -0400 Subject: [PATCH 3/4] Polish wording: fix grammar, jargon, and version-prefix consistency Claude-Session: https://claude.ai/code/session_011c6xisiohbFE7Ch5MGEqsv --- documentdb-local/index.md | 2 +- getting-started/nodejs-setup.md | 2 +- getting-started/prebuilt-packages.md | 16 ++++++++-------- getting-started/vscode-quickstart.md | 2 +- postgres-api/configuration.md | 2 +- 5 files changed, 12 insertions(+), 12 deletions(-) diff --git a/documentdb-local/index.md b/documentdb-local/index.md index 7d5e661..d87cd0a 100644 --- a/documentdb-local/index.md +++ b/documentdb-local/index.md @@ -7,7 +7,7 @@ description: Learn how to install and run DocumentDB Local using Docker for loca DocumentDB Local provides a lightweight, containerized environment for developing and testing applications locally, including prototyping and integration testing. -The examples below use the PostgreSQL 17 image from release **0.117.0**. Other PostgreSQL majors and image tags are listed in the [0.117 release](https://github.com/documentdb/documentdb/releases/tag/v0.117-0). +The examples below use the PostgreSQL 17 image from release **0.117.0**. Other PostgreSQL major versions and image tags are listed in the [0.117 release](https://github.com/documentdb/documentdb/releases/tag/v0.117-0). ## Prerequisites diff --git a/getting-started/nodejs-setup.md b/getting-started/nodejs-setup.md index f3f6b6f..2e7bd14 100644 --- a/getting-started/nodejs-setup.md +++ b/getting-started/nodejs-setup.md @@ -133,7 +133,7 @@ main().catch((error) => { ## Beyond CRUD -Aggregation pipelines, vector search, geospatial queries and change streams use the +Aggregation pipelines, vector search, geospatial queries, and change streams use the same syntax as the MongoDB shell. See the [Mongo Shell Quick Start](https://documentdb.io/docs/getting-started/mongo-shell-quickstart/) for worked examples, and the [API reference](https://documentdb.io/docs/reference/) diff --git a/getting-started/prebuilt-packages.md b/getting-started/prebuilt-packages.md index 5986ffe..884209b 100644 --- a/getting-started/prebuilt-packages.md +++ b/getting-started/prebuilt-packages.md @@ -5,7 +5,7 @@ description: Install the complete DocumentDB stack with a setup wizard, or choos # Pre-built Packages -Install a complete MongoDB-compatible service, or add only the components you need to PostgreSQL you manage. Since v0.116, DocumentDB's packages include a setup wizard, administrator tools, and systemd integration. +Install a complete MongoDB-compatible service, or add only the components you need to a PostgreSQL instance you manage. Since v0.116, DocumentDB's packages include a setup wizard, administrator tools, and systemd integration. Get first-party packages from [documentdb.io](https://documentdb.io/packages), extension packages from [PGDG](#pgdg-extension-packages), or [build packages for another target](#community-builds) with the provided scripts. @@ -14,7 +14,7 @@ Get first-party packages from [documentdb.io](https://documentdb.io/packages), e | You want | Installation | | --- | --- | | A working DocumentDB instance with minimal setup | **[Stand-alone stack](#set-up-and-connect), recommended:** install `documentdb` and run the wizard. | -| MongoDB-compatible access to PostgreSQL you manage | [Extension + gateway](#add-a-gateway): configure the components separately and retain your PostgreSQL service lifecycle. | +| MongoDB-compatible access to a PostgreSQL instance you manage | [Extension + gateway](#add-a-gateway): configure the components separately and retain your PostgreSQL service lifecycle. | | DocumentDB through SQL, without a gateway | [Extension only](#extension-only-installation): install the extension and optional administrator tools. | ## First-party packages @@ -86,7 +86,7 @@ Inspect state with `sudo documentdb-setup --pg-version 18 --status`. On systemd, ## What each release publishes -`N` is the PostgreSQL major. The package manager installs the dependencies of your selected package. +`N` is the PostgreSQL major version. The package manager installs the dependencies of your selected package. | Package | Purpose | | --- | --- | @@ -116,7 +116,7 @@ sudo -u postgres /usr/bin/psql --cluster 18/main -d postgres -v ON_ERROR_STOP=1 -c "CREATE EXTENSION IF NOT EXISTS documentdb_extended_rum CASCADE;" ``` -In 0.117, both extension statements are required after the restart; `CASCADE` does not create `documentdb_extended_rum`. Adjust the major and cluster name for your instance. For other layouts, follow the restart and connection commands printed by `documentdb-tune`. +In v0.117, both extension statements are required after the restart; `CASCADE` does not create `documentdb_extended_rum`. Adjust the major and cluster name for your instance. For other layouts, follow the restart and connection commands printed by `documentdb-tune`. For a **new** Debian/Ubuntu cluster, `sudo documentdb-createcluster 18 docdb --start` combines cluster creation, tuning, startup, and extension creation. Choose a cluster name that does not already exist. @@ -140,7 +140,7 @@ DocumentDB is also included in the **PostgreSQL Global Development Group (PGDG) For example, as of **2026-09-10**, PGDG publishes DocumentDB **0.116** for Debian 13 (`trixie-pgdg`), PostgreSQL **15-18**, on **amd64 and arm64**. Versions and targets differ from first-party releases; consult the [PGDG package pool](https://apt.postgresql.org/pub/repos/apt/pool/main/d/documentdb/). -For a new Debian 13 installation, follow the [PGDG repository setup instructions](https://www.postgresql.org/download/linux/debian/#apt), then inspect the candidate for your chosen PostgreSQL major: +For a new Debian 13 installation, follow the [PGDG repository setup instructions](https://www.postgresql.org/download/linux/debian/#apt), then inspect the candidate for your chosen PostgreSQL major version: ```bash sudo apt update @@ -157,7 +157,7 @@ Configure PostgreSQL and create the extensions for that packaged version separat ## Community builds -Can't find a package for your target? The supplied scripts build DEB or RPM packages with Docker; select the distribution and PostgreSQL major rather than writing packaging files yourself. +No package for your target? The supplied scripts build DEB or RPM packages with Docker; select the distribution and PostgreSQL major version rather than writing packaging files yourself. Use a Linux build environment with Git, Docker, Bash 4+, and GNU utilities, on the target architecture. For example, build the extension for Debian 12 and PostgreSQL 18: @@ -188,7 +188,7 @@ Use release assets when you need an exact first-party version rather than a repo gh release download v0.117-0 -R documentdb/documentdb -D pkgs && cd pkgs && sha256sum -c SHA256SUMS ``` -This downloads both formats, architectures, and PostgreSQL majors. Install only the matching subset below, not every downloaded file. +This downloads all formats, architectures, and PostgreSQL major versions. Install only the matching subset below, not every downloaded file. ## Install from downloaded assets @@ -252,4 +252,4 @@ sudo dnf clean all ## Container image -For macOS, Windows, or a container-based installation, follow [DocumentDB Local](../documentdb-local/index.md). Release 0.117 provides Linux amd64/arm64 images for PostgreSQL 15-18; use a versioned tag rather than `latest` when you need a reproducible version. +For macOS, Windows, or a container-based installation, follow [DocumentDB Local](../documentdb-local/index.md). Release v0.117 provides Linux amd64/arm64 images for PostgreSQL 15-18; use a versioned tag rather than `latest` when you need a reproducible version. diff --git a/getting-started/vscode-quickstart.md b/getting-started/vscode-quickstart.md index 7a13e21..4db3157 100644 --- a/getting-started/vscode-quickstart.md +++ b/getting-started/vscode-quickstart.md @@ -48,7 +48,7 @@ This is the fastest way to get a database running. The wizard handles the contai 5. Select **Open Connection** to reveal the saved connection in the Connections view, then expand it to browse databases and collections. -If you keep the sample data option, a `sampledb` database is created with `users`, `products`, `orders`, and `analytics` collections, so you have something to query straight away. +If you keep the sample data option, a `sampledb` database is created with `users`, `products`, `orders`, and `analytics` collections, so you have something to query immediately. ### Managing the Instance diff --git a/postgres-api/configuration.md b/postgres-api/configuration.md index b9efe85..16e7666 100644 --- a/postgres-api/configuration.md +++ b/postgres-api/configuration.md @@ -23,7 +23,7 @@ Collections with a `validator` are enforced on `insert`, `update`, `findAndModif | GUC | Default | Description | | --- | --- | --- | -| `documentdb.rum_library_load_option` | `require_documentdb_extended_rum` (since v0.117-0) | Requires the DocumentDB extended RUM library on every supported PostgreSQL major, not only PG18. Set this in `postgresql.conf` and restart PostgreSQL for a change to take effect. | +| `documentdb.rum_library_load_option` | `require_documentdb_extended_rum` (since v0.117-0) | Requires the DocumentDB extended RUM library on every supported PostgreSQL major version, not only PG18. Set this in `postgresql.conf` and restart PostgreSQL for a change to take effect. | The package setup wizard and container startup handle the required extension setup. For a manually configured PostgreSQL instance, create both `documentdb` and `documentdb_extended_rum`; `CREATE EXTENSION documentdb CASCADE` does not create `documentdb_extended_rum` automatically. Follow the [package setup guidance](https://documentdb.io/docs/getting-started/packages/) before creating indexes. From 08f994fc82f45f564648a5d0eea092010047f432 Mon Sep 17 00:00:00 2001 From: Guanzhou Song Date: Thu, 10 Sep 2026 12:28:10 -0400 Subject: [PATCH 4/4] Correct the VS Code quick start's sample data for 0.117 The page described a `sampledb` database with `users`, `products`, `orders` and `analytics` collections. That is the v0.116-0 dataset: documentdb-local/sample-data/ held 01-users.js, 02-products.js, 03-orders.js and 04-analytics.js, each seeding `sampledb`. v0.117-0 replaces all four with 01-store-data.js plus two gzipped Extended JSON exports, seeding a `StoreData` database with 41,505 `stores` documents and 2 `ratings` documents. The extension ships no dataset of its own -- QuickStartService runs the image's own /home/documentdb/gateway/scripts/init_documentdb_data.sh against its /home/documentdb/gateway/sample-data directory -- and the wizard defaults to the `latest` tag, so a reader following this page today gets StoreData and none of the four collections named here. Describe what the image actually seeds, point at the sample-data section of the DocumentDB Local page for the detail, and keep the `sampledb` name for anyone deliberately pinning a pre-0.117 tag. Verified against v0.116-0 and v0.117-0 in documentdb/documentdb, and against microsoft/vscode-documentdb at 013e429f. --- getting-started/vscode-quickstart.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/getting-started/vscode-quickstart.md b/getting-started/vscode-quickstart.md index 4db3157..454cde9 100644 --- a/getting-started/vscode-quickstart.md +++ b/getting-started/vscode-quickstart.md @@ -48,7 +48,7 @@ This is the fastest way to get a database running. The wizard handles the contai 5. Select **Open Connection** to reveal the saved connection in the Connections view, then expand it to browse databases and collections. -If you keep the sample data option, a `sampledb` database is created with `users`, `products`, `orders`, and `analytics` collections, so you have something to query immediately. +If you keep the sample data option, the extension loads the image's own dataset, so you have something to query immediately. On the `latest` image, that is [StoreData](https://documentdb.io/docs/documentdb-local/#built-in-sample-data): a `StoreData` database holding 41,505 `stores` documents and 2 `ratings` documents. Images before 0.117 seed a smaller `sampledb` database instead, so pin an older tag in the advanced options if you want that one. ### Managing the Instance