Join us at MongoDB.local London on 7 May to unlock new possibilities for your data. Use WEB50 to save 50%.
Register now >
Docs Menu
Docs Home
/ /
Local & Cloud Deployments
Docs Home
/ /
Manage Atlas
/
Local & Cloud Deployments
Docs Home
/
Tools
/
Atlas CLI
/
Manage Atlas
/
Local & Cloud Deployments

Create a Local Atlas Deployment

This tutorial shows you how to use the atlas deployments command to create a local Atlas deployment. In this tutorial, we will deploy a single-node replica set on your local computer. You can then manage your deployment, and use Atlas Search and Atlas Vector Search.

Supported OS for Local Atlas Deployments

Operating System
Operating System Version
Architecture
Minimum CPU Cores
Minimum Free RAM (GB)

MacOS

13.2 and later

x86-64, ARM

2

2

Red Hat Enterprise Linux / CentOS

8, 9

x86-64, ARM

2

2

Ubuntu

22.04, 24.04

x86-64, ARM

2

2

Debian

11, 12

x86-64, ARM

2

2

Amazon Linux

2023

x86-64, ARM

2

2

Windows

10, 11

x86

2

2

Complete the Prerequisites

Before you begin, complete the following prerequisites:

Important

For compatibility information on each product in the dependencies list, see the product's installation documentation.

1

Install the dependencies.

  1. Install the Atlas CLI.

    If you use Homebrew, you can run the following command in your terminal:

    brew install mongodb-atlas-cli

    For installation instructions on other operating systems, see Install or Update the Atlas CLI.

  2. Install Docker.

    Docker requires a network connection for pulling and caching MongoDB images.

  3. (Optional) Install mongosh version 2.0 or later.

    brew install mongosh

    For installation instructions on other operating systems, see Install mongosh.

  4. (Optional) Install Compass version 1.39.4 or later.

    brew install mongodb-compass

    For installation instructions on other operating systems, see Download and Install Compass.

  5. (Optional) Install Visual Studio Code and MongoDB for VS Code Extension.

    To learn more, see Install MongoDB for VS Code Extension.

2

Create an Atlas account.

If you don't already have an existing Atlas account, run atlas setup in your terminal or create a new account.

Create a Local Atlas Deployment

Use the atlas deployments command to create a local Atlas deployment.

You can run this command in the following ways:

  • Interactive Mode (Default): the command prompts you for the deployment settings and provides default values.

  • Interactive Mode (Custom): the command prompts you for the deployment settings and lets you provide custom values.

  • Non-Interactive Mode: you run the command with the specified options. The command does not prompt you to provide further values. To learn all of the actions that atlas deployments supports, see atlas-deployments.

Click one of the following tabs to see the command for your preferred mode.

1

Run the atlas deployments command in interactive mode.

atlas deployments setup

To initialize the local Atlas deployment with your own data and indexes:

  1. Copy the following command:

    atlas deployments setup --initdb {folder}

  2. Replace the {folder} placeholder with the directory that contains the .js and .sh files to run inside the local container in alphanumeric order.

  3. Run the command.

2

Specify what to deploy.

Example:

Specify local - Local Database and press Enter..

? What would you like to deploy?  [Use arrows to move, type to filter, ? for more help]
> local - Local Database
  atlas - Atlas Database
[Default Settings]
Deployment Name   local50
MongoDB Version   7.0
Port              27017
3

Specify how to set up your local Atlas database.

Example:

Specify default - With default settings and press Enter..

? How do you want to setup your local MongoDB database?  [Use arrows to move, type to filter]
> default - With default settings
  custom - With custom settings
  cancel - Cancel set up
Creating your deployment local50 [this might take several minutes]
1/4: Downloading and completing configuration...
2/4: Starting your local environment...
3/4: Downloading MongoDB binaries to your local environment...
4/4: Creating your deployment local50...
Deployment created!
Connection string: mongodb://localhost:27017/?directConnection=true
1

Run the atlas deployments command in interactive mode.

atlas deployments setup

To initialize the local Atlas deployment with your own data and indexes:

  1. Copy the following command:

    atlas deployments setup --initdb {folder}

  2. Replace the {folder} placeholder with the directory that contains the .js and .sh files to run inside the local container in alphanumeric order.

  3. Run the command.

2

Specify what to deploy.

Specify local - Local Database and press Enter..

Example:

? What would you like to deploy?  [Use arrows to move, type to filter, ? for more help]
> local - Local Database
  atlas - Atlas Database
[Default Settings]
Deployment Name   local50
MongoDB Version   7.0
Port              27017
3

Specify how to set up your local Atlas database.

Example:

Specify custom - With custom settings and press Enter..

? How do you want to setup your local MongoDB database?  [Use arrows to move, type to filter]
  default - With default settings
> custom - With custom settings
  cancel - Cancel set up
