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/prebuilt-packages.md b/getting-started/prebuilt-packages.md index 0122416..1d2e6e5 100644 --- a/getting-started/prebuilt-packages.md +++ b/getting-started/prebuilt-packages.md @@ -1,75 +1,24 @@ --- 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 -The packages depend on each other, so **installing the meta package on its own fails**: +Enable the PostgreSQL upstream (PGDG) repository first; RHEL-compatible hosts also need EPEL and CRB — see [Package Installation](https://documentdb.io/packages). -```text -documentdb : Depends: documentdb-18 (>= 0.116.0) but it is not installable -``` - -Pass the whole set for your platform to one command. +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 are arch-specific — the other four are `_all.deb`. + ```bash sudo apt install ./ubuntu24.04-documentdb_0.116.0_all.deb \ ./ubuntu24.04-documentdb-18_0.116.0_all.deb \ @@ -81,6 +30,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`. 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 \ ./documentdb-18-0.116.0-1.noarch.rpm \ @@ -92,7 +43,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 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 + +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). + +> 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 @@ -105,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: -## Docker Images +| 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. | -Use the official `documentdb-local` image from GHCR: +First-party CI builds and tests Ubuntu 24.04 (DEB) and RHEL-compatible 9 (RPM), on PostgreSQL 17 and 18, for both architectures: + +| 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` | + +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` 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