MongoDB Atlas Local

Since v0.39.0

Introduction

The MongoDB Atlas Local module for Testcontainers lets you spin up a local MongoDB Atlas instance in Docker using mongodb/mongodb-atlas-local for integration tests and development. This module supports SCRAM authentication, init scripts, and custom log file mounting.

This module differs from the standard modules/mongodb Testcontainers module, allowing users to spin up a full local Atlas-like environment complete with Atlas Search and Atlas Vector Search.

Adding this module to your project dependencies

Please run the following command to add the MongoDB Atlas Local module to your Go dependencies:

go get github.com/testcontainers/testcontainers-go/modules/mongodb/atlaslocal

Usage example

Creating a MongoDB Atlas Local container

ctx := context.Background()

atlaslocalContainer, err := atlaslocal.Run(ctx, "mongodb/mongodb-atlas-local:latest")
defer func() {
    if err := testcontainers.TerminateContainer(atlaslocalContainer); err != nil {
        log.Printf("failed to terminate container: %s", err)
    }
}()
if err != nil {
    log.Printf("failed to start container: %s", err)
    return
}

Module Reference

Run function

• Since v0.39.0

The atlaslocal module exposes one entrypoint function to create the MongoDB Atlas Local container, and this function receives three parameters:

func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*Container, error)

• context.Context, the Go context.
• string, the Docker image to use.
• testcontainers.ContainerCustomizer, a variadic argument for passing options.

Image

Use the second argument in the Run function to set a valid Docker image. In example: Run(context.Background(), "mongodb/mongodb-atlas-local:latest").

Container Options

When starting the MongoDB Atlas Local container, you can pass options in a variadic way to configure it.

WithUsername

• Since v0.39.0

This functional option sets the initial username to be created when the container starts, populating the MONGODB_INITDB_ROOT_USERNAME environment variable. You cannot mix this option with WithUsernameFile, as it will result in an error.

WithPassword

• Since v0.39.0

This functional option sets the initial password to be created when the container starts, populating the MONGODB_INITDB_ROOT_PASSWORD environment variable. You cannot mix this option with WithPasswordFile, as it will result in an error.

WithUsernameFile

• Since v0.39.0

This functional option mounts a local file as the MongoDB root username secret at /run/secrets/mongo-root-username and sets the MONGODB_INITDB_ROOT_USERNAME_FILE environment variable. The path must be absolute and exist; no-op if empty.

WithPasswordFile

• Since v0.39.0

This functional option mounts a local file as the MongoDB root password secret at /run/secrets/mongo-root-password and sets the MONGODB_INITDB_ROOT_PASSWORD_FILE environment variable. The path must be absolute and exist; no-op if empty.

WithNoTelemetry

• Since v0.39.0

This functional option disables the telemetry feature of MongoDB Atlas Local, setting the DO_NOT_TRACK environment variable to 1.

WithInitDatabase

• Since v0.39.0

This functional option allows you to specify a database name to be initialized when the container starts, populating the MONGODB_INITDB_DATABASE environment variable.

WithInitScripts

• Since v0.39.0

Mounts a directory into /docker-entrypoint-initdb.d, running .sh/.js scripts on startup. Calling this function multiple times mounts only the latest directory.

WithMongotLogFile

• Since v0.39.0

This functional option writes the mongot logs to /tmp/mongot.log inside the container. See (*Container).ReadMongotLogs to read the logs locally.

WithMongotLogToStdout

• Since v0.39.0

This functional option writes the mongot logs to /dev/stdout inside the container. See (*Container).ReadMongotLogs to read the logs locally.

WithMongotLogToStderr

• Since v0.39.0

This functional option writes the mongot logs to /dev/stderr inside the container. See (*Container).ReadMongotLogs to read the logs locally.

WithRunnerLogFile

• Since v0.39.0

This functional option writes the runner logs to /tmp/runner.log inside the container. See (*Container).ReadRunnerLogs to read the logs locally.

WithRunnerLogToStdout

• Since v0.39.0

This functional option writes the runner logs to /dev/stdout inside the container. See (*Container).ReadRunnerLogs to read the logs locally.

WithRunnerLogToStderr

• Since v0.39.0

This functional option writes the runner logs to /dev/stderr inside the container. See (*Container).ReadRunnerLogs to read the logs locally.

The following options are exposed by the testcontainers package.

Basic Options

• WithExposedPorts Since v0.37.0
• WithEnv Since v0.29.0
• WithWaitStrategy Since v0.20.0
• WithAdditionalWaitStrategy Since v0.38.0
• WithWaitStrategyAndDeadline Since v0.20.0
• WithAdditionalWaitStrategyAndDeadline Since v0.38.0
• WithEntrypoint Since v0.37.0
• WithEntrypointArgs Since v0.37.0
• WithCmd Since v0.37.0
• WithCmdArgs Since v0.37.0
• WithLabels Since v0.37.0

Lifecycle Options

