DocumentDB Local

Prerequisites

• Docker

Installation

Get the Docker container image using docker pull.

docker pull ghcr.io/documentdb/documentdb/documentdb-local:pg17-1.0.0

Running

Choose the admin credentials first, in the same terminal (this works in bash and zsh):

printf 'DocumentDB username: '; IFS= read -r DOCUMENTDB_USERNAME
printf 'DocumentDB password: '; IFS= read -r -s DOCUMENTDB_PASSWORD; echo
export DOCUMENTDB_USERNAME DOCUMENTDB_PASSWORD

Then start the container with docker run, and use docker ps to check that it is running:

docker run -dt -p 127.0.0.1:10260:10260 --name docdb \
  -e USERNAME="${DOCUMENTDB_USERNAME:?Set DOCUMENTDB_USERNAME first}" \
  -e PASSWORD="${DOCUMENTDB_PASSWORD:?Set DOCUMENTDB_PASSWORD first}" \
  ghcr.io/documentdb/documentdb/documentdb-local:pg17-1.0.0

docker ps

CONTAINER ID   IMAGE                                                         COMMAND                  CREATED         STATUS                            PORTS                        NAMES
5aff734a3591   ghcr.io/documentdb/documentdb/documentdb-local:pg17-1.0.0     "/bin/bash -c '/home…"   5 seconds ago   Up 4 seconds (health: starting)   127.0.0.1:10260->10260/tcp   docdb

Wait for the container to be ready

docker ps reports the container as Up well before DocumentDB can accept connections - PostgreSQL has to initialize, the extensions have to be set up, and the admin user has to be created first. Connecting too early fails with MongoServerSelectionError or ECONNREFUSED.

The entrypoint prints a ready banner after gateway startup and any requested data initialization finish. Wait for it before connecting:

until docker logs docdb 2>&1 | grep -q "=== DocumentDB is ready ==="; do sleep 2; done

First start typically takes a few tens of seconds. If the command has not returned after a couple of minutes, the container most likely exited during startup - interrupt it and check docker ps -a and docker logs docdb for the error.

Connect with mongosh

mongosh localhost:10260 \
  -u "${DOCUMENTDB_USERNAME:?Set DOCUMENTDB_USERNAME first}" \
  -p \
  --authenticationMechanism SCRAM-SHA-256 \
  --tls --tlsAllowInvalidCertificates

Current Mongosh Log ID:	690cdcb84e2e610f0f48e609
Connecting to:		mongodb://<credentials>@localhost:10260/?tls=true&tlsAllowInvalidCertificates=true&directConnection=true&serverSelectionTimeoutMS=2000&appName=mongosh+2.5.1
Using MongoDB:		7.0.0
Using Mongosh:		2.5.1
mongosh 2.5.9 is available for download: https://www.mongodb.com/try/download/shell

For mongosh info see: https://www.mongodb.com/docs/mongodb-shell/

[direct: mongos] test>

Docker commands

The following table summarizes the available Docker commands for configuring the emulator. This table details the corresponding arguments, environment variables, allowed values, default settings, and descriptions of each command.

A complete docker run showing where each kind of option goes - Docker options before the image name, container arguments after it. This is the command from the Running section above with a persistent volume and sample data added, so remove that container first with docker rm -f docdb:

docker run -dt \
  -p 127.0.0.1:10260:10260 \
  -v documentdb-data:/data \
  --name docdb \
  -e USERNAME="${DOCUMENTDB_USERNAME:?Set DOCUMENTDB_USERNAME first}" \
  -e PASSWORD="${DOCUMENTDB_PASSWORD:?Set DOCUMENTDB_PASSWORD first}" \
  ghcr.io/documentdb/documentdb/documentdb-local:pg17-1.0.0 \
  --init-data true

Usage telemetry

The 1.0 image sends usage data by default. The native packages send nothing.

At startup and then hourly, the image reports its version, platform and CPU architecture to Scarf. It never sends database, collection or user names, queries, documents or credentials. Scarf does see the source IP address of each request, and the privacy statement says that address shouldn't be assumed to be anonymous once received. A [TELEMETRY] notice in the container log says when it is on.

To turn it off, add any of these before the image name:

-e DOCUMENTDB_USAGE_TELEMETRY=false
-e NO_ANALYTICS=1
-e DO_NOT_TRACK=1

or --disable-usage-telemetry (or --usage-telemetry false) after it. NO_ANALYTICS and DO_NOT_TRACK win over any setting that turns it on. To send the reports to your own collector instead, set DOCUMENTDB_USAGE_TELEMETRY_ENDPOINT.

In CI, turn it off explicitly with -e DOCUMENTDB_USAGE_TELEMETRY=false. The image skips telemetry only when CI, GITHUB_ACTIONS or TF_BUILD is set to a non-empty value in the container's own environment, and docker run doesn't pass the runner's variables through: a container started on a CI runner still reports unless you forward one, for example -e GITHUB_ACTIONS. --enable-telemetry is a separate setting for the gateway's own metrics and doesn't affect this.

The privacy statement has the details. The image also includes it at /home/documentdb/PRIVACY.md.

Built-in sample data

The built-in sample data is the StoreData dataset. Loading it is opt-in: add --init-data true to the container arguments, as in the example above. If you also give scripts in --init-data-path, both run: your scripts first, then the sample data, each tracked by its own marker in the volume.

The bundled Extended JSON preserves BSON Binary, Date, and Timestamp values. After the ready banner, inspect the collections with mongosh:

db.getSiblingDB("StoreData").stores.countDocuments({})   // 41505
db.getSiblingDB("StoreData").ratings.countDocuments({})  // 2

