[Feature]: Add mongodb-atlas-local module

[prestonvasquez]

Problem

testcontainers-go does not have a module for mongodb/mongodb-atlas-local.

Solution

Add a mongodb/mongodb-atlas-local module.

Benefit

This would enable users to run integration tests against MongoDB Atlas-specific features (e.g. Atlas Vector Search) without requiring a remote cluster.

Alternatives

Users could use a generic container, see LangChainGo.

Would you like to help contributing this feature?

Yes

[mdelapenya]

Hi @prestonvasquez, is it possible to use the atlas-local image with the current MongoDB module, or do we need to do some changes to it?

[prestonvasquez]

Hey @mdelapenya , I think this should be a separate module as it introduces features that are not applicable to a local MongoDB server, specifically Atlas Search and Atlas Vector Search. This will require AL-specific options such as WithMongotLogFile, WithRunnerLogFile, and WithDisableTelemetry.

Additionally, there is no explicit rs.initiate() requirement when using Atlas Local: the image boots up a single-node replica set under the hood because that’s required for the search functionality to work.

Suggest we add an atlaslocal module to avoid complicating the existing mongodb module.

For example, using WithReplicaSet with the mongodb/mongodb-atlas-local:latest image results in failure:

func TestMongoDBWithAtlasLocal(t *testing.T) {
	ctx := context.Background()

	const imageName = "mongodb/mongodb-atlas-local:latest"

	container, err := mongodb.Run(ctx, imageName,
		mongodb.WithUsername("admin"),
		mongodb.WithPassword("password"),
		mongodb.WithReplicaSet("meep"),
	)
	if err != nil {
		dumpLogs(t, ctx, container)
	}
	require.NoError(t, err, "failed to start MongoDB container")

	host, err := container.Host(ctx)
	require.NoError(t, err, "failed to get container host")

	port, err := container.MappedPort(ctx, "27017")
	require.NoError(t, err, "failed to get mapped port")

	uri := fmt.Sprintf("mongodb://%s:%s/?directConnection=true", host, port.Port())

	client, err := mongo.Connect(options.Client().ApplyURI(uri))
	require.NoError(t, err, "failed to connect to MongoDB")

	defer func() {
		client.Disconnect(ctx)
	}()

	require.Eventually(t, func() bool {
		err := client.Ping(ctx, nil)
		return err == nil
	}, 60*time.Second, 5*time.Second)
}

// dumpLogs will dump the logs of the MongoDB Atlas Local container to the
// integration test output.
func dumpLogs(t *testing.T, ctx context.Context, ctr testcontainers.Container) {
	t.Helper()

	r, err := ctr.Logs(ctx)
	require.NoError(t, err)

	bytes, err := io.ReadAll(r)
	t.Logf("MongoDB Atlas Local logs:\n%s", string(bytes))
}

Output:

❯ go test -run TestMongoDBWithAtlasLocal -v -failfast
=== RUN   TestMongoDBWithAtlasLocal
2025/08/01 16:51:42 github.com/testcontainers/testcontainers-go - Connected to docker:
  Server Version: 28.1.1
  API Version: 1.49
  Operating System: Docker Desktop
  Total Memory: 7837 MB
  Labels:
    com.docker.desktop.address=unix:///Users/preston.vasquez/Library/Containers/com.docker.docker/Data/docker-cli.sock
  Testcontainers for Go Version: v0.38.0
  Resolved Docker Host: unix:///var/run/docker.sock
  Resolved Docker Socket Path: /var/run/docker.sock
  Test SessionID: bf7a67dd3c90323430e89f86391fca7ee6aa8a6e3e610eeb689aac156fc7c841
  Test ProcessID: eac140fb-b4ae-41c8-b842-bc8b375e5345
2025/08/01 16:51:42 🐳 Creating container for image mongodb/mongodb-atlas-local:latest
2025/08/01 16:51:42 🐳 Creating container for image testcontainers/ryuk:0.12.0
2025/08/01 16:51:42 ✅ Container created: 9d4331a8be03
2025/08/01 16:51:42 🐳 Starting container: 9d4331a8be03
2025/08/01 16:51:42 ✅ Container started: 9d4331a8be03
2025/08/01 16:51:42 ⏳ Waiting for container id 9d4331a8be03 image: testcontainers/ryuk:0.12.0. Waiting for: &{Port:8080/tcp timeout:<nil> PollInterval:100ms skipInternalCheck:false skipExternalCheck:false}
2025/08/01 16:51:43 🔔 Container is ready: 9d4331a8be03
2025/08/01 16:51:43 ✅ Container created: 117f12ac276d
2025/08/01 16:51:43 🐳 Starting container: 117f12ac276d
2025/08/01 16:51:43 ✅ Container started: 117f12ac276d
2025/08/01 16:51:43 ⏳ Waiting for container id 117f12ac276d image: mongodb/mongodb-atlas-local:latest. Waiting for: &{timeout:<nil> deadline:0x140003efca0 Strategies:[0x140004277d0 0x1400044e180]}
2025/08/01 16:51:43 container logs (container exec create: Error response from daemon: container 117f12ac276d19cccd2ec41d3c6909369ac3d4a255d1e6a0fe5ed2aec2509943 is not running
wait until ready: container exited with code 2):
/tmp/entrypoint-tc.sh: line 13: find: command not found
/tmp/entrypoint-tc.sh: line 32: exec: --: invalid option
exec: usage: exec [-cl] [-a name] [command [argument ...]] [redirection ...]
    testcontainers_test.go:29: MongoDB Atlas Local logs:
        /tmp/entrypoint-tc.sh: line 13: find: command not found
        /tmp/entrypoint-tc.sh: line 32: exec: --: invalid option
        exec: usage: exec [-cl] [-a name] [command [argument ...]] [redirection ...]
    testcontainers_test.go:31:
                Error Trace:    /Users/preston.vasquez/Developer/dev/third-party/testcontainers-go/testcontainers_test.go:31
                Error:          Received unexpected error:
                                generic container: start container: started hook: container exec create: Error response from daemon: container 117f12ac276d19cccd2ec41d3c6909369ac3d4a255d1e6a0fe5ed2aec2509943 is not running
                                wait until ready: container exited with code 2
                Test:           TestMongoDBWithAtlasLocal
                Messages:       failed to start MongoDB container
--- FAIL: TestMongoDBWithAtlasLocal (0.88s)
FAIL
exit status 1
FAIL    github.com/prestonvasquez/dev/third-party/testcontainers-go     1.447s

[prestonvasquez]

@mdelapenya, just following up to confirm whether the dedicated atlaslocal module approach in #3254 is acceptable to you and the maintainers.

[mdelapenya]

hey @prestonvasquez I'm currently on PTO, returning to work next Monday 🙏 Will go back to this project then