Docs Menu
Docs Home
/
MongoDB Atlas
/
Atlas CLI
/
Manage Atlas
/
Local & Cloud Deployments

Create a Local Atlas Deployment with Docker

On this page

  • Create a Local Atlas Deployment with Docker
  • Create a Local Atlas Deployment with Docker Compose
  • Persist Data Across Runs with Docker Compose
  • Generate a List of Dependencies
  • Verify the Image Signature
  • Run the Image with GitHub Actions
  • Convert Official Image to a Local Atlas Deployment

This tutorial shows you how to create a local Atlas deployment with Docker. In this tutorial, we will deploy a single-node replica set with Docker.

Create a Local Atlas Deployment with Docker

1

Install and start Docker.

To learn more, see the Docker documentation.

2

Pull down the mongodb/mongodb-atlas-local Docker image.

Example:

docker pull mongodb/mongodb-atlas-local:latest
3

Run the Docker image.

Example:

docker run -p 27017:27017 mongodb/mongodb-atlas-local
docker run -e MONGODB_INITDB_ROOT_USERNAME=user -e MONGODB_INITDB_ROOT_PASSWORD=pass -p 27017:27017 mongodb/mongodb-atlas-local

To automate a containerized deployment of Atlas, you'll need to wait for the container to be in a healthy state before you can connect to Atlas.

The following example demonstrates deploying an Atlas image in Docker and polling Docker to check the state of the container. Once the container is in a healthy state, the script automates a connection to your Atlas instance with Mongosh.

  1. Create a file called mongodb-atlas-local.sh, and paste the following script into your new file.

    # Start mongodb-atlas-local container
    echo "Starting the container"
    CONTAINER_ID=$(docker run --rm -d -P mongodb/mongodb-atlas-local:latest)
    echo "waiting for container to become healthy..."
    function wait() {
    CONTAINER_ID=$1
    echo "waiting for container to become healthy..."
    for _ in $(seq 120); do
          STATE=$(docker inspect -f '{{ .State.Health.Status }}' "$CONTAINER_ID")
          case $STATE in
          healthy)
             echo "container is healthy"
             return 0
             ;;
          unhealthy)
             echo "container is unhealthy"
             docker logs "$CONTAINER_ID"
             stop
             exit 1
             ;;
          *)
          sleep 1
          esac
    done
    echo "container did not get healthy within 120 seconds, quitting"
    docker logs mongodb_atlas_local
    stop
    exit 2
    }
    wait "$CONTAINER_ID"
    EXPOSED_PORT=$(docker inspect --format='{{ (index (index .NetworkSettings.Ports "27017/tcp") 0).HostPort }}' "$CONTAINER_ID")
    # Build the connectionstring
    CONNECTION_STRING="mongodb://127.0.0.1:$EXPOSED_PORT/test?directConnection=true"
    # Example usage of the connection string to connect to mongosh
    mongosh "$CONNECTION_STRING"

  2. Run the following command to make the file executable.

    chmod +x mongodb-atlas-local.sh

  3. Run the executable.

    ./mongodb-atlas-local.sh
4

Connect to the local Atlas deployment.

To connect to the local Atlas deployment from the host (not container), copy and paste the following command into a new terminal, and replace the {connection_string} variable with your connection string.

Note

The following example uses mongosh, but you can use the connection method that you prefer.

mongosh {connection_string}

Examples:

mongosh "mongodb://localhost:27017/?directConnection=true"
mongosh "mongodb://user:pass@localhost:27017/?directConnection=true"

Create a Local Atlas Deployment with Docker Compose

Create a local Atlas deployment with Docker Compose.

Note

If you have an existing Docker-Compose based Atlas implementation that you've built with the official MongoDB Docker Image and that you'd like to convert to use the Atlas Local Dev image, see Convert to a Local Dev Implementation below.

1

Install and start Docker.

To learn more, see the Docker documentation.

2

Install Docker Compose.

Example:

brew install docker-compose

To learn more, see the Docker Compose install documentation.

3

Create a docker-compose.yaml file.

Create the docker-compose.yaml file in the same directory that you run Docker Compose from.

Example:

1services:
2  mongodb:
3    image: mongodb/mongodb-atlas-local
4    environment:
5      - MONGODB_INITDB_ROOT_USERNAME=user
6      - MONGODB_INITDB_ROOT_PASSWORD=pass
7    ports:
8      - 27018:27017
4

Run Docker Compose.

The following command creates a local Atlas deployment with Atlas Search capabilities enabled.

Example:

docker-compose up
5

Connect to the local Atlas deployment.

To connect to the local Atlas deployment from the host (not container), copy and paste the following command into a new terminal, and replace the {connection_string} variable with your connection string.

