DocumentDB Local

Prerequisites

• Docker

Installation

Get the Docker container image using docker pull.

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

Running

To run the container, use docker run. Afterwards, use docker ps to validate that the container is running.

read -r -p 'DocumentDB username: ' DOCUMENTDB_USERNAME
read -r -s -p 'DocumentDB password: ' DOCUMENTDB_PASSWORD
printf '\n'
export DOCUMENTDB_USERNAME DOCUMENTDB_PASSWORD

docker run -dt -p 127.0.0.1:10260:10260 --name docdb \
  ghcr.io/documentdb/documentdb/documentdb-local:pg17-0.117.0 \
  --username "${DOCUMENTDB_USERNAME:?DocumentDB username cannot be empty}" \
  --password "${DOCUMENTDB_PASSWORD:?DocumentDB password cannot be empty}"


docker ps

CONTAINER ID   IMAGE                                                                             COMMAND                  CREATED         STATUS         PORTS                              NAMES
5aff734a3591   ghcr.io/documentdb/documentdb/documentdb-local:pg17-0.117.0                        "/bin/bash -c '/home…"   5 seconds ago   Up 4 seconds   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 "${DOCUMENTDB_PASSWORD:?Set DOCUMENTDB_PASSWORD first}" \
  --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 \
  ghcr.io/documentdb/documentdb/documentdb-local:pg17-0.117.0 \
  --username "${DOCUMENTDB_USERNAME:?Set DOCUMENTDB_USERNAME first}" \
  --password "${DOCUMENTDB_PASSWORD:?Set DOCUMENTDB_PASSWORD first}" \
  --init-data true

Built-in sample data

Release 0.117 replaces the earlier small sampledb seed with the complete StoreData dataset. Loading remains opt-in: add --init-data true to the container arguments, as in the example above.

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 remains one-shot per data volume. Previously seeded volumes are not automatically migrated to StoreData; use a new, empty volume when you want the new sample dataset. A direct loader rerun tolerates duplicate keys rather than duplicating documents. See the versioned sample-data guide for manual loader instructions.

Container image tags

The latest tag is a convenience alias. Pin an explicit tag for anything reproducible:

Every image records what it was built from:

docker run --rm --entrypoint cat ghcr.io/documentdb/documentdb/documentdb-local:pg18-0.117.0 /version.txt

Data initialization

DocumentDB Local starts empty. Pass --init-data true to seed the StoreData database with the stores and ratings collections:

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

Seeding happens once per data volume, on a fresh volume. Existing volumes are not migrated automatically; re-create the volume to seed again.

Control initialization behavior

The built-in sample dataset currently includes 41,505 store documents and 2 rating documents.

Use custom initialization scripts

docker run -dt --name documentdb \
  -p 127.0.0.1:10260:10260 \
  -v /path/to/init/scripts:/init_doc_db.d \
  ghcr.io/documentdb/documentdb/documentdb-local:latest \
  --username '<YOUR_USERNAME>' \
  --password '<YOUR_PASSWORD>' \
  --init-data-path /init_doc_db.d

When --init-data-path is provided, DocumentDB Local skips the built-in sample data and runs only the scripts you mounted.

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 \
  ghcr.io/documentdb/documentdb/documentdb-local:pg17-0.117.0 \
  --username "${DOCUMENTDB_USERNAME:?Set DOCUMENTDB_USERNAME first}" \
  --password "${DOCUMENTDB_PASSWORD:?Set DOCUMENTDB_PASSWORD first}"

Point it inside the data directory rather than at a volume of its own: the entrypoint takes ownership of the data directory on every start, whereas 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 same step runs chmod -R 750 over that directory, so from the second start onwards the private key is group-readable rather than owner-only, and it is included in any backup of the data volume.

Use the certificate with mongosh

mongosh localhost:10260 \
  -u "${DOCUMENTDB_USERNAME:?Set DOCUMENTDB_USERNAME first}" \
  -p "${DOCUMENTDB_PASSWORD:?Set DOCUMENTDB_PASSWORD first}" \
  --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.