Fix Linux package install guide and Package Finder

PACKAGE-INSTALL.md

@@ -1,25 +1,30 @@
 # DocumentDB Package Installation
 
-Verified installation commands for the DocumentDB PostgreSQL extension.
+Repository-backed installation commands for the DocumentDB PostgreSQL extension package.
 
-## What was validated
+## What is published
 
-- Repository-backed installs were exercised in Docker on Ubuntu 22.04, Ubuntu 24.04, Debian 11, Debian 12, Rocky Linux 8, and Rocky Linux 9.
-- Both `amd64`/`x86_64` and `arm64`/`aarch64` variants were checked.
-- PostgreSQL package variants `16`, `17`, and `18` were resolved successfully for the supported repository-backed combinations, with one exception: Debian 11 currently resolves PostgreSQL `16` and `17` only.
+- Repository-backed extension packages are published for Ubuntu 22.04, Ubuntu 24.04, Debian 11, Debian 12, Debian 13, RHEL-compatible 8, and RHEL-compatible 9 targets.
+- Both `amd64`/`x86_64` and `arm64`/`aarch64` variants are published.
+- PostgreSQL package variants `16`, `17`, and `18` are published for the supported repository-backed combinations, with one exception: Debian 11 currently resolves PostgreSQL `16` and `17` only.
 - Debian 13 `.deb` assets are published on GitHub Releases, and the APT repository now publishes a `deb13` component for repository-backed installs.
+- The published package repository installs the PostgreSQL extension package. It does not currently publish a gateway package, setup helper, or systemd service in either the repository-backed install flow or GitHub Releases.
 
 ## Supported PostgreSQL Versions
 
 - Ubuntu 22.04 / 24.04: 16, 17, 18
 - Debian 11: 16, 17
 - Debian 12: 16, 17, 18
 - Debian 13: 16, 17, 18
-- RHEL-family 8 / 9: 16, 17, 18
+- RHEL-compatible 8 / 9: 16, 17, 18
 
 ## Repository-backed package installs
 
-These commands install the required PostgreSQL upstream repositories first, then add the DocumentDB package repository, and finally install the DocumentDB extension package.
+These commands install the required PostgreSQL upstream repositories first, then add the DocumentDB package repository, and finally install the DocumentDB PostgreSQL extension package.
+
+> These commands assume a regular Linux host where you use `sudo`. If you are testing in a clean container that already runs as `root`, omit `sudo` from the package-install commands.
+>
+> On Debian and Ubuntu in a clean container, also run `export DEBIAN_FRONTEND=noninteractive` in the shell before the APT commands. Without it, `tzdata` (and a few other packages) prompt for input during `apt install` and the install hangs with no visible error.
 
 ### Ubuntu 22.04 (Jammy)
 
@@ -86,7 +91,7 @@ sudo apt update && \
 sudo apt install -y postgresql-16-documentdb
 ```
 
-### RHEL / Rocky / AlmaLinux / CentOS Stream 8
+### RHEL-compatible 8
 
 ```bash
 sudo dnf install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm && \
@@ -107,7 +112,7 @@ printf '%s\n' \
 sudo dnf install -y postgresql16-documentdb
 ```
 
-### RHEL / Rocky / AlmaLinux / CentOS Stream 9
+### RHEL-compatible 9
 
 ```bash
 sudo dnf install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm && \
