MongoDB Atlas Local¶

Not available until the next release main

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¶

Not available until the next release main

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¶

Not available until the next release main

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¶

Not available until the next release main

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¶

Not available until the next release main

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¶

Not available until the next release main

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¶

Not available until the next release main

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

WithInitDatabase¶

Not available until the next release main

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¶

Not available until the next release main

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¶

Not available until the next release main

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

WithMongotLogToStdout¶

Not available until the next release main

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

WithMongotLogToStderr¶

Not available until the next release main

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

WithRunnerLogFile¶

Not available until the next release main

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

WithRunnerLogToStdout¶

Not available until the next release main

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

WithRunnerLogToStderr¶

Not available until the next release main

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¶

Build Options¶

WithDockerfile Since v0.37.0

Logging Options¶

Image Options¶

Networking Options¶

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 Not available until the next release main

Experimental Options¶

WithReuseByName Since v0.37.0

Container Methods¶

The MongoDB Atlas Local container exposes the following methods:

ConnectionString¶

Not available until the next release main

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¶

Not available until the next release main

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¶

Not available until the next release main

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
}