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⁠
• Authentication⁠
• Seeding⁠
• Sample Data⁠
• Logs⁠
• Healthcheck⁠
• Telemetry⁠
• Image Tags⁠
• Licensing⁠
• Documentation⁠

⁠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

There are four fundamental supported tags:

• latest tracks the latest stable release of MongoDB
• preview tracks the latest stable release of MongoDB, but with new experimental features
• 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.

⁠Current experimental features

• Use of MongoDB Search in Community⁠ image
  • This edition of MongoDB Search (mongot) enables use of auto-embedding, utilizing AI to automatically embed your vector indexes. See here for more information on Auto-embedding⁠.
  • Provide your Voyage API key through the environment variable VOYAGE_API_KEY.

The following should be considered when using this image:

• MongoDB Search in Community image is in preview and may change at any time during the preview period.
  • Additionally, the $listSearchIndexes aggregation stage is not complete.
• Currently, the only supported embedding provider endpoint is ai.mongodb.com.
  • Your voyage API key must be provisioned via the Atlas UI. See Model API Keys⁠ for more information on provisioning API keys.
• You may see rate limiting (429) on lower AI Model tiers.
  • See Manage Rate Limits⁠ to learn more about rate limiting and AI Model tiers.

⁠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.

⁠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

⁠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⁠.