Choose the right package command

Use the Package Finder to generate the exact install command for your distro, architecture, and PostgreSQL version.

Install the packages

APT example

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=amd64 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 postgresql-16-documentdb

RPM example

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-x86_64/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-9-x86_64-rpms) && \
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 postgresql16-documentdb

What the package installs

The packages install the DocumentDB PostgreSQL extension files for the selected PostgreSQL major version. They do not by themselves start a MongoDB-compatible gateway endpoint on port 10260.

Use the Docker quick start when you need the fastest local gateway-backed DocumentDB endpoint:

docker run -dt --name documentdb \
  -p 10260:10260 \
  ghcr.io/documentdb/documentdb/documentdb-local:latest \
  --username <YOUR_USERNAME> \
  --password <YOUR_PASSWORD>

If you are operating a host PostgreSQL installation, configure PostgreSQL and run the gateway using the source repository's build/run scripts.

Verify the package install

Use package-manager metadata to confirm the extension package is installed:

# APT
apt-cache policy postgresql-16-documentdb
dpkg -L postgresql-16-documentdb | grep -E 'documentdb.*\.(control|sql|so)$' | head

# RPM
dnf info postgresql16-documentdb
rpm -ql postgresql16-documentdb | grep -E 'documentdb.*\.(control|sql|so)$' | head

Turn a package install into a local `mongosh` endpoint

If you want to keep PostgreSQL on the host and still connect with mongosh, install the extension package first and then run the gateway from the source repository against that PostgreSQL instance.

Prerequisites for the host gateway step

• 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.

# from a root shell inside the container
su - postgres

Install the host prerequisites with your distro package manager before continuing. Examples:

# 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:

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.

Host setup example

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/

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.

The first gateway build downloads several hundred Rust crates and typically takes a few minutes on a fresh machine before the gateway begins listening on port 10260. Subsequent runs without -c are much faster.

Keep the gateway command running in the foreground. It starts the MongoDB-compatible endpoint on port 10260 and connects it to PostgreSQL on port 9712.

Then connect with mongosh:

mongosh localhost:10260 \
  -u <YOUR_USERNAME> \
  -p <YOUR_PASSWORD> \
  --authenticationMechanism SCRAM-SHA-256 \
  --tls \
  --tlsAllowInvalidCertificates

Use this flow when you want a package-backed host install plus a local MongoDB-compatible endpoint. Use the Docker quick start instead when you want the shortest local setup path.

Troubleshooting and debugging

If something does not work on the first try:

• Confirm the extension package is installed: postgresql-<PG>-documentdb on APT or postgresql<PG>-documentdb on RPM
• Re-run the Package Finder command for the exact distro, architecture, and PostgreSQL version you selected
• Confirm the PostgreSQL upstream repository was added before the DocumentDB package install
• If you are running in a clean container as root, omit sudo from the package-install commands and switch to an unprivileged user before the gateway steps
• If apt install hangs forever in a clean container, run export DEBIAN_FRONTEND=noninteractive in that shell and re-run the install; the default front-end is waiting for a tzdata prompt that never gets typed
• If you use the host gateway flow, confirm PG_VERSION_USED matches the PostgreSQL major version you installed
• If ./scripts/build_and_start_gateway.sh exits immediately with tput: No value for $TERM (or silently with set -e when TERM=dumb), set export TERM=xterm before re-running, or run the script from an interactive shell (for Docker, docker exec -it ...)
• If ./scripts/build_and_start_gateway.sh fails, confirm git, curl, native build tools, pkg-config, OpenSSL headers, and a current Rust toolchain are installed on the host
• If the gateway build fails while reading Cargo.lock, switch to a current Rust toolchain from rustup instead of the distro-packaged cargo
• If mongosh cannot connect, confirm the gateway script is still running and listening on port 10260
• For Debian 11, use PostgreSQL 16 or 17; PostgreSQL 18 is blocked by the upstream Bullseye PostGIS dependency
• If you need a gateway endpoint, use DocumentDB Local with Docker or build and run the gateway from source

Next steps

• Docker Quick Start
• Building from source
• Mongo Shell Quick Start
• Node.js Quick Start
• Python Quick Start
• API Reference
• Samples Gallery
• Package Finder