Back to Documentation

Getting Started

Linux Packages Quick Start

Install DocumentDB on Debian, Ubuntu, or RHEL-family hosts with repository-backed packages.

Choose the right package command

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

The generated command installs both the PostgreSQL extension package and the gateway package required for MongoDB-compatible connections on port 10260.

The repository-backed install commands currently cover Ubuntu 22.04/24.04, Debian 11/12/13, and RHEL-family 8/9 systems. Debian 11 currently resolves PostgreSQL 16 and 17 in the repository-backed flow.

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 documentdb_gateway

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 documentdb-gateway

Initialize and start DocumentDB

After the packages are installed, run the packaged setup command:

sudo documentdb-setup \
  --username <YOUR_USERNAME> \
  --password <YOUR_PASSWORD> \
  --pg-version 16 \
  --load-sample-data

If you selected PostgreSQL 17 or 18 in the Package Finder, use that version in --pg-version.

If you want to attach DocumentDB to an existing PostgreSQL cluster instead of creating a new local cluster, use --skip-pg-init --pg-port <PORT>.

Verify the setup

Use the gateway service status and mongosh to confirm the host install is ready:

sudo systemctl status documentdb-gateway --no-pager

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

Then run a quick health check and inspect the sample data:

db.runCommand({ ping: 1 })

use sampledb

db.users.find({}, { name: 1, email: 1, _id: 0 }).limit(3)

If you skipped --load-sample-data, create your own collection instead of querying sampledb.

Existing PostgreSQL clusters and custom ports

sudo documentdb-setup \
  --skip-pg-init \
  --pg-port 5432 \
  --gateway-port 10260 \
  --username <YOUR_USERNAME> \
  --password <YOUR_PASSWORD>

Use --data-dir and --pg-owner when your environment needs explicit PostgreSQL paths or ownership settings.

Troubleshooting and debugging

If something does not work on the first try:

  • Confirm both packages are installed: postgresql-<PG>-documentdb plus documentdb_gateway on APT, or postgresql<PG>-documentdb plus documentdb-gateway on RPM
  • Re-run documentdb-setup --help to review cluster, port, and sample-data options
  • Use sudo documentdb-setup --verbose ... for more detailed setup output
  • Check the gateway service with sudo systemctl status documentdb-gateway
  • Inspect recent gateway logs with sudo journalctl -u documentdb-gateway --no-pager -n 50
  • If setup reports a PostgreSQL port or cluster conflict, use --skip-pg-init or choose a different --pg-port

Next steps