Docker Quick Start

Run DocumentDB locally with Docker and verify the setup before moving to driver code.

Prerequisites

Docker
mongosh for the fastest connection check
A local port available for DocumentDB (the examples use 10260)

Start DocumentDB

If you do not already have the image locally, pull it first:

docker pull ghcr.io/documentdb/documentdb/documentdb-local:latest

Then start the container:

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

Replace <YOUR_USERNAME> and <YOUR_PASSWORD> with your own credentials.

-p 127.0.0.1:10260:10260 keeps the endpoint on loopback. A bare -p 10260:10260 publishes it on every interface, which is rarely what you want on a laptop.

--init-data true seeds the built-in sample data into StoreData, which the verification step below queries. It is not enabled by default — without it the container starts with no StoreData database and use StoreData returns nothing. The data is seeded once per data volume. Existing volumes are not migrated automatically; re-create the volume to seed again. See DocumentDB Local for --init-data-path, certificate setup, and additional runtime options.

Verify the container

docker ps --filter "name=documentdb"

You should see the container in an Up state with port 10260 published.

Important

docker ps reports Up well before DocumentDB accepts connections. Wait for the readiness banner, or the first mongosh call fails with a connection error:

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

Verify the connection

Use mongosh to confirm authentication, TLS, and the gateway endpoint are working:

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

Then run a quick health check. The sample data below needs --init-data true on the docker run above — without it StoreData does not exist:

db.runCommand({ ping: 1 })

use StoreData

db.stores.find({}, { _id: 0, name: 1, city: 1, "sales.revenue": 1 }).limit(3)

If you prefer certificate validation instead of --tlsAllowInvalidCertificates, follow the certificate steps in DocumentDB Local.

Persistence and initialization

The quick start command above is ideal for disposable local environments. When you need more control:

Use --data-path with a mounted host directory to keep data across container restarts
Omit --init-data true if you want an empty instance instead of the StoreData collections
Use --init-data-path to run your own .js initialization scripts with mongosh at startup

The built-in StoreData sample dataset includes 41,505 documents in stores and 2 documents in ratings.

Stop, start, and remove

docker stop documentdb       # stop, keep the data
docker start documentdb      # bring it back later
docker restart documentdb
docker logs documentdb       # gateway and startup output

To update the image or start over:

# DESTROYS the container and its anonymous data volume
docker rm -fv documentdb
docker pull ghcr.io/documentdb/documentdb/documentdb-local:latest
# then run the Start DocumentDB command again

Until you remove it, re-running docker run --name documentdb fails with Conflict. The container name "/documentdb" is already in use. Mount a named volume (-v documentdb-data:/data) before storing anything you want to keep.

Troubleshooting and debugging

If something does not work as expected:

Confirm port 10260 is available and that docker ps shows the container running
Inspect startup, authentication, and TLS errors with docker logs documentdb
For more gateway detail, re-create the container with -e DOCUMENTDB_LOG_LEVEL=debug. The --log-level flag is validated at startup but does not currently change what the container logs, and environment variables are fixed at docker run — docker restart cannot change either.
Use the certificate flow in DocumentDB Local if your client should validate TLS certificates
Use Mongo Shell Quick Start for a fuller shell walkthrough