diff --git a/PACKAGE-INSTALL.md b/PACKAGE-INSTALL.md index a7c0f8c..bacec44 100644 --- a/PACKAGE-INSTALL.md +++ b/PACKAGE-INSTALL.md @@ -14,7 +14,8 @@ 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 | -| RHEL-compatible 9 | `rpm/rhel9` | **Full stack**, same package set | +| 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**. @@ -51,9 +52,9 @@ release tag. Those paths are not part of the current hosted support matrix. ## Supported PostgreSQL Versions - Ubuntu 24.04: PostgreSQL 17 and 18 -- RHEL-compatible 9: PostgreSQL 17 and 18 +- EL9 (Rocky Linux, AlmaLinux, CentOS Stream, and registered RHEL): PostgreSQL 17 and 18 -## Quickstart — Ubuntu 24.04 and RHEL 9 +## Quickstart — Ubuntu 24.04 and EL9 This is the recommended path. It installs the whole stack and brings up a working wire-protocol endpoint. @@ -76,19 +77,39 @@ sudo apt update && \ sudo apt install -y documentdb ``` -### RHEL-compatible 9 +### 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. ```bash +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 && \ +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. + +```bash +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 dnf install -y dnf-plugins-core && \ -(sudo dnf config-manager --set-enabled crb || \ - sudo dnf config-manager --set-enabled codeready-builder-for-rhel-9-$(uname -m)-rpms) && \ sudo rpm --import https://documentdb.io/documentdb-archive-keyring.gpg && \ printf '%s\n' \ '[documentdb]' \ @@ -104,18 +125,22 @@ sudo dnf install -y documentdb `documentdb-setup` **prompts for the admin password** interactively. For servers, CI or any non-TTY context, pass it in instead with `--admin-password-file ` or -`--admin-password-stdin`, together with `--yes` — the bare command below will hang without a -terminal. +`--admin-password-stdin`, together with `--yes`; without a password source the command exits. ```bash # Runs initdb / CREATE EXTENSION / admin bootstrap, starts the gateway, and enables -# documentdb-local@.target so the stack survives reboot. -sudo documentdb-setup --admin-user admin +# 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 --admin-user admin --admin-password-stdin --yes +# 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](#adopt-an-existing-postgresql-instance). + `mongosh` is not shipped by these packages. Install it from the [official instructions](https://www.mongodb.com/docs/mongodb-shell/install/), then: @@ -141,7 +166,7 @@ db.orders.find() Other useful `documentdb-setup` flags: `--status`, `--print-config`, `--no-enable`. -### ⚠️ Before you expose this to a network +### 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, @@ -156,8 +181,19 @@ Before using this anywhere but a private machine: 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. Point `DOCUMENTDB_TLS_CERT_FILE` / `DOCUMENTDB_TLS_KEY_FILE` at a - real certificate and drop that option. + authenticating the server. Set all three values in + `/etc/documentdb/local//gateway.env`: + + ```ini + 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 @@ -191,8 +227,34 @@ On hosts without systemd (containers, some dev images) the wizard starts the gat 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. -**Running SQL against the managed instance.** The private PostgreSQL instance is owned by the -`documentdb-local` system user and listens on a socket, so a bare `psql` will not find 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 `/`. 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. + +```bash +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: ```bash sudo -u documentdb-local psql -h /run/documentdb-local/18/postgresql -p 9718 -d postgres @@ -200,17 +262,14 @@ sudo -u documentdb-local psql -h /run/documentdb-local/18/postgresql -p 9718 -d 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. -**Remove or reset:** +**Greenfield: destroy the package-managed instance:** ```bash -# Stop the stack first — package removal deletes files but does not stop a -# running gateway. On systemd hosts: -sudo systemctl stop documentdb-local@18.target -# Without systemd the wizard started the gateway directly; kill that process. - -sudo documentdb-setup --restore # detach the managed integration -sudo documentdb-local-reset --pg-version 18 --confirm-destroy # DESTROYS the data directory +# 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. @@ -218,6 +277,51 @@ 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: + +```bash +sudo documentdb-setup --restore --pg-version 18 +``` + +On a host without systemd, v0.116 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: + +```bash +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: + +```bash +ss -lnt | grep ':10260' +``` + +Then remove the selected major: + +```bash +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 @@ -240,11 +344,31 @@ The current release publishes PostgreSQL 17 and 18. Install `documentdb-17` or ## Upgrading an existing install -The package repository serves the selected official release for its published matrix. +> **Warning:** v0.116 does not support an in-place upgrade from the extension-only package +> layout in v0.114 or earlier. Use a clean host, or remove the earlier packages and perform the +> current fresh installation. Upgrading only `postgresql-N-documentdb` does not install the +> gateway, tools, common payload, or `documentdb-N`. + +For a later point release that uses the same multi-package layout, move the entire stack +together. On a package-managed private PostgreSQL 18 instance: + +```bash +sudo systemctl stop documentdb-gateway-local@18.service + +# Debian / Ubuntu +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 dnf upgrade documentdb-18 postgresql18-documentdb \ + documentdb-common documentdb-gateway documentdb-postgresql-tools + +# PostgreSQL has the old shared library loaded until it restarts. +sudo systemctl restart documentdb-postgresql@18.service +``` -**A package upgrade only replaces files on disk.** It does not touch the SQL objects already -created in your databases, so after upgrading you must update the extensions in **every -database** that has DocumentDB installed: +Then update the extensions in **every database** that has DocumentDB installed: ```sql ALTER EXTENSION documentdb_core UPDATE; @@ -259,15 +383,14 @@ afterwards with: SELECT extname, extversion FROM pg_extension WHERE extname LIKE 'documentdb%'; ``` -> **Pre-GA:** in-place upgrades are not yet a supported, fully tested path. Take a backup -> first, and prefer a clean install where you can. If you would rather not be offered the -> upgrade at all, pin the current version: -> -> ```bash -> sudo apt-mark hold postgresql-18-documentdb # APT -> sudo dnf install -y python3-dnf-plugin-versionlock && \ -> sudo dnf versionlock add postgresql18-documentdb # DNF -> ``` +Finally restart the gateway: + +```bash +sudo systemctl start documentdb-gateway-local@18.service +``` + +Take a backup first. For an adopted PostgreSQL instance, restart its operator-managed +PostgreSQL service instead of `documentdb-postgresql@18.service`. ## Version pinning diff --git a/app/lib/packageInstall.ts b/app/lib/packageInstall.ts index 016f093..dec7612 100644 --- a/app/lib/packageInstall.ts +++ b/app/lib/packageInstall.ts @@ -1,5 +1,5 @@ export type AptDistro = "ubuntu24"; -export type RpmDistro = "rhel9"; +export type RpmDistro = "rocky9" | "rhel9"; export type AptArch = "amd64" | "arm64" | "auto"; export type RpmArch = "x86_64" | "aarch64" | "auto"; export type AptPgVersion = "17" | "18"; @@ -10,7 +10,8 @@ export const aptTargetLabels: Record = { }; export const rpmTargetLabels: Record = { - rhel9: "RHEL-compatible 9 (tested on Rocky Linux 9)", + rocky9: "Rocky Linux / AlmaLinux / CentOS Stream 9", + rhel9: "Red Hat Enterprise Linux 9 (registered)", }; export const aptTargetPgVersions: Record = { @@ -22,12 +23,18 @@ const aptPgdgSuites: Record = { }; const rpmMajorVersions: Record = { + rocky9: "9", rhel9: "9", }; +const rpmRepositoryPaths: Record = { + rocky9: "rhel9", + rhel9: "rhel9", +}; + // The website mirrors the official release's Tier-1 package matrix exactly. export const aptFullStackDistros: readonly AptDistro[] = ["ubuntu24"]; -export const rpmFullStackDistros: readonly RpmDistro[] = ["rhel9"]; +export const rpmFullStackDistros: readonly RpmDistro[] = ["rocky9", "rhel9"]; const fullStackPgVersions = ["17", "18"]; @@ -84,25 +91,29 @@ export function buildRpmInstallCommand( rpmPgVersion: RpmPgVersion, ): string { const rhelMajorVersion = rpmMajorVersions[rpmTarget]; + const repositoryPath = rpmRepositoryPaths[rpmTarget]; // See buildAptInstallCommand: "auto" resolves on the host so one published // example works on x86_64 and aarch64 alike. const arch = rpmArch === "auto" ? "$(uname -m)" : rpmArch; const installTarget = rpmServesFullStack(rpmTarget, rpmPgVersion) ? `documentdb-${rpmPgVersion}` : `postgresql${rpmPgVersion}-documentdb`; + const distributionPrerequisites = + rpmTarget === "rhel9" + ? `sudo subscription-manager repos --enable codeready-builder-for-rhel-${rhelMajorVersion}-${arch}-rpms && \\ +sudo dnf install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-${rhelMajorVersion}.noarch.rpm` + : `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-${rhelMajorVersion}.noarch.rpm`; - return `sudo dnf install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-${rhelMajorVersion}.noarch.rpm && \\ + return `${distributionPrerequisites} && \\ sudo dnf install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-${rhelMajorVersion}-${arch}/pgdg-redhat-repo-latest.noarch.rpm && \\ sudo dnf -qy module disable postgresql && \\ -sudo dnf install -y dnf-plugins-core && \\ -(sudo dnf config-manager --set-enabled crb || \\ - sudo dnf config-manager --set-enabled powertools || \\ - sudo dnf config-manager --set-enabled codeready-builder-for-rhel-${rhelMajorVersion}-${arch}-rpms) && \\ sudo rpm --import https://documentdb.io/documentdb-archive-keyring.gpg && \\ printf '%s\\n' \\ '[documentdb]' \\ 'name=DocumentDB Repository' \\ - 'baseurl=https://documentdb.io/rpm/${rpmTarget}' \\ + 'baseurl=https://documentdb.io/rpm/${repositoryPath}' \\ 'enabled=1' \\ 'gpgcheck=1' \\ 'gpgkey=https://documentdb.io/documentdb-archive-keyring.gpg' | sudo tee /etc/yum.repos.d/documentdb.repo >/dev/null && \\ @@ -112,6 +123,6 @@ sudo dnf install -y ${installTarget}`; // Shown after a full-stack install: the packages ship a wizard that creates the // PostgreSQL instance, installs the extensions and starts the gateway, so the // install command alone does not leave a reachable endpoint. -export function buildSetupCommand(): string { - return `sudo documentdb-setup --admin-user admin`; +export function buildSetupCommand(pgVersion: AptPgVersion | RpmPgVersion): string { + return `sudo documentdb-setup --pg-version ${pgVersion} --use-new-postgres-instance --admin-user admin`; } diff --git a/app/packages/layout.tsx b/app/packages/layout.tsx index ea0d508..051d8c3 100644 --- a/app/packages/layout.tsx +++ b/app/packages/layout.tsx @@ -4,7 +4,7 @@ import { getMetadata } from "../services/metadataService"; export const metadata = getMetadata({ title: "Download DocumentDB - Docker, APT, and RPM Packages", description: - "Run DocumentDB with Docker or install the full stack from GPG-signed repositories for Ubuntu 24.04 and RHEL-compatible 9. Build other targets from source.", + "Run DocumentDB with Docker or install the full stack from GPG-signed repositories for Ubuntu 24.04 and EL9, including Rocky-family systems and registered RHEL. Build other targets from source.", path: "/packages/", extraKeywords: ["download", "install", "Docker", "APT", "RPM", "Debian", "Ubuntu", "RHEL"], }); diff --git a/app/packages/page.tsx b/app/packages/page.tsx index 295a682..0d40748 100644 --- a/app/packages/page.tsx +++ b/app/packages/page.tsx @@ -88,7 +88,7 @@ export default function PackagesPage() { // Default to the paved road (Ubuntu 24.04 + PostgreSQL 18). The package // finder exposes only combinations built and tested in the mirrored release. const [aptTarget, setAptTarget] = useState("ubuntu24"); - const [rpmTarget, setRpmTarget] = useState("rhel9"); + const [rpmTarget, setRpmTarget] = useState("rocky9"); const [aptArch, setAptArch] = useState("amd64"); const [rpmArch, setRpmArch] = useState("x86_64"); const [aptPgVersion, setAptPgVersion] = useState("18"); @@ -104,10 +104,6 @@ export default function PackagesPage() { const latestReleaseAptVersion = release.aptVersion; const latestReleaseRpmVersion = release.rpmVersion; const packagingGuideUrl = `https://github.com/documentdb/documentdb/blob/${release.tagName}/packaging/README.md`; - // The repository serves the mirrored release, so the pinning examples use the - // same versions rather than a separately maintained pair that fell behind. - const repoAptVersionExample = release.aptVersion; - const repoRpmVersionExample = release.rpmVersion; const currentReleaseExamples = [ `ubuntu24.04-documentdb_${release.metaVersion}_all.deb`, `ubuntu24.04-postgresql-18-documentdb_${latestReleaseAptVersion}_amd64.deb`, @@ -140,11 +136,12 @@ export default function PackagesPage() {