4

Specify a deployment name.

Example:

Specify myLocalRs and press Enter..

? Deployment Name [This can't be changed later] (local3612) myLocalRs
5

Specify a MongoDB Version.

Example:

Specify 7.0 and press Enter..

? MongoDB Version  [Use arrows to move, type to filter]
> 7.0
  6.0
6

Specify a port.

Example:

Specify 37018 and press Enter..

? Specify a port (49469) 37018
Creating your deployment myLocalRs
1/2: Starting your local environment...
2/2: Creating your deployment myLocalRs...
Deployment created!
Connection string: mongodb://localhost:37018/?directConnection=true
1

Run the atlas deployments command with the options.

Example:

atlas deployments setup myLocalRs1 --type local --force
[Default Settings]
Deployment Name      myLocalRs1
MongoDB Version   7.0
Port              49684
Creating your deployment myLocalRs1
1/2: Starting your local environment...
2/2: Creating your deployment myLocalRs1...
Deployment created!
Connection string: mongodb://localhost:49684/?directConnection=true
connection skipped

To initialize the local Atlas deployment with your own data and indexes:

  1. Copy the following command:

    atlas deployments setup myLocalRs1 --type local --force --initdb {folder}

  2. Replace the {folder} placeholder with the directory that contains the .js and .sh files to run inside the local container in alphanumeric order.

  3. Run the command.

Manage a Local Atlas Deployment

Use the atlas deployments command to manage a local Atlas deployment. You can use the following commands for both local and cloud Atlas deployments. You can use --type local or --type atlas to run the command for local or cloud atlas deployments respectively.

1

List the available deployments.

Example:

atlas deployments list
NAME        TYPE    MDB VER   STATE
local50     LOCAL   7.0.1     IDLE
local62     LOCAL   7.0.1     IDLE
myLocalRs   LOCAL   7.0.1     IDLE
myLocalRs1  LOCAL   7.0.1     IDLE
2

Download and load the sample data.

  1. Run the following command to download the sample data:

    curl  https://atlas-education.s3.amazonaws.com/sampledata.archive -o sampledata.archive

  2. Copy and paste the following command into your terminal and replace {port-number} with the port for your deployment:

    mongorestore --archive=sampledata.archive --port={port-number}
3

Connect to a deployment.

  1. Run the following command to connect to a deployment:

    atlas deployments connect

  2. Specify the deployment to connect to and press Enter..

  3. Specify how you want to connect to the deployment and press Enter..

    You can retrieve the connection string or connect to the following clients: connection string:

4

Pause a deployment.

  1. Run the following command to pause a deployment:

    atlas deployments pause

  2. Specify the deployment to pause and press Enter..

5

Start a deployment

  1. Run the following command to start a deployment:

    atlas deployments start

  2. Specify the deployment to start and press Enter..

6

Return the logs for the deployment.

  1. Run the following command to return the logs for a deployment:

    atlas deployments logs

  2. Specify the deployment to return logs for and press Enter..

Delete an Atlas Deployment

  1. Run the following command to delete a deployment:

    atlas deployments delete

  2. Specify the deployment to delete and press Enter..

  3. Specify y and press Enter. to confirm.

Move a Local Atlas Deployment to a Cloud Atlas Deployment

You can use Docker and MongoDB Database Tools to move a local Atlas deployment to a cloud Atlas deployment.

1

Create a cloud Atlas deployment.

atlas deployments setup --type atlas
2

Create a local Atlas deployment.

atlas deployments setup --type local

To initialize the local Atlas deployment with your own data and indexes:

  1. Copy the following command:

    atlas deployments setup --type local --initdb {folder}

  2. Replace the {folder} placeholder with the directory that contains the .js and .sh files to run inside the local container in alphanumeric order.

  3. Run the command.

3

Create a binary file of the data.

  1. Copy the following command:

    docker exec -u root -it {local_deployment_name} sh -c "mkdir -p /data/dump && chown -R mongod:mongod /data/dump && mongodump --archive=/data/dump/dump.archive"

  2. Replace the {local-deployment-name} placeholder with the name of your local Atlas deployment.

  3. Run the command.

4

Copy the archive.

  1. Copy the following command:

    docker cp <local deployment name>:/data/dump/dump.archive .

  2. Replace the {local-deployment-name} placeholder with the name of your local Atlas deployment.

  3. Run the command.

5

Return the connection string.

atlas deployments connect --type atlas --connectWith connectionString
6

Restore from the archived file.

  1. Copy the following command:

    mongorestore --uri={connection-string} --archive=./dump.archive

  2. Replace the {connection-string} placeholder with the connection string.

  3. Run the command.

7

(Optional) Delete the local Atlas deployment.

atlas deployments delete --type local

Update a Local Atlas Deployment

You can use Docker and MongoDB Database Tools to update a local Atlas deployment to a newer version of the image.

1

Create a new local Atlas deployment.

atlas deployments setup --type local

To initialize the local Atlas deployment with your own data and indexes:

  1. Copy the following command:

    atlas deployments setup --type local --initdb {folder}

  2. Replace the {folder} placeholder with the directory that contains the .js and .sh files to run inside the local container in alphanumeric order.

  3. Run the command.

2

Create a binary file of the data.

  1. Copy the following command:

    docker exec -u root -it {old-local-deployment-name} sh -c "mkdir -p /data/dump && chown -R mongod:mongod /data/dump && mongodump --archive=/data/dump/dump.archive"

  2. Replace the {old-local-deployment-name} placeholder with the name of your old local Atlas deployment.

  3. Run the command.

3

Copy the archive.

  1. Copy the following command:

    docker cp {old-local-deployment-name}:/data/dump/dump.archive .

  2. Replace the {old-local-deployment-name} placeholder with the name of your old local Atlas deployment.

  3. Run the command.

4

Return the new connection string.

atlas deployments connect --type local --connectWith connectionString
5

Restore from the archived file.

  1. Copy the following command:

    mongorestore --uri={connection-string} --archive=./dump.archive

  2. Replace the {connection-string} placeholder with the connection sring.

  3. Run the command.

6

(Optional) Delete the old local Atlas deployment.

atlas deployments delete --type local

Use Atlas Search with a Local Atlas Deployment

Use the atlas deployments search indexes create command to create an Atlas Search search index. You can then run Atlas Search queries. To learn more, see Atlas Search.

You can run this command with local and cloud Atlas deployments. For detailed steps, see Create an Atlas Search Index and Run a Query.

Use Atlas Vector Search with a Local Atlas Deployment

Use the atlas deployments search indexes create command to work with Atlas Vector Search. To learn more, see How to Index Vector Embeddings for Vector Search.

You can run this command with local and cloud Atlas deployments. For detailed steps, see Use Atlas Vector Search with an Atlas Deployment.

Important

To use the Atlas CLI with Atlas Vector Search, you must create an Atlas deployment with MongoDB 7.0.5 or later. If you created a local Atlas deployment with an earlier MongoDB version, you don't get the latest MongoDB version automatically. You must delete the earlier images and deployments. Then you must create a new Atlas deployment.

Use Preview Features with a Local Atlas Deployment

The preview version of MongoDB Atlas Local includes support for Atlas Vector Search Automated Embedding and other advanced Atlas Search community features. To use these features, set the MONGODB_ATLAS_LOCAL_PREVIEW environment variable to true before creating your local deployment.

Important

The preview image is intended for testing and development purposes. Preview features might change at any time during the Preview period. To learn more, see Preview Features.

Prerequisites

Before you use preview features with a local Atlas deployment, complete the following prerequisites:

  • Obtain a Voyage AI API key for Atlas Vector Search Automated Embedding features. To learn more, see API Keys in the Voyage AI documentation.

  • Complete all prerequisites in Complete the Prerequisites.

Enable Preview Features

To enable preview features in your local deployment:

1

Set the required environment variables.

Set the MONGODB_ATLAS_LOCAL_PREVIEW environment variable to true and provide your Voyage AI API key:

export MONGODB_ATLAS_LOCAL_PREVIEW=true
export MONGODB_ATLAS_LOCAL_VOYAGE_API_KEY=<your-voyage-api-key>
$env:MONGODB_ATLAS_LOCAL_PREVIEW="true"
$env:MONGODB_ATLAS_LOCAL_VOYAGE_API_KEY="<your-voyage-api-key>"
set MONGODB_ATLAS_LOCAL_PREVIEW=true
set MONGODB_ATLAS_LOCAL_VOYAGE_API_KEY=<your-voyage-api-key>

Replace <your-voyage-api-key> with your actual Voyage AI API key.

2

Create a local deployment.

Run the atlas local setup command to create a local deployment with preview features enabled:

atlas local setup

The Atlas CLI uses the preview tag of the mongodb/mongodb-atlas-local Docker image when the MONGODB_ATLAS_LOCAL_PREVIEW environment variable is set to true.

3

Use Atlas Vector Search Automated Embedding features.

After your deployment is created, you can use Atlas Vector Search Automated Embedding features to automatically generate embeddings using the specified Voyage AI model for your text at index-time and query-time. To learn more, see Create Embeddings Automatically.

To learn more about the environment variables, see Atlas CLI Environment Variables.

Supported Actions

To learn all of the actions that atlas deployments supports, see atlas-deployments.

Troubleshoot Errors

To learn more about troubleshooting local Atlas deployment issues, see Troubleshoot Local Atlas Deployment Issues.

Back

Local & Cloud Deployments

Next

Deploy with Docker

On this page