@@ -155,9 +160,94 @@ dnf --showduplicates list postgresql16-documentdb
 sudo dnf install postgresql16-documentdb-<VERSION>
 ```
 
+## From package install to a local `mongosh` endpoint
+
+The repository-backed install gives you the PostgreSQL extension package. To expose a local MongoDB-compatible endpoint on the same host, run PostgreSQL and the gateway from the source repository against the packaged extension files.
+
+### Prerequisites
+
+- `git`
+- `curl`
+- Native build tools for Rust crates that link against OpenSSL
+- A current Rust toolchain via `rustup`
+- `mongosh`
+
+> Run the PostgreSQL and gateway steps from an unprivileged user account, not `root`. PostgreSQL will not initialize as `root`.
+>
+> If you are following these steps in a clean container that starts as `root`, finish the package-install commands as `root`, then switch to an unprivileged account such as `postgres` before you start PostgreSQL or the gateway.
+
+```bash
+# from a root shell inside the container
+su - postgres
+```
+
+Example package-manager installs:
+
+```bash
+# Debian / Ubuntu
+sudo apt install -y git curl build-essential pkg-config libssl-dev
+
+# RHEL-compatible
+sudo dnf install -y git curl gcc gcc-c++ make pkgconf-pkg-config openssl-devel
+```
+
+Install a current Rust toolchain with `rustup`, then load it into your shell:
+
+```bash
+curl https://sh.rustup.rs -sSf | sh -s -- -y
+. "$HOME/.cargo/env"
+```
+
+In a clean container that starts as `root`, install the system packages above and install `mongosh` while you are still `root`. Then switch to the unprivileged user and run the `rustup` commands plus the remaining gateway steps from that user's shell.
+
+### Example host flow
+
+Replace `<PG_MAJOR>` with the PostgreSQL major version you installed from the package repository, such as `16`, `17`, or `18`.
+
+If you do not already have `mongosh`, install it with the official MongoDB shell instructions for your distro before continuing:
+
+- https://www.mongodb.com/docs/mongodb-shell/install/
+
+```bash
+git clone https://github.com/documentdb/documentdb.git
+cd documentdb
+
+export PG_VERSION_USED=<PG_MAJOR>
+
+# Required in non-interactive shells (CI, `docker exec` without `-t`,
+# `docker exec -d`, `nohup`, background `&`). build_and_start_gateway.sh
+# calls `tput` for colored output and aborts under `set -u` / `set -e` if
+# TERM is unset or set to `dumb`. Skip this line in a normal interactive
+# terminal where TERM is already `xterm`, `xterm-256color`, etc.
+export TERM=xterm
+
+./scripts/start_oss_server.sh -c -u <YOUR_USERNAME> -a <YOUR_PASSWORD>
+
+./scripts/build_and_start_gateway.sh -c \
+  -u <YOUR_USERNAME> \
+  -p <YOUR_PASSWORD> \
+  -P 9712
+```
+
+- `./scripts/start_oss_server.sh -c` initializes a fresh local PostgreSQL data directory under `~/.documentdb/data`.
+- `./scripts/build_and_start_gateway.sh -c` forces a clean gateway rebuild; after the first successful build, you can omit `-c` on later restarts.
+- Keep the gateway command running in the foreground. It listens on port `10260` and connects to PostgreSQL on port `9712`.
+- The first gateway build downloads several hundred Rust crates and typically takes a few minutes before the gateway begins listening on port `10260`. Subsequent runs without `-c` are much faster.
+
+Then connect with `mongosh`:
+
+```bash
+mongosh localhost:10260 \
+  -u <YOUR_USERNAME> \
+  -p <YOUR_PASSWORD> \
+  --authenticationMechanism SCRAM-SHA-256 \
+  --tls \
+  --tlsAllowInvalidCertificates
+```
+
 ## Direct downloads
 
-GitHub Releases contains `.deb` and `.rpm` assets for every published combination, including Debian 13 release assets.
+GitHub Releases contains `.deb` and `.rpm` extension assets for every published combination, including Debian 13 release assets. It does not currently publish a gateway package.
 
 Examples:
 
@@ -174,4 +264,5 @@ rhel9-postgresql18-documentdb-0.110.0-1.el9.x86_64.rpm
 
 - The APT repository currently publishes components for `ubuntu22`, `ubuntu24`, `deb11`, `deb12`, and `deb13`.
 - Debian 11 PostgreSQL 18 assets exist, but the upstream Bullseye PostGIS dependency is not currently installable from PGDG.
-- The RPM flow depends on EPEL plus PostgreSQL's upstream RPM repository because DocumentDB depends on PostgreSQL, `pg_cron`, `pgvector`, PostGIS, and `rum`.
+- 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 16/17.
+- On Debian/Ubuntu, the distro-packaged `cargo` can be older than the current gateway workspace lockfile. `rustup` avoids that mismatch.

app/lib/packageInstall.ts

@@ -14,8 +14,8 @@ export const aptTargetLabels: Record<AptDistro, string> = {
 };
 
 export const rpmTargetLabels: Record<RpmDistro, string> = {
-  rhel8: "RHEL 8 / Rocky 8 / AlmaLinux 8 / CentOS Stream 8",
-  rhel9: "RHEL 9 / Rocky 9 / AlmaLinux 9 / CentOS Stream 9",
+  rhel8: "RHEL-compatible 8 (tested on Rocky Linux 8)",
+  rhel9: "RHEL-compatible 9 (tested on Rocky Linux 9)",
 };
 
 export const aptTargetPgVersions: Record<AptDistro, AptPgVersion[]> = {
@@ -53,7 +53,7 @@ echo "deb [signed-by=/usr/share/keyrings/postgresql.gpg] https://apt.postgresql.
 curl -fsSL https://documentdb.io/documentdb-archive-keyring.gpg | sudo gpg --dearmor --yes -o /usr/share/keyrings/documentdb-archive-keyring.gpg && \\
 echo "deb [arch=${aptArch} signed-by=/usr/share/keyrings/documentdb-archive-keyring.gpg] https://documentdb.io/deb stable ${aptTarget}" | sudo tee /etc/apt/sources.list.d/documentdb.list >/dev/null && \\
 sudo apt update && \\
-sudo apt install -y postgresql-${aptPgVersion}-documentdb documentdb_gateway`;
+sudo apt install -y postgresql-${aptPgVersion}-documentdb`;
 }
 
 export function buildRpmInstallCommand(
@@ -78,5 +78,5 @@ printf '%s\\n' \\
   '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 postgresql${rpmPgVersion}-documentdb documentdb-gateway`;
