mongodb/mongodb-atlas-local repository overview

⁠mongodb/mongodb-atlas-local

Create, manage, and automate MongoDB Atlas Local resources with Docker

⁠Table of Contents

• Repository Overview⁠
• Quickstart⁠
  • Alternative deployment methods⁠
    • Atlas CLI⁠
    • MongoDB MCP Server⁠
    • Docker Compose⁠
  • Image Tags⁠
  • Migration Guide: 8.x to 9.x⁠
• Authentication⁠
• Seeding⁠
• Sample Data⁠
• Logs⁠
• Healthcheck⁠
• MongoDB Search Community⁠
• Telemetry⁠
• Licensing⁠
• Documentation⁠
• Current experimental features⁠

⁠Repository Overview

This is the Docker image for the MongoDB Atlas Local experience. MongoDB Atlas Local provides a full deployment of both MongoDB (mongod) and MongoDB Search (mongot) as a single node replica set, so you can build applications with MongoDB, and make use of features like Atlas Search⁠ and Atlas Vector Search⁠ straight away, and throughout the entire software development lifecycle.

⁠Quickstart

1. Pull the Docker image

docker pull mongodb/mongodb-atlas-local

1. Run the database

docker run -p 27017:27017 --name atlas-local mongodb/mongodb-atlas-local

1. Wait until the container is healthy, then connect to the database

mongosh "mongodb://localhost/?directConnection=true"

⁠Alternative deployment methods

⁠Atlas CLI

The Atlas CLI provides a guided setup that can also be used in programmatic workflows. Follow these instructions to Create a Local Atlas deployment using the Atlas CLI⁠.

⁠MongoDB MCP Server

The MongoDB MCP Server⁠ provides Model Context Protocol tools that let you interact with Atlas Local deployments from MCP-enabled clients such as VS Code, Cursor, and Claude Desktop. Follow this guide to Get Started with the MongoDB MCP Server⁠.

⁠Docker Compose

Docker Compose offers a repeatable way for other contributors to set up full MongoDB environments in a reliable way (including healthchecks and initializing with data). Follow the Complete Guide to Deploying MongoDB Atlas Local with Docker Compose⁠ available from the official MongoDB documentation.

⁠Image Tags

⁠Supported versions

Common supported tags:

• latest tracks the latest stable release of MongoDB.
• preview tracks the latest stable release of MongoDB, but with new experimental features.
• 9.0 tracks the latest 9.0 version of MongoDB.
• 8.3 tracks the latest 8.3 version of MongoDB.
• 8.0 tracks the latest 8.0 version of MongoDB.
• 7.0 tracks the latest 7.0 version of MongoDB.

⁠Specific MongoDB builds

To pin a specific version of MongoDB, we provide tags for every build, with tags formatted as <major>.<minor>.<patch>-<timestamp>, for example: 8.0.17-20260218T161908Z. You can view all available tags here⁠.

⁠Preview builds

The preview tag makes new experimental features available in Atlas Local.

Currently, preview and latest are in line: both point to MongoDB 9.0.4 and use MongoDB Search Community (mongot). See Current experimental features⁠ for details.

⁠Migration Guide: 8.x to 9.x

MongoDB 9.0 images change both the MongoDB server version and the Search backend.

Before switching an existing workflow:

• Pin mongodb/mongodb-atlas-local:8.3 or an exact 8.x patch tag until you are ready to test 9.0.
• Test with mongodb/mongodb-atlas-local:9.0 or an exact 9.0.x patch tag before returning to latest.
• Run Search smoke tests that create, list, and query search and vector indexes, especially if tests assert on $listSearchIndexes.
• If you use auto-embedding, set VOYAGE_API_KEY and, if needed, EMBEDDING_PROVIDER_ENDPOINT.
• Use a fresh Docker volume or back up the existing one before starting a 9.0 container with data created by an 8.x container. Do not assume that a volume started by MongoDB 9.0 can be reused by MongoDB 8.x.

⁠Authentication

To set up authentication for your local deployment, specify the following environment variables:

• MONGODB_INITDB_ROOT_USERNAME: The username for the root user.
• MONGODB_INITDB_ROOT_PASSWORD: The password for the root user.

You may also set it via filename mappings for an extra layer of security. Specify the following environment variables:

• MONGODB_INITDB_ROOT_USERNAME_FILE: The path to the file containing the username for the root user.
• MONGODB_INITDB_ROOT_PASSWORD_FILE: The path to the file containing the password for the root user.

