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

Important

The atlas deployments commands are deprecated as of Atlas CLI version 1.52.0. Use atlas local commands instead. We updated this tutorial to use the atlas local command.

This tutorial shows you how to use the atlas local 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 MongoDB Search and MongoDB 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 local 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 local supports, see atlas-local.

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

1

Run the atlas local command in interactive mode.

atlas local setup

To load MongoDB sample data during setup:

  1. Run the following command:

    atlas local setup --loadSampleData true

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

  1. Copy the following command:

    atlas local 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 local command in interactive mode.

atlas local setup

To load MongoDB sample data during setup:

  1. Run the following command:

    atlas local setup --loadSampleData true

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

  1. Copy the following command:

    atlas local 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 local command with the options.

Example:

atlas local setup myLocalRs1 --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 local setup myLocalRs1 --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 local command to manage a local Atlas deployment.

1

List the available deployments.

Example:

atlas local 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

Load sample data.

Note

You can also load sample data during deployment setup using the --loadSampleData true option with atlas local setup. See the setup examples above.

To load sample data into an existing deployment:

  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 local 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 local stop

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

5

Start a deployment

  1. Run the following command to start a deployment:

    atlas local 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 local 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 local 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 setup
2

Create a local Atlas deployment.

atlas local setup

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

  1. Copy the following command:

    atlas local 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.

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 clusters connectionStrings describe
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 local delete

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 local setup

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

  1. Copy the following command:

    atlas local 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

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 local connect --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 local delete

Use MongoDB Search with a Local Atlas Deployment

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

For detailed steps, see Create a MongoDB Search Index and Run a Query.

Use MongoDB Vector Search with a Local Atlas Deployment

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

For detailed steps, see Use MongoDB Vector Search with an Atlas Deployment.

Important

To use the Atlas CLI with MongoDB 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.

Supported Actions

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

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