Operating a package install

Before exposing it to a network

The gateway binds all interfaces (0.0.0.0:10260 and [::]:10260) by default. The PostgreSQL instance behind it stays on loopback.

Before using this anywhere but a private machine:

• Restrict the listener with DOCUMENTDB_LISTEN_ADDR=127.0.0.1:10260 in /etc/documentdb/local/<major>/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/<major>/gateway.env afterwards. A firewall rule is the more durable control.
• 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/<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 documentdb-gateway-local@<major>.service, verify it is active, and then remove tlsAllowInvalidCertificates=true from clients.

Services and paths

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

On a systemd host both services log to the journal; the log files above exist only when documentdb-setup falls back to its non-systemd nohup mode. documentdb-setup --status prints whichever applies to your host.

Units are templated per PostgreSQL major:

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

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 runs as the documentdb-local user 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

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

For an adopted instance, use the operator's existing PostgreSQL connection instead.

Upgrading

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:

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:

ALTER EXTENSION documentdb_core UPDATE;
ALTER EXTENSION documentdb UPDATE;
ALTER EXTENSION documentdb_extended_rum UPDATE;  -- only if installed

Finally restart the gateway:

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

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    # DESTROYS the data directory

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

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:

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:

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

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

These are defects in this release, not expected behaviour. Most need a host without systemd to hit; the two marked any host do not.

Prefer a systemd host for anything you care about, where the service lifecycle is managed by systemd rather than by the setup script.

Multiple PostgreSQL majors

Install the matching documentdb-N for every major you configure. documentdb-setup refuses a major whose extension package is missing:

ERROR: The DocumentDB extension package is not installed for PostgreSQL 17
(/usr/share/postgresql/17/extension/documentdb.control is missing).

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:

sudo documentdb-setup --pg-version 17 --use-new-postgres-instance \
  --gateway-port 10261 --admin-user admin

Troubleshooting

Failure modes beyond the four in the quick start:

• 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 <user>, 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 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

Unattended setup

documentdb-setup prompts for the admin password. For servers and CI, provide exactly one password source and pass --yes. For a new private instance:

printf '%s' "$ADMIN_PW" | sudo documentdb-setup --pg-version 18 \
  --use-new-postgres-instance --admin-user admin --admin-password-stdin --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.