• WithLifecycleHooks Since v0.38.0
• WithAdditionalLifecycleHooks Since v0.38.0
• WithStartupCommand Since v0.25.0
• WithAfterReadyCommand Since v0.28.0

Files & Mounts Options

• WithFiles Since v0.37.0
• WithMounts Since v0.37.0
• WithTmpfs Since v0.37.0
• WithImageMount Since v0.37.0

Build Options

• WithDockerfile Since v0.37.0

Logging Options

• WithLogConsumers Since v0.28.0
• WithLogConsumerConfig Since v0.38.0
• WithLogger Since v0.29.0

Image Options

• WithAlwaysPull Since v0.38.0
• WithImageSubstitutors Since v0.26.0
• WithImagePlatform Since v0.38.0

Networking Options

• WithNetwork Since v0.27.0
• WithNetworkByName Since v0.38.0
• WithBridgeNetwork Since v0.38.0
• WithNewNetwork Since v0.27.0

Advanced Options

• WithHostPortAccess Since v0.31.0
• WithConfigModifier Since v0.20.0
• WithHostConfigModifier Since v0.20.0
• WithEndpointSettingsModifier Since v0.20.0
• CustomizeRequest Since v0.20.0
• WithName Since v0.38.0
• WithNoStart Since v0.38.0
• WithProvider Since v0.39.0

Experimental Options

• WithReuseByName Since v0.37.0

Container Methods

The MongoDB Atlas Local container exposes the following methods:

ConnectionString

• Since v0.39.0

The ConnectionString method returns the connection string to connect to the MongoDB Atlas Local container. It returns a string with the format mongodb://<host>:<port>[/<db>]/?directConnection=true[&authSource=admin].

It can be used to configure a MongoDB client (go.mongodb.org/mongo-driver/v2/mongo), e.g.:

Using ConnectionString with the MongoDB client

ctx := context.Background()

atlaslocalContainer, err := atlaslocal.Run(ctx, "mongodb/mongodb-atlas-local:latest")
defer func() {
    if err := testcontainers.TerminateContainer(atlaslocalContainer); err != nil {
        log.Printf("failed to terminate container: %s", err)
    }
}()
if err != nil {
    log.Printf("failed to start container: %s", err)
    return
}

connString, err := atlaslocalContainer.ConnectionString(ctx)
if err != nil {
    log.Printf("failed to get connection string: %s", err)
    return
}

mongoClient, err := mongo.Connect(options.Client().ApplyURI(connString))
if err != nil {
    log.Printf("failed to connect to MongoDB: %s", err)
    return
}

ReadMongotLogs

• Since v0.39.0

The ReadMongotLogs returns a reader for the log solution specified when constructing the container.

Using ReadMongotLogs with the MongoDB client

ctx := context.Background()

atlaslocalContainer, err := atlaslocal.Run(ctx, "mongodb/mongodb-atlas-local:latest",
    atlaslocal.WithMongotLogFile())

defer func() {
    if err := testcontainers.TerminateContainer(atlaslocalContainer); err != nil {
        log.Printf("failed to terminate container: %s", err)
    }
}()

if err != nil {
    log.Printf("failed to start container: %s", err)
    return
}

connString, err := atlaslocalContainer.ConnectionString(ctx)
if err != nil {
    log.Printf("failed to get connection string: %s", err)
    return
}

_, err = mongo.Connect(options.Client().ApplyURI(connString))
if err != nil {
    log.Printf("failed to connect to MongoDB: %s", err)
    return
}

reader, err := atlaslocalContainer.ReadMongotLogs(ctx)
if err != nil {
    log.Printf("failed to read mongot logs: %s", err)
    return
}
defer reader.Close()

if _, err := io.Copy(io.Discard, reader); err != nil {
    log.Printf("failed to write mongot logs: %s", err)
    return
}

ReadRunnerLogs

• Since v0.39.0

The ReadRunnerLogs returns a reader for the log solution specified when constructing the container.

Using ReadRunnerLogs with the MongoDB client

ctx := context.Background()

atlaslocalContainer, err := atlaslocal.Run(ctx, "mongodb/mongodb-atlas-local:latest",
    atlaslocal.WithRunnerLogFile())

defer func() {
    if err := testcontainers.TerminateContainer(atlaslocalContainer); err != nil {
        log.Printf("failed to terminate container: %s", err)
    }
}()

if err != nil {
    log.Printf("failed to start container: %s", err)
    return
}

connString, err := atlaslocalContainer.ConnectionString(ctx)
if err != nil {
    log.Printf("failed to get connection string: %s", err)
    return
}

_, err = mongo.Connect(options.Client().ApplyURI(connString))
if err != nil {
    log.Printf("failed to connect to MongoDB: %s", err)
    return
}

reader, err := atlaslocalContainer.ReadRunnerLogs(ctx)
if err != nil {
    log.Printf("failed to read runner logs: %s", err)
    return
}
defer reader.Close()

if _, err := io.Copy(io.Discard, reader); err != nil {
    log.Printf("failed to write runner logs: %s", err)
    return
}