⁠Seeding

Map a volume to /docker-entrypoint-initdb.d containing .sh or .js files, they will be executed in alphabetical order.

The default db connected will be test unless the environment variable MONGODB_INITDB_DATABASE is set.

You can use $CONNECTION_STRING as the URI for connecting to databases in your init scripts, as it holds the default connection string for the database.

⁠Sample Data

To automatically load the MongoDB sample dataset during initialization, set the MONGODB_LOAD_SAMPLE_DATA environment variable to true.

The sample dataset (~400MB) is downloaded from the internet during initialization. The download is capped at a 10 minute timeout; on slow connections, raise it with the MONGODB_SAMPLE_DATA_DOWNLOAD_TIMEOUT environment variable (a duration string, e.g. 15m).

⁠Logs

By default we only redirect mongod logs to stdout and stderr. You can set the extra environment variables to enable more logging:

• MONGOT_LOG_FILE: The path to the file where you want to store the logs of Atlas Search (mongot).
• RUNNER_LOG_FILE: The path to the file where you want to store the logs of runner.

Note: both of these variables can be set to /dev/stdout or /dev/stderr for convenience.

⁠Healthcheck

The image automatically runs a healthcheck every 30s to verify that mongod and mongot are healthy and that seeding scripts have successfully completed.

To programmatically wait for a healthy status of the container:

• Using bash, run

while [ "`docker inspect -f {{.State.Health.Status}} atlas-local`" != "healthy" ]; do sleep 2; done

• Using Docker Compose, add the following to your compose.yml

depends_on:
  atlas-local
    condition: service_healthy

⁠MongoDB Search Community

MongoDB 9.0+ images use MongoDB Search Community (mongot)⁠. MongoDB 8.x stable images continue to use local-dev mongot.

MongoDB Search Community (mongot) enables auto-embedding for vector indexes. See Create Vector Embeddings Automatically⁠ for more information. Provide your Voyage API key with the VOYAGE_API_KEY environment variable.

When using MongoDB Search Community (mongot):

• MongoDB Search Community (mongot) may return different $listSearchIndexes output than local-dev mongot. If your tests assert on index metadata, compare the output before switching.
• Atlas Local uses the default endpoint, https://ai.mongodb.com/v1/embeddings, for Atlas-provisioned Voyage API keys. See Model API Keys⁠ for more information on provisioning API keys.
  • For Voyage AI-provisioned keys, set EMBEDDING_PROVIDER_ENDPOINT=https://api.voyageai.com/v1/embeddings:

    -e EMBEDDING_PROVIDER_ENDPOINT=https://api.voyageai.com/v1/embeddings
    

    Copy
• You may see HTTP 429 responses on lower AI Model tiers. See Manage Rate Limits⁠ to learn more about rate limiting and AI Model tiers.

⁠Telemetry

This image collects anonymous telemetry data to help us improve the product and to provide you with a better user experience. The data collected includes:

• Container lifecycle events: startup/shutdown timing, authentication status, seeding results
• Index usage: counts of search and vector indexes created and used
• Database activity: CRUD operation counts, database uptime, total database size
• Client information: anonymized driver versions, operating systems, and application names (limited to MongoDB official tools like Compass and mongosh)

All telemetry is associated with an anonymous deployment UUID. No customer data, database names, or personally identifiable information is collected.

You can opt out of telemetry by setting the DO_NOT_TRACK environment variable to 1. For example:

docker run -e DO_NOT_TRACK=1 -p 27017:27017 --name atlas-local mongodb/mongodb-atlas-local

⁠Licensing

The specific licenses depend on which Atlas Local image is used. To check the license of a currently running Atlas Local instance, run the following commands:

• List all the licenses
  • docker exec atlas-local ls -Rp /usr/share/licenses/mongodb/
• Print the license text
  • docker exec atlas-local cat /usr/share/licenses/mongodb/LICENSE.txt
  • docker exec atlas-local cat /usr/share/licenses/mongodb/mongot/LICENSE.txt
  • docker exec atlas-local cat /usr/share/licenses/mongodb/server/LICENSE-Community.txt
  • docker exec atlas-local cat /usr/share/licenses/mongodb/runner/LICENSE.txt

⁠Documentation

For more information, see Create a Local Atlas Deployment with Docker⁠.

⁠Current experimental features

Currently, preview and latest are aligned: both point to MongoDB 9.0.4 and use MongoDB Search Community (mongot). If preview diverges again later, this section is where we should call out the experimental behavior.