Skip to content

PACKAGE-INSTALL.md

Latest commit

 

History

History
528 lines (401 loc) · 24.6 KB

PACKAGE-INSTALL.md

File metadata and controls

528 lines (401 loc) · 24.6 KB
Raw

DocumentDB Package Installation

Repository-backed installation commands for DocumentDB.

This repository serves v1.0-0.

Clean-host installer

On a clean Ubuntu 24.04 or EL9 host, download and run the installer:

curl -fsSLo documentdb-install.sh https://documentdb.io/install.sh &&
sudo sh documentdb-install.sh

This installs v1.0-0 from this repository on PostgreSQL 18; add --pg-major 17 for 17. On a host where DocumentDB is already set up, it only reports that instance's status and doesn't upgrade it; to move an existing install to 1.0, see Upgrading an existing install.

The site serves the install.sh attached to the release named in scripts/publish-installer.mjs, and the build fails if its SHA256 changes.

What is published

Starting with v0.116-0, DocumentDB ships a multi-package layout with a setup wizard and systemd integration, instead of just a bare PostgreSQL extension package. The website mirrors the package assets attached to one official release; it does not combine the current release with stale packages from older releases. This deliberately reduces the hosted package matrix compared with earlier releases so every advertised combination corresponds to the current, first-party-built release.

Distribution Repository component Packages available
Ubuntu 24.04 ubuntu24 Full stack: documentdb meta, documentdb-N, documentdb-common, documentdb-gateway, documentdb-postgresql-tools, plus the postgresql-N-documentdb extension
Rocky Linux / AlmaLinux / CentOS Stream 9 rpm/rhel9 Full stack, same package set
Registered Red Hat Enterprise Linux 9 rpm/rhel9 Full stack, same package set; uses subscription-manager for CodeReady Builder
  • Both amd64/x86_64 and arm64/aarch64 variants are published.
  • The full stack is published for PostgreSQL 17 and 18.
  • Other accepted build-script combinations (PostgreSQL 15/16; Debian 11/12/13; Ubuntu 22.04; RHEL-compatible 8) are build-on-demand targets in the source repository. They are not part of the current official release and are not served by documentdb.io.

Targets retired from the hosted repository

Starting with v0.116, documentdb.io no longer publishes packages for Ubuntu 22.04, Debian 11/12/13, RHEL-compatible 8, or PostgreSQL 16. This includes the older PG16 extension packages previously present in the ubuntu24 and rpm/rhel9 repositories.

Existing installations keep running, but receive no package updates and cannot reinstall those packages from documentdb.io. Empty signed metadata remains at the retired APT components and RPM 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:

# 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

To remain on an older target, use the matching GitHub release assets or build from that release tag. Those paths are not part of the current hosted support matrix.

Supported PostgreSQL Versions

  • Ubuntu 24.04: PostgreSQL 17 and 18
  • EL9 (Rocky Linux, AlmaLinux, CentOS Stream, and registered RHEL): PostgreSQL 17 and 18

Quickstart — Ubuntu 24.04 and EL9

This is the recommended path. It installs the whole stack and brings up a working wire-protocol endpoint.

These commands assume a regular Linux host where you use sudo. In a clean container that already runs as root, omit sudo, and on Debian/Ubuntu also export DEBIAN_FRONTEND=noninteractive first, or tzdata will hang the install with an invisible prompt.

Ubuntu 24.04 (Noble)

sudo apt update && \
sudo apt install -y curl ca-certificates gnupg && \
curl -fsSL https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo gpg --dearmor --yes -o /usr/share/keyrings/postgresql.gpg && \
echo "deb [signed-by=/usr/share/keyrings/postgresql.gpg] https://apt.postgresql.org/pub/repos/apt noble-pgdg main" | sudo tee /etc/apt/sources.list.d/pgdg.list >/dev/null && \
curl -fsSL https://documentdb.io/documentdb-archive-keyring.gpg | sudo gpg --dearmor --yes -o /usr/share/keyrings/documentdb-archive-keyring.gpg && \
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/documentdb-archive-keyring.gpg] https://documentdb.io/deb stable ubuntu24" | sudo tee /etc/apt/sources.list.d/documentdb.list >/dev/null && \
sudo apt update && \
sudo apt install -y documentdb

Rocky Linux, AlmaLinux, or CentOS Stream 9

crb is disabled by default and is required: PostGIS pulls in gdal*-libs, which needs libqhull_r.so.7, and that library ships only in CRB. Without it dnf install fails with a wall of GDAL candidate lines that never name the missing repository.