+sudo dnf install -y postgresql${rpmPgVersion}-documentdb`;
 }

app/packages/page.tsx

@@ -79,17 +79,11 @@ export default function PackagesPage() {
   const rpmCommand = buildRpmInstallCommand(rpmTarget, rpmArch, rpmPgVersion);
   const selectedPackageNames =
     packageFamily === "apt"
-      ? `postgresql-${aptPgVersion}-documentdb + documentdb_gateway`
-      : `postgresql${rpmPgVersion}-documentdb + documentdb-gateway`;
+      ? `postgresql-${aptPgVersion}-documentdb`
+      : `postgresql${rpmPgVersion}-documentdb`;
   const selectedTargetText =
     packageFamily === "apt" ? aptTargetLabels[aptTarget] : rpmTargetLabels[rpmTarget];
   const selectedArchText = packageFamily === "apt" ? aptArch : rpmArch;
-  const selectedPgVersion = packageFamily === "apt" ? aptPgVersion : rpmPgVersion;
-  const setupCommand = `sudo documentdb-setup \\
-  --username <YOUR_USERNAME> \\
-  --password <YOUR_PASSWORD> \\
-  --pg-version ${selectedPgVersion} \\
-  --load-sample-data`;
 
   return (
     <div className="min-h-screen bg-neutral-900 py-12">
@@ -99,9 +93,9 @@ export default function PackagesPage() {
             Download DocumentDB
           </h1>
           <p className="mx-auto max-w-3xl text-lg text-gray-300">
-            Choose Docker for the fastest local setup, or Linux packages for managed host
-            installations. The generated package commands configure the PostgreSQL
-            dependency repositories and install the packages required by DocumentDB.
+            Choose Docker for the fastest local setup, or Linux packages for PostgreSQL
+            extension installs. The generated package commands configure the PostgreSQL
+            dependency repositories and install the DocumentDB extension package.
           </p>
           <div className="mt-4 flex flex-wrap justify-center gap-3 text-sm">
             <span className="rounded-full border border-green-500/30 bg-green-500/20 px-3 py-1 text-green-300">
@@ -287,21 +281,30 @@ export default function PackagesPage() {
                 The generated command adds the PostgreSQL upstream repositories that provide
                 PostgreSQL, <code className="text-gray-300">pg_cron</code>,{" "}
                 <code className="text-gray-300">pgvector</code>, PostGIS, and{" "}
-                <code className="text-gray-300">rum</code>.
+                <code className="text-gray-300">rum</code> for PostgreSQL 16/17.
               </p>
               <p className="mt-2 text-sm text-gray-400">
-                It also installs the PostgreSQL extension package plus the gateway package
-                required for MongoDB-compatible connections on port 10260.
+                It installs the PostgreSQL extension package. The published package repository
+                does not currently include a gateway package, setup helper, or systemd service.
               </p>
+              {packageFamily === "apt" ? (
+                <p className="mt-2 text-sm text-gray-400">
+                  Running in a clean Debian/Ubuntu container as <code className="text-gray-300">root</code>?
+                  Run <code className="text-gray-300">export DEBIAN_FRONTEND=noninteractive</code> in the shell first
+                  (and omit <code className="text-gray-300">sudo</code> from the command above).
+                  Without it, <code className="text-gray-300">tzdata</code> prompts for input partway through
+                  and the install hangs with no visible error.
+                </p>
+              ) : null}
               <div className="mt-4 rounded-lg border border-neutral-700 bg-neutral-900/60 p-4">
                 <p className="mb-3 text-sm font-semibold text-white">
-                  Then initialize and start DocumentDB
+                  Need the MongoDB-compatible gateway?
                 </p>
-                <CommandSnippet command={setupCommand} label="Setup" />
                 <p className="mt-3 text-sm text-gray-400">
-                  Use <code className="text-gray-300">--skip-pg-init</code> and{" "}
-                  <code className="text-gray-300">--pg-port</code> if you want to attach
-                  DocumentDB to an existing PostgreSQL cluster instead of creating a new one.
+                  Use the Docker image for the fastest gateway-backed local setup. If you want a
+                  package-backed host install that still works with <code className="text-gray-300">mongosh</code>,
+                  the Linux package guide includes the exact non-root gateway follow-up commands
+                  and host build prerequisites.
                 </p>
               </div>
               {packageFamily === "apt" ? (
@@ -351,7 +354,7 @@ export default function PackagesPage() {
                   <tr>
                     <td className="px-3 py-3 font-semibold text-red-300">RPM</td>
                     <td className="px-3 py-3">
-                      RHEL 8/9, Rocky, AlmaLinux, CentOS Stream
+                       RHEL-compatible 8/9 (tested on Rocky Linux)
                     </td>
                     <td className="px-3 py-3">x86_64, aarch64</td>
                     <td className="px-3 py-3">16, 17, 18</td>
@@ -463,19 +466,13 @@ export default function PackagesPage() {
               <div className="rounded-md border border-neutral-700 bg-black p-3">
                 <code className="text-xs text-green-400 sm:text-sm">
                   sudo apt update && apt search documentdb && apt-cache policy
-                  postgresql-16-documentdb documentdb_gateway
+                  postgresql-16-documentdb
                 </code>
               </div>
               <div className="rounded-md border border-neutral-700 bg-black p-3">
                 <code className="text-xs text-green-400 sm:text-sm">
                   sudo dnf clean all && dnf search documentdb && rpm -qi
-                  postgresql16-documentdb documentdb-gateway
-                </code>
-              </div>
-              <div className="rounded-md border border-neutral-700 bg-black p-3">
-                <code className="text-xs text-green-400 sm:text-sm">
-                  sudo systemctl status documentdb-gateway --no-pager && sudo journalctl -u
-                  documentdb-gateway --no-pager -n 20
+                  postgresql16-documentdb
                 </code>
               </div>
             </div>
@@ -488,9 +485,10 @@ export default function PackagesPage() {
               3. Connect and try it
             </h2>
             <p className="text-sm leading-6 text-gray-400">
-              After you run <code className="text-gray-300">documentdb-setup</code> and the
-              gateway is listening on port 10260, follow one of these guides to make your first
-              connection.
+              Docker starts a gateway-backed local endpoint on port 10260. Linux packages install
+              the PostgreSQL extension; the Linux package guide adds the extra source-gateway
+              steps needed when you want a host install that still exposes a MongoDB-compatible
+              endpoint.
             </p>
           </div>