Note

The following example uses mongosh, but you can use the connection method that you prefer.

mongosh {connection_string}

Example:

mongosh "mongodb://user:pass@localhost:27018/?directConnection=true"
6

(Optional) Stop the container.

docker compose down -v

Persist Data Across Runs with Docker Compose

You can persist data across multiple runs with Docker Compose. Persisting data helps to ensure that data isn't lost between runs. Data remains available across runs of Docker Compose.

1

Install and start Docker.

To learn more, see the Docker documentation.

2

Install Docker Compose.

Example:

brew install docker-compose

To learn more, see the Docker Compose install documentation.

3

Create a docker-compose.yaml file.

Update the docker-compose.yaml file to mount the necessary data directories as volumes.

Example:

1services:
2  mongodb:
3    hostname: mongodb
4    image: mongodb/mongodb-atlas-local
5    environment:
6      - MONGODB_INITDB_ROOT_USERNAME=user
7      - MONGODB_INITDB_ROOT_PASSWORD=pass
8    ports:
9      - 27019:27017
10    volumes:
11      - data:/data/db
12      - config:/data/configdb
13volumes:
14  data:
15  config:
4

Run Docker Compose.

The following command creates a local Atlas deployment with Atlas Search capabilities enabled.

Example:

docker-compose up

You can also run Docker Compose in detached mode.

Example:

docker-compose up -d
5

Connect to the local Atlas deployment.

To connect to the local Atlas deployment from the host (not container), copy and paste the following command into a new terminal, and replace the {connection_string} variable with your connection string.

Note

The following example uses mongosh, but you can use the connection method that you prefer.

mongosh {connection_string}

Example:

mongosh "mongodb://user:pass@localhost:27019/?directConnection=true"

Generate a List of Dependencies

You can generate a list of the dependencies for the mongodb/mongodb-atlas-local Docker image.

1

Install syft.

Example:

brew install syft

To learn more, see the syft README.

2

Run syft.

syft mongodb/mongodb-atlas-local

Verify the Image Signature

You can verify the signature of the mongodb/mongodb-atlas-local Docker image.

1

Install cosign.

Example:

brew install cosign

To learn more, see the cosign Installation.

2

Run the following commands.

Example:

curl -O https://cosign.mongodb.com/mongodb-atlas-local.pem
COSIGN_REPOSITORY="docker.io/mongodb/signatures" cosign verify --private-infrastructure --key=./mongodb-atlas-local.pem "mongodb/mongodb-atlas-local";

Run the Image with GitHub Actions

To run the mongodb/mongodb-atlas-local Docker image with GitHub actions, create a workflow file. To learn more, see the GitHub Actions Quickstart.

Example:

Create the following mongodb.yml file in the .github/workflows directory:

on:
  push:
    branches:
      - main
  pull_request:
jobs:
  run:
    runs-on: ubuntu-latest
    services:
      mongodb:
        image: mongodb/mongodb-atlas-local
        ports:
          - 27017:27017
    steps:
      - name: install mongosh
        run: |
         curl --output mongosh.deb https://downloads.mongodb.com/compass/mongodb-mongosh_2.2.1_amd64.deb
         sudo dpkg -i mongosh.deb
         mongosh --version
     - run: mongosh 'mongodb://localhost/?directConnection=true' --eval 'show dbs'

Convert Official Image to a Local Atlas Deployment

If you have an existing Atlas implementation running in Docker Compose that you have built with the official mongo Docker image, you can refer to the following checklist to simplify converting it to the mongodb-atlas-local image.

  1. Remove any existing command from your docker-compose.yaml file. Because the command in a Docker Compose definition overrides the ENTRYPOINT defined in the mongodb-atlas-local image, you must remove any existing command for the mongodb-atlas-local image to run as designed.

  2. There is no need to define a health check for the Atlas deployment, as this feature is built in to the mongodb-atlas-local image.

Example Docker Compose Updates

The following examples illustrate the likely required changes to your Docker Compose YAML file:

services:
  self_built_atlas_implementation:
    image: mongo:8.0
    ports:
      - 27017:27017
    command: ["./entrypoint.sh"]  # You may have defined a health check for the database in the entrypoint script.
services:
  local_dev_atlas:
    image: mongodb/mongodb-atlas-local:8.0
    hostname: local_dev_atlas
    ports:
      - 27017:27017
    environment:
      - MONGODB_INITDB_ROOT_USERNAME=user
      - MONGODB_INITDB_ROOT_PASSWORD=pass
    volumes:
      - data:/data/db
      - config:/data/configdb
volumes:
  - data:
  - config:

Back

Create a Local Deployment

Next

Use Atlas Search