if (. /etc/os-release && [ "$ID" = centos ]) && [ -f /etc/yum.repos.d/pgdg-redhat-all.repo ]; then sudo sed -i 's/rhel-\$releasever_major\.\$releasever_minor-/rhel-$releasever_major-/g' /etc/yum.repos.d/pgdg-redhat-all.repo; fi && \
sudo dnf install -y dnf-plugins-core && \
sudo dnf config-manager --set-enabled crb && \
sudo dnf install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm && \
sudo dnf install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-$(uname -m)/pgdg-redhat-repo-latest.noarch.rpm && \
if (. /etc/os-release && [ "$ID" = centos ]) && [ -f /etc/yum.repos.d/pgdg-redhat-all.repo ]; then sudo sed -i 's/rhel-\$releasever_major\.\$releasever_minor-/rhel-$releasever_major-/g' /etc/yum.repos.d/pgdg-redhat-all.repo; fi && \
sudo dnf -qy module disable postgresql && \
sudo rpm --import https://documentdb.io/documentdb-archive-keyring.gpg && \
printf '%s\n' \
  '[documentdb]' \
  'name=DocumentDB Repository' \
  'baseurl=https://documentdb.io/rpm/rhel9' \
  'enabled=1' \
  'gpgcheck=1' \
  'gpgkey=https://documentdb.io/documentdb-archive-keyring.gpg' | sudo tee /etc/yum.repos.d/documentdb.repo >/dev/null && \
sudo dnf install -y documentdb

Registered Red Hat Enterprise Linux 9

This requires an active Red Hat subscription. RHEL exposes CodeReady Builder through subscription-manager; it does not provide the crb repository ID used above.

sudo subscription-manager repos --enable codeready-builder-for-rhel-9-$(uname -m)-rpms && \
sudo dnf install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm && \
sudo dnf install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-$(uname -m)/pgdg-redhat-repo-latest.noarch.rpm && \
sudo dnf -qy module disable postgresql && \
sudo rpm --import https://documentdb.io/documentdb-archive-keyring.gpg && \
printf '%s\n' \
  '[documentdb]' \
  'name=DocumentDB Repository' \
  'baseurl=https://documentdb.io/rpm/rhel9' \
  'enabled=1' \
  'gpgcheck=1' \
  'gpgkey=https://documentdb.io/documentdb-archive-keyring.gpg' | sudo tee /etc/yum.repos.d/documentdb.repo >/dev/null && \
sudo dnf install -y documentdb

Then set up and connect

documentdb-setup prompts for the admin password interactively. For servers, CI or any non-TTY context, pass it in instead with --admin-password-file <file> or --admin-password-stdin, together with --yes; without a password source the command exits.

# Runs initdb / CREATE EXTENSION / admin bootstrap, starts the gateway, and enables
# documentdb-local@18.target so the stack survives reboot.
sudo documentdb-setup --pg-version 18 --use-new-postgres-instance --admin-user admin

# Unattended equivalent:
#   printf '%s' "$ADMIN_PW" | sudo documentdb-setup --pg-version 18 \
#     --use-new-postgres-instance --admin-user admin --admin-password-stdin --yes

The explicit major and fresh-instance flags prevent another installed PostgreSQL major or an existing system cluster from being selected accidentally. To adopt an existing PostgreSQL instance instead, use Adopt an existing PostgreSQL instance.

Sample data is opt-in. Add --load-sample-data to the setup command to seed the StoreData database with 41,505 documents in stores and 2 documents in ratings. This requires mongosh; the command above leaves the new instance empty.

mongosh is not shipped by these packages. Install it from the official instructions, then:

mongosh 'mongodb://admin:<password>@127.0.0.1:10260/mydb?tls=true&tlsAllowInvalidCertificates=true' \
        --eval 'db.runCommand({ping: 1})'

If the password contains @, :, / or other reserved characters it must be percent-encoded in the URI (@ becomes %40). To avoid encoding entirely, pass the credentials as flags:

mongosh localhost:10260 -u admin -p --authenticationMechanism SCRAM-SHA-256 \
        --tls --tlsAllowInvalidCertificates --eval 'db.runCommand({ping: 1})'

A first database and collection are created on first write:

db.orders.insertOne({ item: "widget", qty: 5 })
db.orders.find()

Other useful documentdb-setup flags: --status, --print-config, --no-enable.

Before you expose this to a network

The gateway listens on all interfaces (0.0.0.0:10260 and [::]:10260) by default, even though the connect string above says 127.0.0.1. On a cloud VM with an open security group, the commands above stand up an internet-reachable endpoint protected only by the admin password. The PostgreSQL instance behind it is not exposed — it stays on 127.0.0.1.