Seeding is one-shot per data volume; use a new, empty volume to seed again. A direct loader rerun tolerates duplicate keys rather than duplicating documents. See the versioned sample-data guide for manual loader instructions.

Container lifecycle

• Health check. The image has a Docker health check. docker inspect -f '{{.State.Health.Status}}' docdb reports healthy once DocumentDB accepts connections.
• Stale postmaster.pid. After docker kill, docker rm -f, an out-of-memory kill or a host crash, the next start removes the stale file, but only when the volume's lock shows a 1.0 container wrote it. Otherwise it refuses to start, because an older container may still be using the volume. Once nothing else uses it, re-create the container once with -e DOCUMENTDB_FORCE_REMOVE_STALE_POSTMASTER_PID=true, then without it (docker start can't add the variable). Don't share a volume between hosts. A second container on a volume that is already in use exits immediately.
• PostgreSQL loss stops the container. If PostgreSQL inside the container stops, the gateway fails requests straight away and the container exits after 20 seconds (DOCUMENTDB_POSTMASTER_EXIT_TIMEOUT), so a restart policy can bring it back.

Upgrading the image

A newer image on an existing data volume doesn't update the DocumentDB extensions in it (#773), so the volume keeps the old schema under the new binaries. Upgrading a volume in place is not supported in 1.0. To move data from a 0.117 container to 1.0, export it with mongodump, start a 1.0 container on a new volume, and load it with mongorestore. The PostgreSQL major version of the image must also match the one that initialized the volume.

If you do start a 1.0 image on a volume an older container used, the 1.0 image refuses to start while the old container's postmaster.pid is still there; see Container lifecycle for the override and removing it afterward. For 0.116 and 0.117, stop the old container with docker stop first, which removes the file; after docker kill, docker rm -f or a crash it stays. Images 0.114 and earlier don't normally stop PostgreSQL cleanly, so their volumes usually keep the file.

Feature support

Please refer to the documentdb documentation for currently supported features.

Installing certificates

If you do not supply your own certificate with --cert-path and --key-file, DocumentDB Local generates a self-signed certificate on first start and reuses it on subsequent starts of the same container, so docker stop / docker start keeps it stable. Removing and re-creating the container generates a new certificate unless you persist the directory it is stored in. The generated certificate is valid for 365 days and is not renewed automatically - re-create the container, or delete cert.pem from the state directory shown below, to generate a fresh one.

To validate the certificate instead of skipping validation with tlsAllowInvalidCertificates=true, copy it out of the container and point mongosh at it.

Get certificate

The gateway picks its TLS state directory from the first writable candidate. In this image that resolves to a path under the container user's home directory, so no extra options are needed when starting the container. In a bash window, copy the certificate from the container to the local host:

docker cp docdb:/home/documentdb/.local/state/documentdb-gateway/tls/cert.pem ~/documentdb-cert.pem

The gateway logs the path it actually chose on startup. Check there first if the copy reports No such container:path:

docker logs docdb | grep "TLS auto-gen"

To keep the same certificate across re-creating the container, pin the location with DOCUMENTDB_TLS_STATE_DIR and put it inside the data volume. This replaces the container you started earlier, so run docker rm -f docdb first:

docker run -dt \
  -p 127.0.0.1:10260:10260 \
  -v documentdb-data:/data \
  -e DOCUMENTDB_TLS_STATE_DIR=/data/tls \
  --name docdb \
  -e USERNAME="${DOCUMENTDB_USERNAME:?Set DOCUMENTDB_USERNAME first}" \
  -e PASSWORD="${DOCUMENTDB_PASSWORD:?Set DOCUMENTDB_PASSWORD first}" \
  ghcr.io/documentdb/documentdb/documentdb-local:pg17-1.0.0

Point it inside the data directory rather than at a volume of its own: a separate volume is created root-owned, and the gateway - which runs as an unprivileged user - cannot write its key there. The trade-off is that the key is included in any backup of the data volume. If the entrypoint ever has to repair the data directory's ownership (it does when the owner doesn't match, or with DOCUMENTDB_FORCE_OWNERSHIP_REPAIR=true), it runs chmod -R 750 over the directory, which leaves the private key group-readable rather than owner-only.

Use the certificate with mongosh

mongosh localhost:10260 \
  -u "${DOCUMENTDB_USERNAME:?Set DOCUMENTDB_USERNAME first}" \
  -p \
  --authenticationMechanism SCRAM-SHA-256 \
  --tls --tlsCAFile ~/documentdb-cert.pem

Current Mongosh Log ID:	690ce1171181053c6edbf354
Connecting to:		mongodb://<credentials>@localhost:10260/?directConnection=true&serverSelectionTimeoutMS=2000&authMechanism=SCRAM-SHA-256&tls=true&tlsCAFile=%2Fhome%2Fuser%2Fdocumentdb-cert.pem&appName=mongosh+2.5.1
Using MongoDB:		7.0.0
Using Mongosh:		2.5.1
mongosh 2.5.9 is available for download: https://www.mongodb.com/try/download/shell

For mongosh info see: https://www.mongodb.com/docs/mongodb-shell/

[direct: mongos] test>

Beyond local development

DocumentDB Local runs a single container on one machine, with no replication and no failover, which is what makes it convenient for development and testing. For other ways to run DocumentDB:

• Kubernetes Operator - run DocumentDB as a replicated service, with automatic failover, backup and restore, and rolling upgrades.
• Pre-built packages - add the DocumentDB extension to a PostgreSQL server you already run.

Reporting issues

If you encounter issues with using this version of DocumentDB, open an issue in the GitHub repository (https://github.com/documentdb/documentdb/issues) and tag it with the label documentdb-local.