Getting Started

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 10260:10260 \
  ghcr.io/documentdb/documentdb/documentdb-local:latest \
  --username <YOUR_USERNAME> \
  --password <YOUR_PASSWORD>

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

DocumentDB Local loads built-in sample data into sampledb by default. See DocumentDB Local for --skip-init-data, --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.

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 and inspect the built-in sample data:

db.runCommand({ ping: 1 })

use sampledb

db.users.find({}, { name: 1, email: 1, _id: 0 }).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
Use --skip-init-data if you want an empty instance instead of the default sampledb collections
Use --init-data-path to run your own .js initialization scripts with mongosh at startup

The built-in sample dataset includes users, products, orders, and analytics collections in sampledb.

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
Restart the container with --log-level debug for more verbose local diagnostics
Use the certificate flow in DocumentDB Local if your client should validate TLS certificates
Use Mongo Shell Quick Start for a fuller shell walkthrough