Before using this anywhere but a private machine:

  • Restrict the listener to loopback by setting DOCUMENTDB_LISTEN_ADDR=127.0.0.1:10260 in /etc/documentdb/local/<major>/gateway.env, then restarting the service. (Only loopback hosts and the bare :port form are accepted; an arbitrary IP is rejected.) Otherwise firewall port 10260 yourself.

  • Replace the auto-generated self-signed certificate. tlsAllowInvalidCertificates=true in the example disables certificate validation, so it gives you encryption without authenticating the server. Set all three values in /etc/documentdb/local/<major>/gateway.env:

    DOCUMENTDB_TLS_AUTO_GENERATE=false
DOCUMENTDB_TLS_CERT_FILE=/etc/documentdb/tls/server.crt
DOCUMENTDB_TLS_KEY_FILE=/etc/documentdb/tls/server.key

    The gateway runs as documentdb-gateway. Every parent directory must be traversable by that account; keep the private key restricted but readable, for example root:documentdb-gateway with mode 0640. Restart the gateway service and verify it is active before removing tlsAllowInvalidCertificates=true from clients.

  • Use a strong admin password, and create per-application users rather than sharing admin.

Verify and operate

sudo documentdb-setup --status      # gateway listener, service states, resolved paths
documentdb-gateway --version        # DocumentDB version (1.0.0)
dpkg -l | grep documentdb           # or: rpm -qa | grep documentdb

Do not use db.version() / buildInfo in mongosh to check the DocumentDB version — those report the emulated MongoDB wire version (e.g. 7.0.0), not DocumentDB's.

Thing Where
Gateway port 10260
PostgreSQL port 9700 + <major> (9718 for PG 18), loopback only
Gateway log /var/lib/documentdb-gateway/gateway.log
PostgreSQL log /var/lib/documentdb-local/<major>/data/pglog.log
Setup state / gateway env /etc/documentdb/local/<major>/setup.conf, .../gateway.env

Day 2 (units are templated per PostgreSQL major — substitute 18 as needed):

sudo systemctl status  documentdb-local@18.target
sudo systemctl restart documentdb-local@18.target
sudo systemctl stop    documentdb-local@18.target

On hosts without systemd (containers, some dev images) the wizard starts the gateway directly instead; the systemctl commands above fail with "System has not been booted with systemd". Use documentdb-setup --status to inspect it and re-run documentdb-setup to restart it.

Adopt an existing PostgreSQL instance

Use brownfield mode only when PostgreSQL already exists and its service and data remain operator-owned. Back up the instance first. The wizard does not create, delete, start, or stop that PostgreSQL instance, but it does add managed configuration blocks, create the gateway role, install the DocumentDB extensions, and register the gateway.

Identify the instance as <major>/<name>. On Ubuntu, run pg_lsclusters; a typical instance is 18/main. The standard PGDG layout on EL9 has one instance per major and also uses 18/main; add --pg-port when it listens on a non-default port.

sudo documentdb-setup --target-postgres-instance 18/main --admin-user admin

If shared_preload_libraries changed, the first run prints a restart handoff instead of finishing setup. Restart the operator-managed PostgreSQL service, then re-run the exact setup command it prints. Typical service names are postgresql@18-main.service on Ubuntu and postgresql-18.service on EL9. The wizard intentionally does not restart an adopted PostgreSQL instance for you.

The wizard's default default_toast_compression setting applies to newly written values in every database on an adopted instance. If other workloads must retain PostgreSQL's own default, prefix both setup runs with sudo DOCUMENTDB_TOAST_COMPRESSION=default.

Running SQL against a package-managed private instance. A greenfield PostgreSQL instance is owned by the documentdb-local system user and listens on a socket, so a bare psql will not find it:

sudo -u documentdb-local psql -h /run/documentdb-local/18/postgresql -p 9718 -d postgres

Use that connection for the ALTER EXTENSION statements under Upgrading, and to read versions with SELECT extname, extversion FROM pg_extension WHERE extname LIKE 'documentdb%';. For an adopted instance, use the operator's existing PostgreSQL connection instead.

Greenfield: destroy the package-managed instance:

# Reset reads setup.conf before removing it, stops the services, and destroys
# the package-managed data directory. Do not run --restore first.
sudo documentdb-local-reset --pg-version 18 --confirm-destroy

# Name the package you installed AND the extension: autoremove does not reap
# postgresql-18-documentdb, and `remove` would leave its config behind.
sudo apt purge --autoremove documentdb-18 postgresql-18-documentdb
sudo dnf remove documentdb-18 postgresql18-documentdb && sudo dnf autoremove

Brownfield: detach without deleting the existing PostgreSQL instance:

