Docs Menu
Docs Home
/ /
Atlas CLI
/ /

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

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.

1

To learn more, see the Docker documentation.

2

Example:

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

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

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.

1

To learn more, see the Docker documentation.

2

Example:

brew install docker-compose

To learn more, see the Docker Compose install documentation.

3

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

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

Example:

docker-compose up
5

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
docker compose down -v

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

To learn more, see the Docker documentation.

2

Example:

brew install docker-compose

To learn more, see the Docker Compose install documentation.

3

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

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 - 27019:27017
9 volumes:
10 - data:/data/db
11volumes:
12 data:
4

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

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"

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

1

Example:

brew install syft

To learn more, see the syft README.

2
syft mongodb/mongodb-atlas-local

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

1

Example:

brew install cosign

To learn more, see the cosign Installation.

2

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";

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'

Back

Create a Local Deployment