Choose Docker for the fastest local setup, or Linux packages for a persistent - install. On Ubuntu 24.04 and RHEL-compatible 9 the packages install the full - DocumentDB stack — the PostgreSQL extension, the wire-protocol gateway, the - administrator tools and systemd units. Starting with v0.116, the hosted package - matrix is intentionally smaller and mirrors only combinations attached to the - current official release. + install. On Ubuntu 24.04 and EL9 (Rocky Linux, AlmaLinux, CentOS Stream, or + registered Red Hat Enterprise Linux), the packages install the full DocumentDB + stack — the PostgreSQL extension, the wire-protocol gateway, the administrator + tools and systemd units. Starting with v0.116, the hosted package matrix is + intentionally smaller and mirrors only combinations attached to the current + official release.

@@ -185,7 +182,7 @@ export default function PackagesPage() { >

Linux Packages

- Best for: persistent Ubuntu 24.04 or RHEL-compatible 9 VM and server environments. + Best for: persistent Ubuntu 24.04 or EL9 VM and server environments.

@@ -219,11 +216,12 @@ export default function PackagesPage() {

documentdb.io now publishes only the combinations built and tested for the - current release: Ubuntu 24.04 and RHEL-compatible 9, PostgreSQL 17 or 18, on - both supported architectures. Packages from earlier releases are not carried - forward to make unsupported targets appear current. This also withdraws the - older PostgreSQL 16 extension packages previously served for Ubuntu 24.04 and - RHEL-compatible 9. + current release: Ubuntu 24.04 and EL9, PostgreSQL 17 or 18, on both supported + architectures. EL9 covers Rocky Linux, AlmaLinux, CentOS Stream, and registered + Red Hat Enterprise Linux with different prerequisite commands. Packages from + earlier releases are not carried forward to make unsupported targets appear + current. This also withdraws the older PostgreSQL 16 extension packages + previously served for Ubuntu 24.04 and EL9.

Need another distribution or PostgreSQL major? We welcome community builds. @@ -252,7 +250,7 @@ export default function PackagesPage() { className="mt-1 w-full rounded-md border border-neutral-700 bg-neutral-800 px-3 py-2 text-sm text-gray-100" > - + @@ -366,26 +364,39 @@ export default function PackagesPage() { {isFullStack ? ( <>

- Then run the setup wizard. It creates the PostgreSQL instance, installs the - extensions, bootstraps the admin user and starts the gateway — the install - above on its own does not leave a reachable endpoint. It prompts for the - admin password; pass{" "} - --admin-password-stdin --yes for an - unattended install. + Then run the setup wizard. The generated command pins the PostgreSQL major + you selected and creates a new private instance, so another installed major + or an existing system cluster cannot be selected by accident. It installs + the extensions, bootstraps the admin user and starts the gateway — the + package install above on its own does not leave a reachable endpoint. It + prompts for the admin password. For automation, use the complete{" "} + + unattended setup + {" "} + instructions.

- +

The gateway then listens on port{" "} 10260. It binds all interfaces by - default, so firewall the port and supply a real certificate before exposing - it to a network. See the{" "} - - package installation guide - {" "} - for verification, day-2 and upgrade steps. + operations guide + + .

) : null} @@ -474,7 +485,10 @@ export default function PackagesPage() { RPM - RHEL-compatible 9 · rpm/rhel9 + + Rocky/Alma/CentOS Stream 9 or registered RHEL 9 ·{" "} + rpm/rhel9 + x86_64, aarch64 17, 18 @@ -556,17 +570,10 @@ export default function PackagesPage() { selected target actually installs.

- The two package families carry different version strings, so the - right <VERSION> depends on which you - pin. The extension is{" "} - {repoAptVersionExample} (APT) /{" "} - {repoRpmVersionExample} (RPM), while{" "} - documentdb,{" "} - documentdb-<pg> and the gateway are{" "} - {release.metaVersion} (APT) /{" "} - {release.metaRpmVersion} (RPM). Pinning{" "} - documentdb-18={repoAptVersionExample}{" "} - fails — always take the string the list command prints. + APT and RPM use different version syntax, and individual subpackages can carry + different release suffixes. Always copy the exact version returned below for{" "} + {selectedPackageNames}; do not infer it + from the extension or another package.

APT — list then pin

@@ -666,9 +673,12 @@ export default function PackagesPage() {

Docker starts a gateway-backed local endpoint on port 10260. On Ubuntu 24.04 and - RHEL-compatible 9 the packages give you the same thing: install, then run{" "} - sudo documentdb-setup --admin-user admin, - which creates the database and starts the gateway. + EL9 the packages give you the same thing: install, then run{" "} + + {buildSetupCommand(packageFamily === "apt" ? aptPgVersion : rpmPgVersion)} + + {", "}which creates a private database instance for the selected PostgreSQL major and + starts the gateway.

diff --git a/app/services/articleService.ts b/app/services/articleService.ts index d666e9b..788ea33 100644 --- a/app/services/articleService.ts +++ b/app/services/articleService.ts @@ -4,7 +4,11 @@ import { load as loadYaml } from 'js-yaml'; import matter from 'gray-matter'; import { Article } from '../types/Article'; import { Link } from '../types/Link'; -import { buildAptInstallCommand, buildRpmInstallCommand } from '../lib/packageInstall'; +import { + buildAptInstallCommand, + buildRpmInstallCommand, + buildSetupCommand, +} from '../lib/packageInstall'; import { documentdbDiscordUrl } from './externalLinks'; const articlesDirectory = path.join(process.cwd(), 'articles'); @@ -157,11 +161,11 @@ If something does not work as expected: - [Package Finder](/packages) `; -const linuxPackagesGuideContent = `# Linux Packages Quick Start +export const linuxPackagesGuideContent = `# Linux Packages Quick Start Install DocumentDB from the published package repository and get a MongoDB-compatible endpoint on your own host. -The current official release publishes the full stack — extension, gateway, setup wizard and systemd units — for **Ubuntu 24.04 and RHEL-compatible 9, on PostgreSQL 17 or 18**. Starting with v0.116, this is a deliberately smaller prebuilt matrix than earlier releases. The website repository mirrors only the current release assets and does not carry older packages forward to make other targets appear current. +The current official release publishes the full stack — extension, gateway, setup wizard and systemd units — for **Ubuntu 24.04 and EL9, on PostgreSQL 17 or 18**. EL9 includes Rocky Linux, AlmaLinux, CentOS Stream, and registered Red Hat Enterprise Linux; the Package Finder supplies the prerequisite command for each family. Starting with v0.116, this is a deliberately smaller prebuilt matrix than earlier releases. The website repository mirrors only the current release assets and does not carry older packages forward to make other targets appear current. > [!NOTE] > Need another distribution or PostgreSQL major? We welcome community builds. Check out the matching release tag and use the version-parameterized [packaging scripts](https://github.com/documentdb/documentdb/blob/v0.116-0/packaging/README.md). \`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. PostgreSQL 15 is extension-only because the setup tools require PostgreSQL 16 or newer. These builds are on demand and are not official release assets hosted by documentdb.io. @@ -194,13 +198,22 @@ You do not need PostgreSQL already installed — the setup wizard creates and ma ${buildAptInstallCommand('ubuntu24', 'auto', '18')} \`\`\` -### RHEL-compatible 9, PostgreSQL 18 (RPM) +### Rocky Linux, AlmaLinux, or CentOS Stream 9, PostgreSQL 18 (RPM) + +\`\`\`bash +${buildRpmInstallCommand('rocky9', 'auto', '18')} +\`\`\` + +### Registered Red Hat Enterprise Linux 9, PostgreSQL 18 (RPM) + +This command requires an active Red Hat subscription. RHEL exposes CodeReady Builder through +\`subscription-manager\`, not through the \`crb\` repository ID used by Rocky-family systems. \`\`\`bash ${buildRpmInstallCommand('rhel9', 'auto', '18')} \`\`\` -For PostgreSQL 17, install \`documentdb-17\`; there is no \`documentdb-16\`. Keep the \`crb\` line on RHEL — without it \`dnf\` fails on \`libqhull_r.so.7\`. +For PostgreSQL 17, install \`documentdb-17\`; there is no \`documentdb-16\`. Both EL9 flows enable CodeReady Builder, which supplies \`libqhull_r.so.7\` for PostGIS dependencies. Then install \`mongosh\`, which you need to talk to the endpoint: @@ -210,7 +223,7 @@ curl -fsSL https://pgp.mongodb.com/server-8.0.asc | sudo gpg --dearmor -o /usr/s echo "deb [signed-by=/usr/share/keyrings/mongodb.gpg] https://repo.mongodb.org/apt/ubuntu noble/mongodb-org/8.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb.list sudo apt update && sudo apt install -y mongodb-mongosh -# RHEL-compatible 9 +# EL9 printf '[mongodb-org-8.0]\\nname=MongoDB\\nbaseurl=https://repo.mongodb.org/yum/redhat/9/mongodb-org/8.0/$basearch/\\ngpgcheck=1\\nenabled=1\\ngpgkey=https://pgp.mongodb.com/server-8.0.asc\\n' | sudo tee /etc/yum.repos.d/mongodb.repo sudo dnf install -y mongodb-mongosh \`\`\` @@ -223,10 +236,12 @@ sudo dnf install -y mongodb-mongosh Installing the packages puts files on disk; it does not create a database or start the endpoint. The setup wizard does that: \`\`\`bash -sudo documentdb-setup --admin-user admin +${buildSetupCommand('18')} \`\`\` -It creates the PostgreSQL instance, installs the extensions, starts the gateway, and enables it at boot. It **prompts for the admin password**. +It creates a new private PostgreSQL 18 instance, installs the extensions, starts the gateway, and enables it at boot. It **prompts for the admin password**. The explicit major and fresh-instance flags keep another installed PostgreSQL major or an existing system cluster from being selected accidentally. + +For automation, use the complete [unattended setup](/docs/linux-packages#unattended-setup) command. To adopt an existing PostgreSQL instance instead, follow [Adopt an existing PostgreSQL instance](/docs/linux-packages#adopt-an-existing-postgre-sql-instance); brownfield setup intentionally has different lifecycle and restart requirements. Now open a shell against the endpoint: @@ -258,14 +273,14 @@ A database and collection are created on first write: - \`Unable to locate package documentdb-18\` (apt) / \`No match for argument: documentdb-18\` (dnf) — the DocumentDB repository was not added, or the host is not in the current release matrix. Check the [Package Finder](/packages) - \`documentdb-18 : Depends: postgresql-18 but it is not installable\` — PGDG was not added first -- \`nothing provides libqhull_r.so.7\` — the \`crb\` line did not run +- \`nothing provides libqhull_r.so.7\` — CRB or CodeReady Builder was not enabled for the selected EL9 family - \`MongoServerError: Invalid key\` — empty or wrong password; a bare \`-p\` prompts, so a non-interactive shell sends nothing - Anything else — \`sudo documentdb-setup --status\` reports the listener, service states and resolved paths More failure modes, including hosts without systemd: [Operating a package install](/docs/linux-packages#troubleshooting). `; -const linuxPackagesOperationsContent = `# Operating a package install +export const linuxPackagesOperationsContent = `# Operating a package install Day-2 operations for a DocumentDB installed from Linux packages: securing the endpoint, managing services, running SQL, upgrading, and removal. Install first with the [Linux Packages Quick Start](/docs/getting-started/packages). @@ -276,9 +291,25 @@ The gateway binds **all interfaces** (\`0.0.0.0:10260\` and \`[::]:10260\`) by d Before using this anywhere but a private machine: - Restrict the listener with \`DOCUMENTDB_LISTEN_ADDR=127.0.0.1:10260\` in \`/etc/documentdb/local//gateway.env\` and restart the service, or firewall port \`10260\`. **Re-running \`documentdb-setup\` silently resets this to a wildcard bind**, so re-check with \`grep DOCUMENTDB_LISTEN_ADDR /etc/documentdb/local//gateway.env\` afterwards. A firewall rule is the more durable control. -- Replace the auto-generated self-signed certificate. \`tlsAllowInvalidCertificates=true\` disables certificate validation — point \`DOCUMENTDB_TLS_CERT_FILE\` / \`DOCUMENTDB_TLS_KEY_FILE\` at a real certificate and drop that option. - Use a strong admin password and create per-application users rather than sharing \`admin\`. +### Replace the self-signed certificate + +\`tlsAllowInvalidCertificates=true\` disables server authentication. To use a real certificate, +set all three values in \`/etc/documentdb/local//gateway.env\`: + +\`\`\`ini +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 +\`documentdb-gateway-local@.service\`, verify it is active, and then remove +\`tlsAllowInvalidCertificates=true\` from clients. + ## Services and paths \`\`\`bash @@ -305,9 +336,35 @@ sudo systemctl restart documentdb-local@18.target sudo systemctl stop documentdb-local@18.target \`\`\` -## Running SQL against the managed instance +## 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 \`/\`. 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. + +\`\`\`bash +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\`. -\`documentdb-setup\` runs a private instance as the \`documentdb-local\` user on a socket, so a bare \`psql\` will not find it: +## Running SQL against a package-managed private instance + +A greenfield PostgreSQL instance runs as the \`documentdb-local\` user on a socket, so a bare +\`psql\` will not find it: \`\`\`bash sudo -u documentdb-local psql -h /run/documentdb-local/18/postgresql -p 9718 -d postgres @@ -317,9 +374,37 @@ sudo -u documentdb-local psql -h /run/documentdb-local/18/postgresql -p 9718 -d SELECT extname, extversion FROM pg_extension WHERE extname LIKE 'documentdb%'; \`\`\` +For an adopted instance, use the operator's existing PostgreSQL connection instead. + ## Upgrading -A package upgrade only replaces files. Afterwards, update the extensions in every database that has DocumentDB installed: +> [!WARNING] +> v0.116 does not support an in-place upgrade from the extension-only package layout in +> v0.114 or earlier. Use a clean host, or remove the earlier packages and perform the current +> [fresh installation](/docs/getting-started/packages). Upgrading only +> \`postgresql-N-documentdb\` does not install the gateway, tools, common payload, or +> \`documentdb-N\`. + +For a later point release that uses the same multi-package layout, move the entire stack +together. On a package-managed private PostgreSQL 18 instance: + +\`\`\`bash +sudo systemctl stop documentdb-gateway-local@18.service + +# Debian / Ubuntu +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 dnf upgrade documentdb-18 postgresql18-documentdb \\ + documentdb-common documentdb-gateway documentdb-postgresql-tools + +# PostgreSQL has the old shared library loaded until it restarts. +sudo systemctl restart documentdb-postgresql@18.service +\`\`\` + +Then update the extensions in **every database** that has DocumentDB installed: \`\`\`sql ALTER EXTENSION documentdb_core UPDATE; @@ -327,16 +412,23 @@ ALTER EXTENSION documentdb UPDATE; ALTER EXTENSION documentdb_extended_rum UPDATE; -- only if installed \`\`\` -PostgreSQL applies intermediate upgrade scripts automatically. In-place upgrades are not yet a fully tested path, so take a backup first. +Finally restart the gateway: + +\`\`\`bash +sudo systemctl start documentdb-gateway-local@18.service +\`\`\` + +PostgreSQL applies intermediate upgrade scripts automatically. Take a backup first. For an +adopted PostgreSQL instance, restart its operator-managed PostgreSQL service instead of +\`documentdb-postgresql@18.service\`. ## Remove or reset -\`\`\`bash -# Stop the stack first. On systemd hosts: -sudo systemctl stop documentdb-local@18.target -# Without systemd, use an UNSCOPED restore (no --pg-version): -sudo documentdb-setup --restore +### Greenfield: destroy the package-managed instance +\`\`\`bash +# 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 # DESTROYS the data directory # Name the package you installed AND the extension: autoremove does not reap @@ -345,7 +437,53 @@ sudo apt purge --autoremove documentdb-18 postgresql-18-documentdb sudo dnf remove documentdb-18 postgresql18-documentdb && sudo dnf autoremove \`\`\` -Confirm the stack is down first with \`ss -lnt | grep 10260\`. A gateway still running when its packages go keeps serving from a deleted binary. On a multi-major host remove one major at a time and re-check the survivor: \`documentdb-common\` owns the shared tooling and only \`documentdb-N\` holds it. +### Brownfield: detach from an 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: + +\`\`\`bash +sudo documentdb-setup --restore --pg-version 18 +\`\`\` + +On a host without systemd, v0.116 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: + +\`\`\`bash +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: + +\`\`\`bash +ss -lnt | grep ':10260' +\`\`\` + +Then remove the selected major: + +\`\`\`bash +sudo apt purge --autoremove documentdb-18 postgresql-18-documentdb +sudo dnf remove documentdb-18 postgresql18-documentdb && sudo dnf autoremove +\`\`\` + +Do not run \`documentdb-local-reset\` for brownfield installations: the PostgreSQL instance and +its data belong to the operator. Do not run restore before a greenfield reset either; restore +deletes the state that identifies custom data directories and protects adopted clusters. + +On a systemd multi-major host, remove one major at a time and re-check the survivor: +\`documentdb-common\` owns the shared tooling and only \`documentdb-N\` holds it. ## Known issues in 0.116 @@ -356,9 +494,8 @@ These are defects in this release, not expected behaviour. Most need a host with | Status | \`documentdb-setup --status\` can report "active" for any process holding port 10260 | **any host** | | Upgrade | \`documentdb-setup\` does not run \`ALTER EXTENSION documentdb_core UPDATE\`; run it yourself | **any host** | | Restart | Re-running \`documentdb-setup\` to restart can hang; redirecting output to a file avoids it | no systemd | -| Stop | \`documentdb-setup --restore --pg-version N\` reports success without stopping the gateway — use an unscoped \`--restore\`, which stops every major on the host | no systemd | +| Stop | A scoped \`documentdb-setup --restore --pg-version N\` cannot stop a nohup gateway; follow the no-systemd brownfield removal steps above | no systemd | | Minimal RHEL | Install \`procps-ng\` first, or \`--restore\` reports success while the gateway keeps serving and a later run fails with \`Port 10260 is already in use\` | no systemd | -| Reset | \`documentdb-local-reset --confirm-destroy\` can report success while leaving a PostgreSQL process running | no systemd | **Prefer a systemd host for anything you care about**, where the service lifecycle is managed by systemd rather than by the setup script. @@ -374,7 +511,8 @@ ERROR: The DocumentDB extension package is not installed for PostgreSQL 17 Each major also needs its own gateway port — the second one fails on \`Gateway port 10260 is already in use\` unless you pass \`--gateway-port\`: \`\`\`bash -sudo documentdb-setup --pg-version 17 --gateway-port 10261 --admin-user admin +sudo documentdb-setup --pg-version 17 --use-new-postgres-instance \\ + --gateway-port 10261 --admin-user admin \`\`\` ## Troubleshooting @@ -383,16 +521,22 @@ Failure modes beyond the four in the [quick start](/docs/getting-started/package - \`Bad GPG signature\` on \`pgdg-common\` — wrong architecture in the PGDG repository URL - \`apt install\` hangs in a container — \`export DEBIAN_FRONTEND=noninteractive\` first, and drop the leading \`sudo\` when running as \`root\` (minimal images often have no \`sudo\`). Keep \`sudo -u \`, which switches user; \`su documentdb-local -c\` fails because that account has \`/usr/sbin/nologin\`, so use \`su -s /bin/bash documentdb-local -c '...'\` -- \`ss: command not found\` on a minimal RHEL host — install \`iproute\`; the DocumentDB packages do not pull it in +- \`ss: command not found\` on a minimal EL9 host — install \`iproute\`; the DocumentDB packages do not pull it in - \`db.version()\` and \`buildInfo\` in \`mongosh\` report the emulated MongoDB wire version, not DocumentDB's — use \`documentdb-gateway --version\` -## Multiple PostgreSQL majors +## Unattended setup -Install the matching \`documentdb-N\` for every major you configure. \`documentdb-setup --pg-version N\` will happily configure a major whose package is absent, and nothing then owns the result — a later \`autoremove\` can reap \`documentdb-common\` out from under it. +\`documentdb-setup\` prompts for the admin password. For servers and CI, provide exactly one +password source and pass \`--yes\`. For a new private instance: -## Unattended setup +\`\`\`bash +printf '%s' "$ADMIN_PW" | sudo documentdb-setup --pg-version 18 \\ + --use-new-postgres-instance --admin-user admin --admin-password-stdin --yes +\`\`\` -\`documentdb-setup\` prompts for the admin password. For servers and CI, pass \`--admin-password-file \` or \`--admin-password-stdin\` together with \`--yes\`. +For brownfield adoption, replace \`--pg-version 18 --use-new-postgres-instance\` with +\`--target-postgres-instance 18/main\`. You can use +\`--admin-password-file /path/to/protected/file\` instead of stdin. `; const linuxPackagesOfflineContent = `# Offline / air-gapped install diff --git a/tests/packageArticles.test.ts b/tests/packageArticles.test.ts new file mode 100644 index 0000000..dc2b87a --- /dev/null +++ b/tests/packageArticles.test.ts @@ -0,0 +1,73 @@ +import { describe, expect, it } from 'vitest'; +import { + linuxPackagesGuideContent, + linuxPackagesOperationsContent, +} from '../app/services/articleService'; + +describe('Linux package articles', () => { + it('keeps advanced setup details out of the quick start', () => { + expect(linuxPackagesGuideContent).toContain( + '/docs/linux-packages#unattended-setup', + ); + expect(linuxPackagesGuideContent).toContain( + '/docs/linux-packages#adopt-an-existing-postgre-sql-instance', + ); + expect(linuxPackagesGuideContent).not.toContain('--admin-password-stdin'); + expect(linuxPackagesGuideContent).not.toContain('--target-postgres-instance'); + }); + + it('documents the supported brownfield adoption workflow', () => { + expect(linuxPackagesOperationsContent).toContain( + '## Adopt an existing PostgreSQL instance', + ); + expect(linuxPackagesOperationsContent).toContain( + 'sudo documentdb-setup --target-postgres-instance 18/main --admin-user admin', + ); + expect(linuxPackagesOperationsContent).toContain( + 'The wizard intentionally does not restart an adopted', + ); + expect(linuxPackagesOperationsContent).toContain( + 'DOCUMENTDB_TOAST_COMPRESSION=default', + ); + }); + + it('distinguishes scoped systemd restore from no-systemd cleanup', () => { + expect(linuxPackagesOperationsContent).toContain( + 'sudo documentdb-setup --restore --pg-version 18', + ); + expect(linuxPackagesOperationsContent).toContain( + 'sudo documentdb-setup --restore --yes', + ); + expect(linuxPackagesOperationsContent).toMatch( + /A scoped restore alone is not\s+sufficient on a no-systemd host\./, + ); + expect(linuxPackagesOperationsContent).toContain( + 'Restart the adopted PostgreSQL service after restore', + ); + expect(linuxPackagesOperationsContent).toContain( + "the command should produce no output", + ); + }); + + it('provides a complete unattended setup command', () => { + expect(linuxPackagesOperationsContent).toContain( + `printf '%s' "$ADMIN_PW" | sudo documentdb-setup --pg-version 18`, + ); + expect(linuxPackagesOperationsContent).toContain( + '--use-new-postgres-instance --admin-user admin --admin-password-stdin --yes', + ); + }); + + it('keeps Package Finder advanced hints linked and version-agnostic', async () => { + const { readFile } = await import('node:fs/promises'); + const { fileURLToPath } = await import('node:url'); + const source = await readFile( + fileURLToPath(new URL('../app/packages/page.tsx', import.meta.url)), + 'utf8', + ); + + expect(source).toContain('href="/docs/linux-packages#unattended-setup"'); + expect(source).toContain('individual subpackages can carry'); + expect(source).not.toContain('and the gateway are'); + }); +}); diff --git a/tests/packageInstall.test.ts b/tests/packageInstall.test.ts index 746ab17..82468d1 100644 --- a/tests/packageInstall.test.ts +++ b/tests/packageInstall.test.ts @@ -5,6 +5,7 @@ import { aptTargetPgVersions, buildAptInstallCommand, buildRpmInstallCommand, + buildSetupCommand, rpmServesFullStack, rpmTargetLabels, } from '../app/lib/packageInstall'; @@ -28,9 +29,15 @@ const expectedPgdgSuites: Record = { }; const expectedRhelMajors: Record = { + rocky9: '9', rhel9: '9', }; +const expectedRpmRepositoryPaths: Record = { + rocky9: 'rhel9', + rhel9: 'rhel9', +}; + const aptDistros = Object.keys(aptTargetLabels) as AptDistro[]; const rpmDistros = Object.keys(rpmTargetLabels) as RpmDistro[]; const aptArches: AptArch[] = ['amd64', 'arm64']; @@ -124,10 +131,9 @@ describe('buildRpmInstallCommand', () => { expect(command).toContain(`EL-${major}-x86_64`); }); - it.each(rpmArches)('uses arch %s in the PGDG and CodeReady repository names', (arch) => { - const command = buildRpmInstallCommand('rhel9', arch, '17'); + it.each(rpmArches)('uses arch %s in the PGDG repository name', (arch) => { + const command = buildRpmInstallCommand('rocky9', arch, '17'); expect(command).toContain(`EL-9-${arch}/pgdg-redhat-repo-latest.noarch.rpm`); - expect(command).toContain(`codeready-builder-for-rhel-9-${arch}-rpms`); }); it('resolves the architecture on the host when arch is "auto"', () => { @@ -138,9 +144,11 @@ describe('buildRpmInstallCommand', () => { expect(command).not.toContain('EL-9-aarch64'); }); - it.each(rpmDistros)('points the DocumentDB repository at rpm/%s', (distro) => { + it.each(rpmDistros)('points %s at the shared EL9 DocumentDB repository', (distro) => { const command = buildRpmInstallCommand(distro, 'x86_64', '17'); - expect(command).toContain(`baseurl=https://documentdb.io/rpm/${distro}`); + expect(command).toContain( + `baseurl=https://documentdb.io/rpm/${expectedRpmRepositoryPaths[distro]}`, + ); }); it.each(rpmMatrix)('installs the right package for $distro/$arch/pg$pg', ({ distro, arch, pg }) => { @@ -152,6 +160,8 @@ describe('buildRpmInstallCommand', () => { }); it('serves the full stack for every published target', () => { + expect(rpmServesFullStack('rocky9', '18')).toBe(true); + expect(rpmServesFullStack('rocky9', '17')).toBe(true); expect(rpmServesFullStack('rhel9', '18')).toBe(true); expect(rpmServesFullStack('rhel9', '17')).toBe(true); expect(aptServesFullStack('ubuntu24', '18')).toBe(true); @@ -161,9 +171,35 @@ describe('buildRpmInstallCommand', () => { ); }); + it('uses CRB for Rocky, AlmaLinux, and CentOS Stream', () => { + const command = buildRpmInstallCommand('rocky9', 'x86_64', '18'); + expect(command).toContain('sudo dnf config-manager --set-enabled crb'); + expect(command).not.toContain('subscription-manager repos --enable'); + expect(command).not.toContain('codeready-builder-for-rhel'); + }); + + it('uses subscription-manager for registered RHEL', () => { + const command = buildRpmInstallCommand('rhel9', 'aarch64', '18'); + expect(command).toContain( + 'sudo subscription-manager repos --enable codeready-builder-for-rhel-9-aarch64-rpms', + ); + expect(command).not.toContain('dnf config-manager --set-enabled crb'); + }); + it('enables gpgcheck against the DocumentDB signing key', () => { - const command = buildRpmInstallCommand('rhel9', 'x86_64', '17'); + const command = buildRpmInstallCommand('rocky9', 'x86_64', '17'); expect(command).toContain("'gpgcheck=1'"); expect(command).toContain("'gpgkey=https://documentdb.io/documentdb-archive-keyring.gpg'"); }); }); + +describe('buildSetupCommand', () => { + it.each(['17', '18'] as const)( + 'pins PostgreSQL %s and creates a fresh private instance', + (pgVersion) => { + expect(buildSetupCommand(pgVersion)).toBe( + `sudo documentdb-setup --pg-version ${pgVersion} --use-new-postgres-instance --admin-user admin`, + ); + }, + ); +});