Before restoring, run sudo documentdb-setup --status and note the gateway port for the major you are removing.

On a systemd host, a scoped restore stops and disables that major's gateway:

sudo documentdb-setup --restore --pg-version 18

On a host without systemd, the current setup tooling cannot safely attribute a nohup gateway process to one PostgreSQL major. If only one DocumentDB major is configured, use an unscoped restore so the orphan gateway sweep runs:

sudo documentdb-setup --restore --yes

If more than one DocumentDB major is configured without systemd, schedule a maintenance window and use the same unscoped restore. It detaches every configured major and stops the nohup gateways; re-run setup for the majors you are keeping afterward. A scoped restore alone is not sufficient on a no-systemd host.

Restart the adopted PostgreSQL service after restore to apply removal of the managed settings. On an unscoped multi-major restore, restart each operator-managed PostgreSQL service involved.

Verify that the target gateway port is no longer listening before removing packages. Substitute the port you noted above; the command should produce no output:

ss -lnt | grep ':10260'

Then remove the selected major:

sudo apt purge --autoremove documentdb-18 postgresql-18-documentdb
sudo dnf remove documentdb-18 postgresql18-documentdb && sudo dnf autoremove

Never run documentdb-local-reset for a brownfield installation. Never run restore before a greenfield reset: restore deletes the state that identifies custom data directories and protects adopted clusters.

If you installed the documentdb meta package rather than documentdb-18, name that instead.

What the packages are

Package Role
documentdb (meta) + documentdb-N Full stand-alone install; pins PostgreSQL major N + its extension and owns the systemd lifecycle. The meta package pins PG 18.
postgresql-N-documentdb The extension for PostgreSQL major N (files only).
documentdb-gateway Wire-protocol runtime (binary + systemd unit).
documentdb-postgresql-tools Admin helpers: documentdb-tune, documentdb-createcluster, documentdb-register-gateway, documentdb-gateway-admin.
documentdb-common Shared, PG-agnostic payload: documentdb-setup, systemd template units, sysusers.d/tmpfiles.d drop-ins, helper scripts, sample data.

To install the extension by itself on these distributions, use postgresql-18-documentdb (APT) or postgresql18-documentdb (RPM) instead of the documentdb meta package.

Installing a different PostgreSQL major

The current release publishes PostgreSQL 17 and 18. Install documentdb-17 or documentdb-18; the documentdb meta package selects PostgreSQL 18.

Upgrading an existing install

Package installs from v0.116 or v0.117 upgrade in place to 1.0. Move the entire stack together; upgrading only postgresql-N-documentdb does not update the gateway, tools, common payload, or documentdb-N. These steps use systemd; upgrading a host without it isn't covered here. On a package-managed private PostgreSQL 18 instance:

Warning: A host that ran a 1.0 release candidate (RC1 or RC2) has no upgrade path. Use a clean host or a new, empty PostgreSQL instance. Removing packages alone does not create a fresh database: package removal preserves PostgreSQL data and in-database content, and a later setup run reuses an initialized data directory.

# Debian / Ubuntu
sudo systemctl stop documentdb-gateway-local@18.service &&
sudo apt update &&
sudo apt install --only-upgrade documentdb-18 postgresql-18-documentdb \
  documentdb-common documentdb-gateway documentdb-postgresql-tools

# EL9: use this instead of the apt commands above
sudo systemctl stop documentdb-gateway-local@18.service &&
sudo dnf upgrade documentdb-18 postgresql18-documentdb \
  documentdb-common documentdb-gateway documentdb-postgresql-tools

Upgrading the packages does not update the database catalog. The simplest way is to restart PostgreSQL so it loads the new libraries, then re-run setup with the options you installed with. Setup updates the extensions and then starts the gateway:

sudo systemctl restart documentdb-postgresql@18.service &&
sudo documentdb-setup --pg-version 18 --use-new-postgres-instance --admin-user admin

Setup adds any missing shared_preload_libraries entries and updates the extensions, but only in the postgres database. If your gateway uses another database, take the manual route below. It also asks for the admin password and sets it on the existing admin user: enter the current password to keep it.

To update by hand, or for every other database that has DocumentDB installed, first check that the extended RUM library is preloaded:

sudo -u documentdb-local psql -h /run/documentdb-local/18/postgresql -p 9718 -d postgres -X -Atc "SHOW shared_preload_libraries;"

If pg_documentdb_extended_rum is missing (possible on a 0.116 install), add it before updating; the update below would succeed without it, and index builds would fail later. If the gateway uses postgres, re-run setup as above. If it uses another database, add the library to shared_preload_libraries in the instance's postgresql.conf yourself: setup would point the gateway back at postgres. Then restart PostgreSQL, update the extensions in one transaction, and start the gateway only if that worked:

sudo systemctl restart documentdb-postgresql@18.service &&
sudo -u documentdb-local psql -h /run/documentdb-local/18/postgresql -p 9718 -d postgres \
  -X -1 -v ON_ERROR_STOP=1 \
  -c 'ALTER EXTENSION documentdb_core UPDATE;' \
  -c 'ALTER EXTENSION documentdb UPDATE;' \
  -c 'CREATE EXTENSION IF NOT EXISTS documentdb_extended_rum CASCADE;' \
  -c 'ALTER EXTENSION documentdb_extended_rum UPDATE;' &&
sudo systemctl start documentdb-gateway-local@18.service

-1 runs the statements as one transaction: if any fails, every extension stays at its old version and the gateway stays stopped. -X skips ~/.psqlrc, which could otherwise turn ON_ERROR_STOP off. If DocumentDB is installed in other databases too, run the psql part for each of them, with that -d, before the last line, so the gateway starts only after every database is updated. PostgreSQL applies intermediate upgrade scripts automatically. Take a backup first.

On a host with both PostgreSQL 17 and 18, documentdb-common, documentdb-gateway and documentdb-postgresql-tools serve both majors, so upgrading them affects both: stop both gateways (documentdb-gateway-local@17.service and @18.service) before upgrading, then update each major.

For an adopted PostgreSQL instance, setup never restarts PostgreSQL. Stop the gateway (documentdb-gateway-local@18.service) before upgrading, restart the operator-managed PostgreSQL service yourself, then re-run documentdb-setup --pg-version 18 --target-postgres-instance 18/main --admin-user admin (with your cluster name); it updates the extensions and then starts the gateway. If setup has to change shared_preload_libraries, it exits without updating the extensions: restart PostgreSQL and run it once more. By hand, use that instance's own psql connection.

Confirm afterwards with:

SELECT extname, extversion FROM pg_extension WHERE extname LIKE 'documentdb%';

Version pinning

Run the repository setup for your distro first, then:

APT

apt-cache madison documentdb-18
sudo apt install documentdb-18=<VERSION>

RPM

dnf --showduplicates list documentdb-18
sudo dnf install documentdb-18-<VERSION>

Build-on-demand targets

Other distributions and PostgreSQL majors accepted by the upstream packaging scripts can be built from the matching source tag. They are not official release assets and are therefore not published in the documentdb.io package repositories. Community builds are welcome.

For example, after checking out the matching release tag, build an extension package with:

./packaging/build_packages.sh --os deb12 --pg 16 --version 1.0.0

v1.0-0 and v1.0-RC2 are on the same commit, so pass --version; without it the scripts can build RC-versioned packages. That command builds only postgresql-N-documentdb. A custom full-stack package set uses three entry points:

  • packaging/build_packages.sh — PostgreSQL extension
  • packaging/gateway/build_gateway_packages.sh — wire-protocol gateway
  • packaging/build_extra_packages.sh — tools, common payload, documentdb-N, and meta package

The v1.0 packaging guide documents their required arguments, version formats, prerequisites, and accepted targets. PostgreSQL 15 remains extension-only for package-managed installs because the setup tools require PostgreSQL 16 or newer.

Direct downloads

GitHub Releases contains the .deb and .rpm assets for every published combination. The package repositories on documentdb.io are generated from exactly the same asset list; they do not retain packages from older releases.

Examples:

ubuntu24.04-documentdb_1.0.0_all.deb
ubuntu24.04-postgresql-18-documentdb_1.0-0_amd64.deb
rhel9-postgresql18-documentdb-1.0.0-1.el9.x86_64.rpm

For a full stack, pass the five packages for the selected PostgreSQL major to one command: documentdb-N, the matching postgresql-N-documentdb / postgresqlN-documentdb extension, documentdb-common, documentdb-gateway, and documentdb-postgresql-tools. For PostgreSQL 18 only, the optional documentdb meta package may be included; it selects documentdb-18. Local files resolve dependencies only against enabled repositories, so a package whose dependencies are not included still fails. Alternatively, use the repository-backed install above.

Notes

  • The current release publishes the ubuntu24 APT component and the rpm/rhel9 repository.
  • The RPM flow depends on EPEL plus PostgreSQL's upstream RPM repository because DocumentDB depends on PostgreSQL, pg_cron, pgvector, PostGIS, and rum for PostgreSQL 17.
  • On Debian/Ubuntu, the distro-packaged cargo can be older than the current gateway workspace lockfile. rustup avoids that mismatch.