# Technical Documentation: testcontainers/testcontainers-go

> ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/testcontainers/testcontainers-go)

### Overview (`README.md`)

# Testcontainers

[](https://github.com/testcontainers/testcontainers-go/actions/workflows/ci.yml)
[](https://pkg.go.dev/github.com/testcontainers/testcontainers-go)
[](https://goreportcard.com/report/github.com/testcontainers/testcontainers-go)
[](https://sonarcloud.io/summary/new_code?id=testcontainers_testcontainers-go)
[](https://github.com/testcontainers/testcontainers-go/blob/main/LICENSE)

[](https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=141451032&machine=standardLinux32gb&devcontainer_path=.devcontainer%2Fdevcontainer.json&location=EastUs)

[](https://testcontainers.slack.com/)

_Testcontainers for Go_ is a Go package that makes it simple to create and clean up container-based dependencies for
automated integration/smoke tests. The clean, easy-to-use API enables developers to programmatically define containers
that should be run as part of a test and clean up those resources when the test is done.

You can find more information about _Testcontainers for Go_ at [golang.testcontainers.org](https://golang.testcontainers.org), which is rendered from the [./docs](./docs) directory.

## Using _Testcontainers for Go_

Please visit [the quickstart guide](https://golang.testcontainers.org/quickstart) to understand how to add the dependency to your Go project.

---

### Overview (`modulegen/README.md`)

# Testcontainers for Go code modules

Please read the docs [here](../docs/examples/index.md) or visit the website: https://golang.testcontainers.org/modules/

---

### Overview (`usage-metrics/README.md`)

# Testcontainers-Go Usage Metrics

This directory contains the automation system for tracking testcontainers-go usage across GitHub repositories.

## Overview

The system automatically collects three datasets: two usage metrics obtained by querying the GitHub Code Search API for references to testcontainers-go in `go.mod` files across public repositories, and the daily clone traffic of this repository obtained from the GitHub Traffic API. The data is visualised in interactive dashboards integrated into the main MkDocs documentation site at https://golang.testcontainers.org/usage-metrics/

## Components

### 📊 Data Collection (`collect.go`)

A single Go program with three subcommands:

| Subcommand | Source | Flag |
|---|---|---|
| `versions` | Code Search: `"testcontainers/testcontainers-go {version}"` in go.mod | `-version` |
| `modules` | Code Search: `"testcontainers/testcontainers-go/modules/{module}"` in go.mod | `-module` |
| `clones` | Traffic API: `GET /repos/{repo}/traffic/clones?per=day` | `-repo` (default `testcontainers/testcontainers-go`), `-until` (optional `YYYY-MM-DD`, record days up to and including it) |

The search subcommands exclude forks and testcontainers organisation repositories, retry on rate-limit errors (up to 5 passes, with inter-request and cooldown waits), and append results to a CSV file.

The `clones` subcommand fetches the last 14 days of clone traffic (the maximum GitHub retains) in a single request, retries retryable errors up to 5 passes, and **upserts** one row per day into its CSV: rows with a date already present are replaced, because consecutive 14-day windows overlap and GitHub revises recent days. The CSV header must be exactly `date,count,uniques` and the file is rewritten atomically through a temporary file. `-until` drops days after the given date; the workflow passes yesterday so the in-progress UTC day is never stored. Authentication errors, including any 403 that does not mention a rate limit, are not retried. The Traffic API requires push access to the repository, so this subcommand needs a token with the `Administration: read` repository permission.

### 💾 Data Storage

| File | Description | Format |
|---|---|---|
| `docs/usage-metrics/core.csv` | Historical adoption data by library version | `date,version,count` |
| `docs/usage-metrics/modules.csv` | Historical import counts by module | `date,module,count` |
| `docs/usage-metrics/clones.csv` | Daily clone traffic of this repository | `date,count,uniques` |

All files are version-controlled for historical tracking and served directly by the MkDocs site.

### 🌐 Website (integrated into `docs/`)

| File | Purpose |
|---|---|
| `docs/usage-metrics/index.md` | Core library dashboard (landing page for the section) |
| `docs/usage-metrics/modules.md` | Modules dashboard |
| `docs/usage-metrics/clones.md` | GitHub clones dashboard |
| `docs/js/usage-metrics.js` | Charts for the core library dashboard |
| `docs/js/modules-usage-metrics.js` | Charts for the modules dashboard |
| `docs/js/clones-metrics.js` | Charts for the GitHub clones dashboard, with a Day / Week / Month / Year toggle |
| `docs/css/usage-metrics.css` | Shared styles for all dashboards |

All dashboards use Chart.js for visualisations and are responsive for mobile and desktop.

### 🤖 Automation

| Workflow | Schedule | Trigger input |
|---|---|---|
| `.github/workflows/usage-metrics.yml` | Monthly, 1st at 09:00 UTC | `versions` — comma-separated (empty = all from v0.13.0) |
| `.github/workflows/usage-metrics-modules.yml` | Monthly, 1st at 10:00 UTC | `modules` — comma-separated (empty = all modules under `modules/`) |
| `.github/workflows/github-clones.yml` | Daily at 03:00 UTC | none |

The two search workflows create a pull request for the metrics update rather than committing directly to main.

The clones workflow runs daily and maintains a monthly data branch named `YYYY-MM-clones`. On every run the branch is rebuilt on top of `main`: the run checks out `main`, restores `clones.csv` from the branch's previous tip (or from the previous month's branch when a new month starts), upserts the latest days up to yesterday, and force-pushes a single commit with `--force-with-lease`. The branch therefore always has exactly one commit over `main` and never conflicts with it. On the first run after a month ends, the previous month's branch is rebuilt the same way with `-until` set to the month's last day, so its final days carry complete numbers, and a pull request from it to `main` is opened; merging it publishes the data on the docs site. The check is repeated on every run, so a skipped schedule cannot lose the pull request. A `concurrency` group prevents two runs from pushing at the same time.

The clones workflow reads the Traffic API with the `TRAFFIC_TOKEN` repository secret: a fine-grained personal access token scoped to this repository with `Administration: read` and `Metadata: read`. Pushes and the pull request use the default `GITHUB_TOKEN`.

## Data Formats

### Core library (`docs/usage-metrics/core.csv`)

Tracks how many public repositories import each version of the core library.

```csv
date,version,count
2024-01-15,v0.27.0,133
2024-02-15,v0.27.0,145
2024-02-15,v0.28.0,12
```

- **date**: Collection date in `YYYY-MM-DD` format
- **version**: Version string (e.g. `v0.27.0`)
- **count**: Number of repositories importing that version

### Modules (`docs/usage-metrics/modules.csv`)

Tracks how many public repositories import each individual module.

```csv
date,module,count
2026-06-01,kafka,245
2026-06-01,postgres,1748
2026-06-01,redis,668
```

- **date**: Collection date in `YYYY-MM-DD` format
- **module**: Module directory name (e.g. `kafka`, `postgres`)
- **count**: Number of repositories importing that module

### GitHub clones (`docs/usage-metrics/clones.csv`)

Tracks how many times the repository was cloned each day, as reported by GitHub.

```csv
date,count,uniques
2026-09-16,5392,1372
2026-09-17,6073,1567
```

- **date**: Day of the clones in `YYYY-MM-DD` format (UTC)
- **count**: Total clones on that day
- **uniques**: Unique cloners on that day, as counted by GitHub. Summing this column over several days overestimates the number of distinct cloners.

History starts on 2026-09-16. GitHub discards traffic older than 14 days, so earlier data cannot be recovered.

## Usage

### Manual Collection

```bash
cd usage-metrics

# Collect specific versions
go run collect.go versions -version v0.37.0 -version v0.38.0 -csv ../docs/usage-metrics/core.csv

# Collect specific modules
go run collect.go modules -module kafka -module redis -csv ../docs/usage-metrics/modules.csv

# Collect the last 14 days of clone traffic (needs a token with push access, see below)
GH_TOKEN=<token> go run collect.go clones -csv ../docs/usage-metrics/clones.csv

# Same, but ignore the in-progress day
GH_TOKEN=<token> go run collect.go clones -csv ../docs/usage-metrics/clones.csv -until "$(date -u -d yesterday +%Y-%m-%d)"
```

Flags can be repeated for multiple items. All subcommands accept a `-csv` flag to override the default output path.

### Running Locally

```bash
# Serve the docs (from the repository root)
make serve-docs

# Core library dashboard:  http://localhost:8000/usage-metrics/
# Modules dashboard:        http://localhost:8000/usage-metrics/modules/
# GitHub clones dashboard:  http://localhost:8000/usage-metrics/clones/
```

### Manual Workflow Trigger

**Core library versions:**
1. Go to Actions → "Update Usage Metrics"
2. Click "Run workflow"
3. Optionally specify versions (e.g. `v0.39.0,v0.38.0`) or leave empty for all versions since v0.13.0

**Modules:**
1. Go to Actions → "Update Modules Usage Metrics"
2. Click "Run workflow"
3. Optionally specify modules (e.g. `kafka,redis`) or leave empty for all modules

**GitHub clones:**
1. Go to Actions → "Update GitHub Clones Metrics"
2. Click "Run workflow"

## Rate Limiting

GitHub Code Search API limits:
- **Unauthenticated**: 10 requests/minute
- **Authenticated**: 30 requests/minute

The collection script queries items sequentially with:
- A 7-second wait between consecutive requests within a pass
- A 65-second cooldown after a rate-limit hit within a pass
- A 120-second wait between passes (up to 5 passes total)

The `gh` CLI is used under the hood, which automatically authenticates with the `GITHUB_TOKEN` available in the workflow environment.

## Tests

Unit tests cover all logic that does not depend on the `gh` CLI:

```bash
cd usage-metrics
go test ./...
```

## Customisation

### Changing Collection Frequency

Edit the cron schedule in the relevant workflow file:

```yaml
schedule:
  - cron: '0 9 1 * *'  # Monthly on the 1st at 9 AM UTC
```

### Customising Charts

- Core library: edit `docs/js/usage-metrics.js`
- Modules: edit `docs/js/modules-usage-metrics.js`

### Changing the Version Range

By default, `usage-metrics.yml` queries all tags matching `v0.X.Y` from v0.13.0 onwards. To change the starting point, modify the `awk` pattern in the workflow file.

### Adding or Removing Modules

The modules workflow auto-discovers all subdirectories under `modules/` that contain a `go.mod` file. No manual list maintenance is needed.

## Architecture Decisions

### Why a single `collect.go` with subcommands?

Both collection jobs share the same retry logic, CSV helpers, and GitHub API call pattern. A single binary with `versions` and `modules` subcommands eliminates the duplication while keeping the two data models cleanly separated.

### Why CSV?

- Simple and human-readable
- Version-controlled with Git for free historical diffing
- No database or external service required
- Suitable for the data volume (one row per item per month)

### Why Go for Collection?

- Native to the project — no extra runtime or dependency
- Easy `gh` CLI invocation for authenticated GitHub API calls
- Good standard-library CSV support

## Troubleshooting

### API Rate Limiting

The collection script retries automatically (up to 5 passes). If it still fails:
1. Check the workflow logs under the "Query versions" or "Query modules" step
2. Re-run the workflow manually for the failed items only

### CSV Not Updating

1. Go to Actions and open the relevant workflow run
2. Review the query step output for any errors
3. Verify that `GH_TOKEN` / `GITHUB_TOKEN` has Code Search access
4. For clones, verify that the `TRAFFIC_TOKEN` secret exists, has not expired, and grants `Administration: read` on the repository. A `403 Must have push access` error in the "Collect clone traffic" step means the token lacks that permission.

### Charts Not Displaying

1. Verify the CSV file is at `docs/usage-metrics/core.csv`, `docs/usage-metrics/modules.csv` or `docs/usage-metrics/clones.csv`
2. Open the browser console and look for fetch or JavaScript errors
3. Ensure Chart.js and PapaParse CDN links are accessible from your browser

## License

Same as the main testcontainers-go repository (MIT).

---

### Overview (`modules/dex/README.md`)

# Dex

Since <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>

## Introduction

The Testcontainers module for [Dex](https://github.com/dexidp/dex), a CNCF OIDC provider.

## Adding this module to your project dependencies

```bash
go get github.com/testcontainers/testcontainers-go/modules/dex
```

## Usage example

```go
ctx := context.Background()

app, err := dex.NewClient("my-app",
    dex.WithClientSecret("secret"),
    dex.WithClientRedirectURIs("http://localhost:8080/callback"),
    dex.WithClientGrantTypes("authorization_code", "refresh_token"),
    dex.WithClientName("My App"),
)
if err != nil {
    log.Fatalf("new client: %v", err)
}

user, err := dex.NewUser("user@example.com", "user", "password")
if err != nil {
    log.Fatalf("new user: %v", err)
}

c, err := dex.Run(ctx, "dexidp/dex:v2.45.1",
    dex.WithClient(app),
    dex.WithUser(user),
)
if err != nil {
    log.Fatalf("run dex: %v", err)
}
defer testcontainers.TerminateContainer(c)

fmt.Println("issuer:", c.IssuerURL())
```

## Supported grants

`authorization_code`, `refresh_token`, `password`. Declare per-client via
`WithClientGrantTypes(...)`.

**`client_credentials` requires Dex ≥ v2.46.0 (or `dexidp/dex:master` until
that release ships) with the feature flag enabled.** Dex gates this grant
behind the env var `DEX_CLIENT_CREDENTIAL_GRANT_ENABLED_BY_DEFAULT=true`.
Use `WithEnableClientCredentials()` to set it automatically. The module
does not validate the image tag — the caller must pin a compatible image.

```go
svc, err := dex.NewClient("svc",
    dex.WithClientSecret("s"),
    dex.WithClientName("Service"),
    dex.WithClientGrantTypes("client_credentials"),
)
// ...
c, err := dex.Run(ctx, "dexidp/dex:master",
    dex.WithEnableClientCredentials(),
    dex.WithClient(svc),
)
```

Clients added at runtime via `AddClient` inherit Dex's defaults
(`authorization_code` + `refresh_token`) because Dex's gRPC `api.Client` proto
has no `grant_types` field. Clients needing other grants must be declared
pre-start via `WithClient`.

## Connectors

- `ConnectorPassword` — Dex's built-in static password DB (default; enabled
  automatically when a user is seeded via `WithUser`). Disable via
  `WithDisablePasswordDB()` when running connector-only flows.
- `ConnectorMock` — Dex's `mockCallback` test connector (returns a fixed user,
  `kilgore@kilgore.trout`).

## Issuer URL

By default, the issuer is derived from the host and mapped HTTP port:
`http://<host>:<mappedPort>/dex`. Pass `WithIssuer(...)` when the issuer must
be reachable from other containers (for example via a shared Docker network
and a network alias). The caller owns reachability when overriding.

## ID token claims

Dex's password connector emits these standard claims in ID tokens:

- `sub` — stable user ID (auto-generated UUID when constructed via `NewUser`
  without `WithUserID`).
- `email` — user's email address.
- `email_verified` — always `true` for static password entries.
- `name` — the value of `User`'s username.
- `iss` — the issuer URL.
- `aud` — the client ID.

Dex does NOT emit the `preferred_username` claim; use the `name` claim instead
when a human-readable identifier is needed.

## Module reference

### Types

- `Client` — opaque OAuth2 client value. Construct with `NewClient(id, opts...)`.
- `User` — opaque password entry. Construct with `NewUser(email, username, password, opts...)`.
- `ConnectorType` — `ConnectorPassword`, `ConnectorMock`
- `Storage` — `StorageSQLite` (default), `StorageMemory`

### Client options (`ClientOption`)

- `WithClientSecret(string)`
- `WithClientName(string)`
- `WithClientRedirectURIs(...string)`
- `WithClientGrantTypes(...string)`
- `WithClientPublic()`

### User options (`UserOption`)

- `WithUserID(string)` — pin a stable subject claim. Omit to auto-generate UUIDv4.

### Module options

- `WithClient(Client)`
- `WithUser(User)`
- `WithConnector(type, id, name)`
- `WithIssuer(url)`
- `WithSkipApprovalScreen(bool)`
- `WithStorage(Storage)` — `StorageSQLite` (default) or `StorageMemory`
- `WithDisablePasswordDB()` — opt out of the built-in password DB
- `WithLogger(*slog.Logger)` — captures Dex logs
- `WithLogLevel(slog.Level)` — sets Dex's `logger.level` YAML key
- `WithEnableClientCredentials()` — enables the OAuth2 `client_credentials` grant via feature flag (requires Dex ≥ v2.46.0 or `:master`)

### Endpoint getters

- `IssuerURL() string`
- `ConfigEndpoint() string`
- `JWKSEndpoint() string`
- `TokenEndpoint() string`
- `AuthEndpoint() string`
- `GRPCEndpoint(ctx context.Context) (string, error)` — only getter that
  may return an error (Docker host/port lookup).

### Runtime mutation (gRPC)

`AddClient`, `RemoveClient`, `AddUser`, `RemoveUser`. Not safe for concurrent
use.

- `AddClient` returns `ErrClientExists` when the ID is already registered.
- `AddUser` returns `ErrUserExists` when the email is already registered.
- `RemoveClient` wraps `ErrClientNotFound` when the ID is absent.
- `RemoveUser` wraps `ErrUserNotFound` when the email is absent.

## Known limitations

- Runtime-added clients inherit Dex's default grants; non-default grants must
  be declared pre-start via `WithClient`.
- `client_credentials` requires `WithEnableClientCredentials()` and Dex ≥
  v2.46.0 or the `:master` image tag. On v2.45.x and earlier the token
  endpoint returns `unsupported_grant_type` regardless of client config.
- gRPC admin API is plaintext. TLS not supported day 1.
- `mockCallback` emits a fixed user; parameterized flows need the password
  connector with a pre-seeded user.
- SQLite storage is container-local and ephemeral.
- Bcrypt cost ≥ 10 is enforced by Dex for both YAML and gRPC password paths.

---

### Index (`docs/index.md`)

# Welcome to Testcontainers for Go!

<p align="center"><strong>Not using Go? Here are other supported languages!</strong></p>
<div class="card-grid">
    <a href="https://java.testcontainers.org" class="card-grid-item"><img src="language-logos/java.svg" alt=""/>Java</a>
    <a class="card-grid-item"><img src="language-logos/go.svg" alt=""/>Go</a>
    <a href="https://dotnet.testcontainers.org/" class="card-grid-item"><img src="language-logos/dotnet.svg" alt=""/>.NET</a>
    <a href="https://node.testcontainers.org/" class="card-grid-item"><img src="language-logos/nodejs.svg" alt=""/>Node.js</a>
    <a href="https://testcontainers-python.readthedocs.io/en/latest/" class="card-grid-item"><img src="language-logos/python.svg" alt=""/>Python</a>
    <a href="https://rust.testcontainers.org/" class="card-grid-item"><img src="language-logos/rust.svg" alt=""/>Rust</a>
    <a href="https://github.com/testcontainers/testcontainers-ruby/" class="card-grid-item"><img src="language-logos/ruby.svg" alt=""/>Ruby</a>
    <a href="https://php.testcontainers.org/" class="card-grid-item"><img src="language-logos/php.svg" alt=""/>PHP</a>
    <a href="https://github.com/testcontainers/testcontainers-hs/" class="card-grid-item"><img src="language-logos/haskell.svg" alt=""/>Haskell</a>
    <a href="https://cljdoc.org/d/clj-test-containers/clj-test-containers/" class="card-grid-item"><img src="language-logos/clojure.svg" alt=""/>Clojure</a>
    <a href="https://github.com/testcontainers/testcontainers-elixir" class="card-grid-item"><img src="language-logos/elixir.svg" alt=""/>Elixir</a>
    <a href="https://github.com/testcontainers/testcontainers-scala/" class="card-grid-item"><img src="language-logos/scala.svg" alt=""/>Scala</a>
    <a href="https://github.com/testcontainers/testcontainers-native" class="card-grid-item"><img src="language-logos/c.svg" alt=""/>Native</a>
</div>

## About Testcontainers for Go

_Testcontainers for Go_ is a Go package that makes it simple to create and clean up container-based dependencies for
automated integration/smoke tests. The clean, easy-to-use API enables developers to programmatically define containers
that should be run as part of a test and clean up those resources when the test is done.

To start using _Testcontainers for Go_ please read our [quickstart guide](./quickstart.md).

## GoDoc

Inline documentation and docs where the code live is crucial for us. Go has nice support for them and we provide
examples as well. Check it out at
[pkg.go.dev/github.com/testcontainers/testcontainers-go](https://pkg.go.dev/github.com/testcontainers/testcontainers-go).

## Who is using Testcontainers Go?

* [Elastic](https://www.elastic.co) - Testing of the APM Server, and E2E testing for Beats
* [Telegraf](https://www.influxdata.com/time-series-platform/telegraf/) - Integration testing the plugin-driven server agent for collecting & reporting metrics
* [Intel](https://intel.com/) - Reference implementation design E2E testing for microservice-based solutions
* [OpenTelemetry](https://opentelemetry.io/) - Integration testing of the OpenTelemetry Collector receivers

## License

This project is opensource and you can have a look at the code on
[GitHub](https://github.com/testcontainers/testcontainers-go). See [LICENSE](https://github.com/testcontainers/testcontainers-go/blob/main/LICENSE).

## Copyright

Copyright (c) 2018-present Gianluca Arbezzano and other authors. Check out our
[lovely contributors](https://github.com/testcontainers/testcontainers-go/graphs/contributors).

---

### Quickstart (`docs/quickstart.md`)

_Testcontainers for Go_ plays well with the native `go test` framework.

The ideal use case is for integration or end to end tests. It helps you to spin
up and manage the dependencies life cycle via Docker.

## 1. System requirements

Please read the [system requirements](../system_requirements/) page before you start.

## 2. Install _Testcontainers for Go_

We use [go mod](https://blog.golang.org/using-go-modules) and you can get it installed via:

```
go get github.com/testcontainers/testcontainers-go
```

## 3. Spin up Redis

```go
import (
	"context"
	"testing"

	"github.com/stretchr/testify/require"

	"github.com/testcontainers/testcontainers-go"
	"github.com/testcontainers/testcontainers-go/wait"
)

func TestWithRedis(t *testing.T) {
	ctx := context.Background()
	redisC, err := testcontainers.Run(
		ctx, "redis:latest",
		testcontainers.WithExposedPorts("6379/tcp"),
		testcontainers.WithWaitStrategy(
			wait.ForListeningPort("6379/tcp"),
			wait.ForLog("Ready to accept connections"),
		),
	)
	testcontainers.CleanupContainer(t, redisC)
	require.NoError(t, err)
}
```

The `testcontainers.Run` function receives the image name and a list of options with how the Docker container will
look.

* `WithExposedPorts` is an option that lists the ports to be exposed from the container.
* `WithWaitStrategy` is an option that you can use to validate when a container is ready. It
  is important to get this set because it helps to know when the container is
  ready to receive any traffic. In this case, we check for the logs we know come
  from Redis, telling us that it is ready to accept requests.

When you use `WithExposedPorts` you have to imagine yourself using `docker run -p
<port>`.  When you do so, `dockerd` maps the selected `<port>` from inside the
container to a random one available on your host.

In the previous example, we expose `6379` for `tcp` traffic to the outside. This
allows Redis to be reachable from your code that runs outside the container, but
it also makes parallelization possible because if you add `t.Parallel()` to your
tests, and each of them starts a Redis container each of them will be exposed on a
different random port.

`testcontainers.Run` creates and starts the container. In this example we are
not using the `WithNoStart()` option. It means that the container function will wait for the
container to be up and running. If you pass the `WithNoStart()` option, it won't
start, leaving to you the decision about when to start it.	

All the containers must be removed at some point, otherwise they will run until
Ryuk the resource reaper terminates them, or when the host is overloaded.
One of the ways we have to clean up the container immediately is by using the `testing`
package from the standard library along with the `CleanupContainer` function:
`testcontainers.CleanupContainer(t, redisC)`. This function
automatically handles nil container so it can be used before any error check.

!!!tip

    Look at [features/garbage_collector](/features/garbage_collector/) to know another way to
    clean up resources.

## 4. Make your code to talk with the container

This is just an example, but usually Go applications that rely on Redis are
using the [redis-go](https://github.com/go-redis/redis) client. This code gets
the endpoint from the container we just started, and it configures the client.

```go
endpoint, err := redisC.Endpoint(ctx, "")
if err != nil {
    t.Error(err)
}

client := redis.NewClient(&redis.Options{
    Addr: endpoint,
})

_ = client
```

We expose only one port, so the `Endpoint` does not need a second argument set.

!!!tip

    If you expose more than one port you can specify the one you need as a second
    argument.

In this case it returns: `localhost:<mappedportfor-6379>`.

## 5. Run the test

You can run the test via `go test ./...`

## 6. Want to go deeper with Redis?

You can find a more elaborated Redis example in our examples section. Please check it out [here](./modules/redis.md).

---

### Examples Index (`docs/examples/index.md`)

# Code examples

In this section you'll discover how to create code examples for _Testcontainers for Go_, which are almost the same as Go modules, but without exporting any public API.

Their main goal is to create shareable code snippets on how to use certain technology (e.g. a database, a web server), in order to explore its usage before converting the example module into a real Go module exposing a public API.

## Interested in adding a new example?

Please refer to the documentation of the code generation tool [here](../modules/index.md).

## Update Go dependencies in the examples

To update the Go dependencies in the examples, please run:

```shell
$ cd examples
$ make tidy-examples
```

---

### Modules Index (`docs/modules/index.md`)

# Testcontainers for Go modules

In this section you'll discover how to create Go modules for _Testcontainers for Go_, including the steps to follow, the best practices, and the guidelines to consider before creating a new module.

## Before creating a new module

First, you have to consider the following things before creating a new module to the project:

1. Please check if the module you are interested in is already present in the [Modules Catalog](https://testcontainers.com/modules/?language=go).
If it's already there, you can use it as a dependency in your project, and you can also contribute to the module if you want to improve it!
2. If it is not present there, please consider where you are going to host the module: under your own GitHub account as a **Community module**, or under the `testcontainers-go` repository.
3. If you're a vendor interested in creating an **Official module** for your project/product, please contact us, see below.

In any case, we will be happy to assist you in the process of creating the module. Please feel free to ask for assistance in our [Slack](https://slack.testcontainers.org/) or in the [GitHub Discussions](https://github.com/testcontainers/testcontainers-go/discussions).

### Community modules

If you are going to host the module under your own GitHub account, please consider the following:

- you'll have to follow the same guidelines as the ones for the modules hosted under the `testcontainers-go` repository,
including the naming conventions, the documentation, the tests and the testable examples, and defining a proper CI workflow.
You'll find more information in the sections below.
- you'll be more autonomous in the development and release of the module, not having to wait for the maintainers to review and merge your PRs.
As a direct consequence, you'll be responsible for the maintenance, documentation and support of the module,
including updating the module to the latest version of _Testcontainers for Go_ if/when needed.
- once created, you'll need to add the module to the [Modules Catalog](https://testcontainers.com/modules/?language=go) in order to be listed there.
You can do this by submitting a PR to the [community repository](https://github.com/testcontainers/community-module-registry).
An example can be found [here](https://github.com/testcontainers/community-module-registry/pull/21/files).
- you'll need to add the module to the [Go documentation](https://pkg.go.dev) in order to be listed there. Please check our [Releasing docs](https://github.com/testcontainers/testcontainers-go/blob/main/RELEASING.md) for more information about triggering the Golang Proxy.

### Modules hosted under the `testcontainers-go` repository

If you still want to host the module under the `testcontainers-go` repository, please consider the following:

- we are not experts in all the technologies out there, so we are open to contributions from the community.
We are happy to review and merge your PRs, and we are also happy to help you with the development of the module.
But this is a shared responsibility, so we expect you to be involved in the maintenance, documentation and support of the module.
- the module will be part of the CI/CD pipeline of the `testcontainers-go` repository, so it will be tested and released with the rest of the modules.
Think of GitHub workflows, release notes, etc. Although it sounds great, which it is, it also means that it will increase the build time in our CI/CD pipeline on GitHub, including flaky tests, number of dependency updates, etc. So in the end it's more work for us.
- once created, we'll add the module to the [Modules Catalog](https://testcontainers.com/modules/?language=go) and to the [Go documentation](https://pkg.go.dev/github.com/testcontainers/testcontainers-go).

## Creating a new module

We have provided a command line tool to generate the scaffolding for the code of the example you are interested in. This tool will generate:

- a Go module for the example, including:
    - go.mod and go.sum files, including the current version of _Testcontainer for Go_.
    - a Go package named after the module, in lowercase
    - a Go file for the creation of the container.
    - a Go test file for running a simple test for your container, consuming the above struct and using the image flag as Docker image for the container.
    - a Go examples file for running the example in the docs site, also adding them to [https://pkg.go.dev](https://pkg.go.dev).
    - a Makefile to run the tests in a consistent manner
- a markdown file in the docs/modules directory including the snippets for both the creation of the container and a simple test. By default, this generated file will contain all the documentation for the module, including:
    - the version of _Testcontainers for Go_ in which the module was added.
    - a short introduction to the module.
    - a section for adding the module to the project dependencies.
    - a section for a usage example, including:
        - a snippet for creating the container, from the `examples_test.go` file in the Go module.
    - a section for the module reference, including:
        - the entrypoint function for creating the container.
        - the options for creating the container.
    - a section for the container methods.
- a new Nav entry for the module in the docs site, adding it to the `mkdocs.yml` file located at the root directory of the project.
- a GitHub workflow file in the .github/workflows directory to run the tests for the example.
- an entry in the VSCode workspace file, in order to include the new module in the project's workspace.

!!!info
    If you are hosting the module under your own GitHub account, please move the generated files to the new repository. Discard the following files and directories: `mkdocs.yml`, VSCode workspace, Sonarqube properties, and the `.github/workflows` directory, as they are specific to the `testcontainers-go` repository. You can use them as reference to create your own CI/CD pipeline.

### Command line flags

| Flag    | Short | Type   | Required | Description                                                                                                                                      |
|---------|-------|--------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------|
| --name  | -n    | string | Yes      | Name of the module, use camel-case when needed. Only alphanumerical characters are allowed (leading character must be a letter).                 |
| --image | -i    | string | Yes      | Fully-qualified name of the Docker image to be used in the examples and tests (i.e. 'org/project:tag')                                             |
| --title | -t    | string | No       | A variant of the name supporting mixed casing (i.e. 'MongoDB'). Only alphanumerical characters are allowed (leading character must be a letter). |


### What is this tool not doing?

- If the module name or title does not contain alphanumerical characters, it will exit the generation.
- If the module already exists, it will exit without updating the existing files.

### How to run the tool

From the [`modulegen` directory]({{repo_url}}/tree/main/modulegen), please run:

```shell
go run . new module --name ${NAME_OF_YOUR_MODULE} --image "${REGISTRY}/${MODULE}:${TAG}" --title ${TITLE_OF_YOUR_MODULE}
```

!!!info
    In the case you just want to create [an example module](../examples/index.md), with no public API, please run:

    ```shell
    go run . new example --name ${NAME_OF_YOUR_MODULE} --image "${REGISTRY}/${MODULE}:${TAG}" --title ${TITLE_OF_YOUR_MODULE}
    ```

### Technology modules: client/SDK dependency policy

Production modules and images should remain **driver-agnostic**.

- Do not bundle client SDKs (database/message broker/storage drivers, etc.) **in production modules or images.**  
  Examples: `yugabyte/gocql`, etc.
- If you need to show how to connect to a given technology, provide bootstrap code as helpers and keep those dependencies in **tests/examples** only.
- Prefer small helpers that read container state and build a client config. Reference those helpers from examples and tests.

### Adding types and methods to the module

We are going to propose a set of steps to follow when adding types and methods to the module:

!!!warning
    The `StartContainer` function will be eventually deprecated and replaced with `Run`. We are keeping it in certain modules for backwards compatibility, but they will be removed in the future.

#### Container struct design

- **Make sure a public `Container` type exists for the module**. This type has to use composition to embed the `testcontainers.Container` type, promoting all the methods from it.
- **Use the name `Container`**, not a module-specific name like `PostgresContainer` or `RedisContainer`. This keeps the API consistent across modules.

```golang
// Container represents the container type used in the module
type Container struct {
    testcontainers.Container
    // private fields, maybe obtained from the settings struct (i.e. settings.dbName, settings.user, settings.password, etc.)
    dbName   string
    user     string
    password string
    ...
    // Or you can directly store all the options
    settings options // keep processed Option state
}
```

!!!info
    Some existing modules still use module-specific container names (e.g., `PostgresContainer`). These will eventually be changed to follow the `Container` naming convention.

- **Use private fields** for storing container state (e.g., connection details, credentials, settings). This prevents external mutation and keeps the API clean.
- **Public fields are acceptable** when they are part of the public API and users need direct access, but prefer private fields with public accessor methods when possible.

#### The Run function

- **Make sure a `Run` function exists and is public**. This function is the entrypoint to the module with signature: `func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*Container, error)`
- The function should:
1. Process custom module options first (if using an intermediate config struct)
2. Build `moduleOpts` slice with default container configuration
3. Append user-provided options to `moduleOpts`
4. Call `testcontainers.Run(ctx, img, moduleOpts...)`
5. Return the module-specific container with proper error wrapping

```golang
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*Container, error) {
    // 1. Process custom options to extract settings (if needed)
    var settings options
    for _, opt := range opts {
        if opt, ok := opt.(Option); ok {
            if err := opt(&settings); err != nil {
                return nil, err
            }
        }
    }

    // 2. Build moduleOpts with defaults
    moduleOpts := []testcontainers.ContainerCustomizer{
        testcontainers.WithExposedPorts("6379/tcp"),
        testcontainers.WithWaitStrategy(wait.ForListeningPort("6379/tcp")),
    }

    // Add conditional options based on settings
    if settings.tlsEnabled {
        moduleOpts = append(moduleOpts, /* TLS configuration */)
    }

    // 3. Append user options
    moduleOpts = append(moduleOpts, opts...)

    // 4. Call testcontainers.Run
    ctr, err := testcontainers.Run(ctx, img, moduleOpts...)
    var c *Container
    if ctr != nil {
        c = &Container{Container: ctr, settings: settings}
    }

    // 5. Return with proper error wrapping
    if err != nil {
        return c, fmt.Errorf("run redis: %w", err)
    }

    return c, nil
}
```

#### Container options

Define container options for the module leveraging the `testcontainers.ContainerCustomizer` interface, that has one single method: `Customize(req *GenericContainerRequest) error`.

!!!warning
    The interface definition for `ContainerCustomizer` was changed to allow errors to be correctly processed.
    More specifically, the `Customize` method was changed from:

    ```go
    Customize(req *GenericContainerRequest)
    ```

    To:

    ```go
    Customize(req *GenericContainerRequest) error
    ```

##### When to use built-in options vs custom options

**Prefer built-in options** (`testcontainers.With*`) for simple configuration. These options return `testcontainers.CustomizeRequestOption`, which is a concrete function type (not an interface) that implements the `testcontainers.ContainerCustomizer` interface:

```golang
// ✅ Good: Use built-in options for simple env var settings
// Returns testcontainers.CustomizeRequestOption (struct, not interface)
func WithDatabase(dbName string) testcontainers.CustomizeRequestOption {
    return testcontainers.WithEnv(map[string]string{"POSTGRES_DB": dbName})
}

func WithPassword(password string) testcontainers.CustomizeRequestOption {
    return testcontainers.WithEnv(map[string]string{"POSTGRES_PASSWORD": password})
}
```

**Use `testcontainers.CustomizeRequestOption`** for complex logic requiring multiple operations. Always return the struct type, not the interface:

```golang
// ✅ Good: Return testcontainers.CustomizeRequestOption (struct type)
func WithConfigFile(cfg string) testcontainers.CustomizeRequestOption {
    return func(req *testcontainers.GenericContainerRequest) error {
        cfgFile := testcontainers.ContainerFile{
            HostFilePath:      cfg,
            ContainerFilePath: "/etc/postgresql.conf",
            FileMode:          0o755,
        }

        if err := testcontainers.WithFiles(cfgFile)(req); err != nil {
            return err
        }

        return testcontainers.WithCmdArgs("-c", "config_file=/etc/postgresql.conf")(req)
    }
}
```

**Create your own `Option` type** when you need to transfer state that isn't part of the container request. Return the struct type, not an interface:

```golang
// Options struct for transferring state
type options struct {
    tlsEnabled bool
    tlsConfig  *tls.Config
}

// Option function type for custom module options
type Option func(*options) error

// ✅ Good: Return Option struct type, not testcontainers.ContainerCustomizer interface
func WithTLS() Option {
    return func(opts *options) error {
        opts.tlsEnabled = true
        return nil
    }
}

// Implement ContainerCustomizer interface to satisfy testcontainers.ContainerCustomizer
func (o Option) Customize(req *testcontainers.GenericContainerRequest) error {
    // This method can be empty if the option only sets internal state
    return nil
}

// In Run function, process these before building moduleOpts
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*Container, error) {
    var settings options
    for _, opt := range opts {
        if opt, ok := opt.(Option); ok {
            if err := opt(&settings); err != nil {
                return nil, err
            }
        }
    }
    // Now use settings.tlsEnabled to conditionally add options
    ...
}
```

##### Option patterns and best practices

**Always return struct types, not interfaces:**

```golang
// ✅ Correct: Return concrete struct type
func WithUsername(user string) testcontainers.CustomizeRequestOption {
    return testcontainers.WithEnv(map[string]string{"USER": user})
}

// ❌ Wrong: Don't return interface type
func WithUsername(user string) testcontainers.ContainerCustomizer {
    return testcontainers.WithEnv(map[string]string{"USER": user})
}
```

**Error handling in options:**
- Simple options returning `testcontainers.CustomizeRequestOption` should propagate errors from built-in options
- Custom `Option` types should return errors for validation failures

```golang
// CustomizeRequestOption - propagate errors
func WithInitScripts(scripts ...string) testcontainers.CustomizeRequestOption {
    return func(req *testcontainers.GenericContainerRequest) error {
        containerFiles := []testcontainers.ContainerFile{/* ... */}
        return testcontainers.WithFiles(containerFiles...)(req)
    }
}

// Custom Option type - return validation errors
type Option func(*Options) error

func WithListener(hostPort string) Option {
    return func(opts *Options) error {
        host, port, err := net.SplitHostPort(hostPort)
        if err != nil {
            return fmt.Errorf("invalid host:port format: %w", err)
        }
        opts.Listeners = append(opts.Listeners, Listener{Host: host, Port: port})
        return nil
    }
}
```

**Calling built-in options from custom options:**

```golang
// ✅ Correct: Call built-in options directly
func WithConfigFile(cfg string) testcontainers.CustomizeRequestOption {
    return func(req *testcontainers.GenericContainerRequest) error {
        return testcontainers.WithFiles(cfgFile)(req)
    }
}

// ❌ Wrong: Don't use .Customize() method
func WithConfigFile(cfg string) testcontainers.CustomizeRequestOption {
    return func(req *testcontainers.GenericContainerRequest) error {
        return testcontainers.WithFiles(cfgFile).Customize(req)  // Wrong!: adds unnecessary indirection
    }
}
```

##### Option ordering

The order in which options are applied matters:

1. **Module defaults** (in `moduleOpts` slice) - base configuration
2. **User-provided options** (via `opts...`) - user customizations
3. **Post-processing options** (appended last) - validation, network config, etc.

```golang
moduleOpts := []testcontainers.ContainerCustomizer{
    // 1. Defaults
    testcontainers.WithEnv(map[string]string{"DB": "default"}),
}

// 2. User options
moduleOpts = append(moduleOpts, opts...)

// 3. Post-processing (after user options, if needed)
moduleOpts = append(moduleOpts, validateConfiguration)
```

##### Inspecting container state after Run

When you need to read environment variables or other container state after creation:

```golang
ctr, err := testcontainers.Run(ctx, img, moduleOpts...)
if err != nil {
    return nil, fmt.Errorf("run postgres: %w", err)
}

// Retrieve actual env vars set on the container
inspect, err := ctr.Inspect(ctx)
if err != nil {
    return nil, fmt.Errorf("inspect postgres: %w", err)
}

var foundDB, foundUser, foundPass bool
for _, env := range inspect.Config.Env {
    if v, ok := strings.CutPrefix(env, "POSTGRES_DB="); ok {
        c.dbName, foundDB = v, true
    }
    if v, ok := strings.CutPrefix(env, "POSTGRES_USER="); ok {
        c.user, foundUser = v, true
    }
    if v, ok := strings.CutPrefix(env, "POSTGRES_PASSWORD="); ok {
        c.password, foundPass = v, true
    }

    // Early exit optimization
    if foundDB && foundUser && foundPass {
        break
    }
}
```

**Best practices:**
- Use `strings.CutPrefix` (standard library) instead of manual string manipulation
- Set defaults when creating the container struct, not in the loop
- Use individual `found` flags and check all together for early exit
- Break early once all required values are found

#### Container methods

- If needed, define public methods to extract information from the running container, using the `Container` type as receiver. E.g. a connection string to access a database:

```golang
func (c *Container) ConnectionString(ctx context.Context, args ...string) (string, error) {
    endpoint, err := c.PortEndpoint(ctx, "5432/tcp", "")
    if err != nil {
        return "", err
    }
    return fmt.Sprintf("postgres://%s:%s@%s/%s", c.user, c.password, endpoint, c.dbName), nil
}
```

#### Documentation

- Document the public API with Go comments.
- Extend the docs to describe the new API of the module. We usually define a parent `Module reference` section, including a `Container options` and a `Container methods` subsections; within each subsection, we define a nested subsection for each option and method, respectively.

### ContainerRequest options

In order to simplify the creation of the container for a given module, `Testcontainers for Go` provides a set of `testcontainers.CustomizeRequestOption` functions to customize the container request for the module. These options are:

- `testcontainers.WithImageSubstitutors`: a function that sets your own substitutions to the container images.
- `testcontainers.WithEnv`: a function that sets the environment variables for the container request.
- `testcontainers.WithExposedPorts`: a function that exposes additional ports from the container.
- `testcontainers.WithEntrypoint`: a function that completely replaces the container's entrypoint.
- `testcontainers.WithEntrypointArgs`: a function that appends commands to the container's entrypoint.
- `testcontainers.WithCmd`: a function that completely replaces the container's command.
- `testcontainers.WithCmdArgs`: a function that appends commands to the container's command.
- `testcontainers.WithLabels`: a function that adds Docker labels to the container.
- `testcontainers.WithFiles`: a function that copies files from the host into the container at creation time.
- `testcontainers.WithMounts`: a function that adds volume mounts to the container.
- `testcontainers.WithTmpfs`: a function that adds tmpfs mounts to the container.
- `testcontainers.WithHostPortAccess`: a function that enables the container to access a port that is already running in the host.
- `testcontainers.WithLogConsumers`: a function that sets the log consumers for the container request.
- `testcontainers.WithLogConsumerConfig`: a function that sets the log consumer config for the container request.
- `testcontainers.WithLogger`: a function that sets the logger for the container request.
- `testcontainers.WithLifecycleHooks`: a function that sets the lifecycle hooks for the container request.
- `testcontainers.WithAdditionalLifecycleHooks`: a function that appends lifecycle hooks to the existing ones for the container request.
- `testcontainers.WithAlwaysPull`: a function that pulls the image before starting the container.
- `testcontainers.WithImagePlatform`: a function that sets the image platform for the container request.
- `testcontainers.WithWaitStrategy`: a function that replaces the wait strategy for the container request.
- `testcontainers.WithAdditionalWaitStrategy`: a function that appends the wait strategy for the container request.
- `testcontainers.WithWaitStrategyAndDeadline`: a function that replaces the wait strategy for the container request with a deadline.
- `testcontainers.WithAdditionalWaitStrategyAndDeadline`: a function that appends the wait strategy for the container request with a deadline.
- `testcontainers.WithStartupCommand`: a function that sets the execution of a command when the container starts.
- `testcontainers.WithAfterReadyCommand`: a function that sets the execution of a command right after the container is ready (its wait strategy is satisfied).
- `testcontainers.WithDockerfile`: a function that sets the build from a Dockerfile for the container request.
- `testcontainers.WithNetwork`: a function that sets the network and the network aliases for the container request.
- `testcontainers.WithNewNetwork`: a function that sets the network aliases for a throw-away network for the container request.
- `testcontainers.WithConfigModifier`: a function that sets the config Docker type for the container request. Please see [Advanced Settings](../features/creating_container.md#advanced-settings) for more information.
- `testcontainers.WithHostConfigModifier`: a function that sets the host config Docker type for the container request. Please see [Advanced Settings](../features/creating_container.md#advanced-settings) for more information.
- `testcontainers.WithEndpointSettingsModifier`: a function that sets the endpoint settings Docker type for the container request. Please see [Advanced Settings](../features/creating_container.md#advanced-settings) for more information.
- `testcontainers.CustomizeRequest`: a function that merges the default options with the ones provided by the user. Recommended for completely customizing the container request.
- `testcontainers.WithReuseByName`: a function that marks a container to be reused if it exists or create a new one if it doesn't.
- `testcontainers.WithName`: a function that sets the name of the container.
- `testcontainers.WithNoStart`: a function that prevents the container from being started after creation, so it must be started manually.
- `network.WithNetwork`: a function that sets the network and the network aliases for the container request, reusing an already existing network.
- `network.WithNetworkName`: a function that sets the network aliases for an already existing network, by its name.
- `network.WithBridgeNetwork`: a function that sets the container to be attached to the `bridge` network.
- `network.WithNewNetwork`: a function that sets the network aliases for a throw-away network for the container request.

### Update Go dependencies in the modules

To update the Go dependencies in the modules, please run:

```shell
$ cd modules
$ make tidy-examples
```

## Refreshing the modules

To refresh the modules, please run:

```shell
$ cd modulegen
$ go run . refresh
```

This command recreates all the project files for the modules and examples, including:

- the mkdocs.yml file, including all the modules and examples, excluding the `compose` module, as it has its own docs page.
- the VSCode project file, including all the modules, the examples and the modulegen module.
- the Sonar properties file, including all the modules, the examples and the modulegen module.

Executing this command in a well-known state of the project, must not produce any changes in the project files.

The Dependabot config is maintained manually. Its directory globs automatically cover new modules and examples, and updates to the same dependency are grouped into one pull request across the configured Go modules.

## Interested in converting an example into a module?

The steps to convert an existing example, aka `${THE_EXAMPLE}`, into a module are the following:

1. Rename the module path at the `go.mod` file for your example.
1. Move the `examples/${THE_EXAMPLE}` directory to `modules/${THE_EXAMPLE}`.
1. In the `mkdocs.yml` file, move the entry for `${THE_EXAMPLE}` from examples to modules.
1. Move `docs/examples${THE_EXAMPLE}.md` file to `docs/modules/${THE_EXAMPLE}`, updating the references to the source code paths.
1. Update the GitHub workflow for `${THE_EXAMPLE}`, modifying names and paths.

---

### System Requirements Index (`docs/system_requirements/index.md`)

# Go version

From the [Go Release Policy](https://go.dev/doc/devel/release#policy):

> Each major Go release is supported until there are two newer major releases. For example, Go 1.5 was supported until the Go 1.7 release, and Go 1.6 was supported until the Go 1.8 release. We fix critical problems, including critical security problems, in supported releases as needed by issuing minor revisions (for example, Go 1.6.1, Go 1.6.2, and so on).

_Testcontainers for Go_ is tested against those two latest Go releases, therefore we recommend using any of them. You could check what versions are actually supported by looking at the [GitHub Action](https://github.com/testcontainers/testcontainers-go/blob/main/.github/workflows/ci.yml) configuration, under the `test.strategy.matrix.go-version` key.

## Updating the Go version

The project has a script to update the Go version used in the project. To update the Go version across all files, please run the following command:

```bash
DRY_RUN=false ./scripts/bump-go.sh 1.21
```

It will update:
- all `go.mod` files.
- all GitHub Actions workflows, and their matrices using the `go-version` strategy.
- the templates for the module generator.
- the Devcontainer configuration.
- the tag of the Go Docker image in the markdown documentation.

---

### Usage Metrics Index (`docs/usage-metrics/index.md`)

# Usage Metrics

Since `v0.30`, I noticed all versions decreased a lot, which could be a reality: projects upgrading to the latest releases; but `v0.39.0` passed from ~500 to ~100. And v0.40.0 passed from ~700 to ~1300, so in total, we lost ~1500 imports.

In any case, I also noticed that GH search produces non-deterministic results, so executing the same query returns different numbers. I expect the overall trend gets fixed in the upcoming months.

<div id="loading" class="loading">Loading metrics data...</div>
<div id="error" class="error" style="display: none;"></div>

<div id="content" style="display: none;">
    <div class="stats-grid" id="stats-grid">
        
    </div>

    <div class="chart-container">
        <h2 class="chart-title">Total Adoption Over Time</h2>
        <canvas id="versionChart"></canvas>
    </div>

    <div class="chart-container">
        <h2 class="chart-title">Usage Trend Over Time</h2>
        <canvas id="trendChart"></canvas>
    </div>

    <div class="chart-container">
        <h2 class="chart-title">Latest Usage by Version</h2>
        <canvas id="latestChart"></canvas>
    </div>

    <div class="metrics-info">
        <p>Data collected from <a href="https://github.com/search?q=%22testcontainers%2Ftestcontainers-go%22+path%3Ago.mod+NOT+is%3Afork+NOT+org%3Atestcontainers&type=code" target="_blank">GitHub Code Search</a></p>
        <p>Last updated: <span id="update-time"></span></p>
    </div>
</div>

## GitHub Stars

[](https://www.star-history.com/#testcontainers/testcontainers-go&type=date&legend=top-left)

---

### Bounty (`docs/bounty.md`)

# Testcontainers issue bounty policy

## General

We want to use issue bounties to encourage contributions in areas that are important to our sponsors, or tricky to solve.
This includes bug fixes and new features.
We hope that this will provide incentives to tackle issues, and gives sponsors a way to influence where development time is expended.
We also want to reward our contributors, some of whom make huge efforts to improve Testcontainers and help their fellow developers!

!!! note
    It's early days for our use of sponsorship, so we expect to evolve this policy over time, possibly without notice. In the event of any ambiguity or dispute, the [Testcontainers org core maintainers](#organisation-core-maintainers) have the final say.

    If you'd like to suggest an improvement to this policy, we'd be grateful for your input - please raise a pull request!

## For Sponsors

Sponsors will be able to create a number of 'bounties' per month, varying according to sponsorship tier.

As a sponsor, the process for creating a bounty is as follows:

* Raise an issue, or find an existing issue that describes the bug or feature.
* Start a discussion with the [Testcontainers org core maintainers](#organisation-core-maintainers) to agree that the issue is suitable for a bounty, and how much the reward amount should be.
* Once agreed, we will assign a label to the issue so that interested developers can find it.

Sponsors can create up to 1 or 3 bounties (according to tier) _per calendar month_ - i.e. the counter resets on the 1st of each month. 
If a sponsor does not use their full quota of bounty credits in a calendar month, they cannot be rolled over to the next month.

Bounties will expire 90 days after creation - after this time, if they have not been resolved we will close them.

## For Contributors

As a contributor, the process for working on an issue with a bounty attached is:

* Find an issue with a bounty attached to it and no assignee, clarify the requirements if necessary, and consider how you would approach working on it.
* Start a discussion with the [Testcontainers org core maintainers](#organisation-core-maintainers) and the bounty owner. To avoid unpleasant surprises at review time, we'll try to confirm that we're happy with your proposed solution.
* If we're happy with your proposed solution, we will assign the ticket to you.
* Once work is complete, we will go through the PR process as usual and merge the work when finished.
* To receive the bounty reward, [raise an invoice](https://opencollective.com/testcontainers/expenses/new) on Open Collective, following the expenses policy on that page.

Note that a 20% cut of the bounty amount will normally be assigned to project maintainers for PR review work.
We believe this reflects that PR review can often be a significant amount of work for some issues - and also gives maintainers an incentive to complete the review and unlock the bounty reward!
Some pull requests are so well done that very little review is necessary. If that happens, the maintainers may choose not to take a cut of the bounty, and instead release the full amount to the contributor.

## Organisation core maintainers

The organisation core maintainers are:

* Richard North (@rnorth)
* Sergei Egorov (@bsideup)
* Kevin Wittek (@kiview)

---

### Contributing (`docs/contributing.md`)

# Contributing

`Testcontainers for Go` is open source, and we love to receive contributions from our community — you!

There are many ways to contribute, from writing tutorials or blog posts, improving the documentation, submitting bug reports and feature requests, or writing code for the core library or for a technology module.

In any case, if you like the project, please star the project on [GitHub](https://github.com/testcontainers/testcontainers-go/stargazers) and help spread the word :)
Also join our [Slack workspace](http://slack.testcontainers.org) to get help, share your ideas, and chat with the community.

## Questions

GitHub is reserved for bug reports and feature requests; it is not the place for general questions.
If you have a question or an unconfirmed bug, please visit our [Slack workspace](https://testcontainers.slack.com/);
feedback and ideas are always welcome.

## Code contributions

If you have a bug fix or new feature that you would like to contribute, please find or open an [issue](https://github.com/testcontainers/testcontainers-go/issues) first.
It's important to talk about what you would like to do, as there may already be someone working on it,
or there may be context to be aware of before implementing the change.

Next would be to fork the repository and make your changes in a feature branch. **Please do not commit changes to the `main` branch**,
otherwise we won't be able to contribute to your changes directly in the PR.

### Submitting your changes

Please just be sure to:

* follow the style, naming and structure conventions of the rest of the project.
* make commits atomic and easy to merge.
* use [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) for the PR title. This will help us to understand the nature of the changes, and to generate the changelog after all the commits in the PR are squashed.
    * Please use the `feat!`, `chore!`, `fix!`... types for breaking changes, as these categories are considered as `breaking change` in the changelog. Please use the `!` to denote a breaking change.
    * Please use the `security` type for security fixes, as these categories are considered as `security` in the changelog.
    * Please use the `feat` type for new features, as these categories are considered as `feature` in the changelog.
    * Please use the `fix` type for bug fixes, as these categories are considered as `bug` in the changelog.
    * Please use the `docs` type for documentation updates, as these categories are considered as `documentation` in the changelog.
    * Please use the `chore` type for housekeeping commits, including `build`, `ci`, `style`, `refactor`, `test`, `perf` and so on, as these categories are considered as `chore` in the changelog.
    * Please use the `deps` type for dependency updates, as these categories are considered as `dependencies` in the changelog.

!!!important
    There is a GitHub Actions workflow that will check if your PR title follows the conventional commits convention. If not, it contributes a failed check to your PR.
    To know more about the conventions, please refer to the [workflow file](https://github.com/testcontainers/testcontainers-go/blob/main/.github/workflows/conventions.yml).

* use [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) for your commit messages, as it improves the readability of the commit history, and the review process. Please follow the above conventions for the PR title.
* unless necessary, please try to **avoid pushing --force** to the published branch you submitted a PR from, as it makes it harder to review the changes from a given previous state.
* apply format running `make lint-all`. It will run `golangci-lint` for the core and modules with the configuration set in the root directory of the project. Please be aware that the lint stage on CI could fail if this is not done.
    * For linting just the modules: `make -C modules lint-modules`
    * For linting just the examples: `make -C examples lint-examples`
    * For linting just the modulegen: `make -C modulegen lint`
* verify all tests are passing. Build and test the project with `make test-all` to do this.
    * For a given module or example, go to the module or example directory and run `make test`.
    * If you find an `ld warning` message on MacOS, you can ignore it. It is indeed a warning: https://github.com/golang/go/issues/61229
> === Errors
> ld: warning: '/private/var/folders/3y/8hbf585d4yl6f8j5yzqx6wz80000gn/T/go-link-2319589277/000018.o' has malformed LC_DYSYMTAB, expected 98 undefined symbols to start at index 1626, found 95 undefined symbols starting at index 1626

* when updating the `go.mod` file, please run `make tidy-all` to ensure all modules are updated.

### Module contribution 

For detailed policies on module development and contributions, please refer to the [Module Index page](./modules/index.md).

## Documentation contributions

The _Testcontainers for Go_ documentation is a static site built with [MkDocs](https://www.mkdocs.org/).
We use the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme, which offers a number of useful extensions to MkDocs.

We publish our documentation using Netlify.

### Adding functional options

When adding a new functional option, besides adding the Go code for the new option, you have to update the [common_functional_options.md](./features/common_functional_options.md) file to include the new option, with the following syntax:

```md
#### WithNewFeature

- Not available until the next release <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>

If you need to set the new feature, you can use the `testcontainers.WithNewFeature` option.
```

Also update the [common_functional_options_list.md](./features/common_functional_options_list.md) file to include the new option, with the following syntax:

```md
- [`WithNewFeature`](/features/common_functional_options/#withnewfeature) Not available until the next release <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
```

This file is imported by all the modules, so they will all have the new option in the documentation.

!!!important
    The release process automatically updates the version of the module across the documentation site, so use the _`main`_ placeholder as shown above,as you don't need to use a fixed version manually.

### Adding code snippets

To include code snippets in the documentation, we use the [codeinclude plugin](https://github.com/rnorth/mkdocs-codeinclude-plugin), which uses the following syntax:

> &lt;!--codeinclude--&gt;<br/>
> &#91;Human readable title for snippet&#93;(./relative_path_to_example_code.go) targeting_expression<br/>
> &#91;Human readable title for snippet&#93;(./relative_path_to_example_code.go) targeting_expression<br/>
> &lt;!--/codeinclude--&gt;<br/>

Where each title snippet in the same `codeinclude` block would represent a new tab
in the snippet, and each `targeting_expression` would be:

- `block:someString` or
- `inside_block:someString`

Please refer to the [codeinclude plugin documentation](https://github.com/rnorth/mkdocs-codeinclude-plugin) for more information.

### Previewing rendered content

From the root directory of the repository, you can use the following command to build and serve the documentation locally:

```shell
make serve-docs
```

It will use a Docker container to install the required dependencies and start a local server at `http://localhost:8000`.

Once finished, you can destroy the container with the following command:

```shell
make clean-docs
```

### PR Preview deployments

Note that documentation for pull requests will automatically be published by Netlify as 'deploy previews'.
These deployment previews can be accessed via the `deploy/netlify` check that appears for each pull request.

Please check the GitHub comment Netlify posts on the PR for the URL to the deployment preview.

---

### Dependabot (`docs/dependabot.md`)

# Staying up to date with Dependabot

It is recommended to group the Testcontainers update modules for dependabot using the following configuration:

```yaml
version: 2
updates:
  - package-ecosystem: "gomod"
    directories:
      - "/"
      - ...
    schedule:
      interval: "daily"
    groups:
      testcontainers-go:
        patterns:
          - "github.com/testcontainers/testcontainers-go"
          - "github.com/testcontainers/testcontainers-go/modules/*"
```

This ensures that all modules are updated at the same time, and that the PRs are grouped together. 

It also helps to avoid conflicts and makes it easier to review the changes.

---

### Getting Help (`docs/getting_help.md`)

# Getting help

We hope that you find Testcontainers intuitive to use and reliable.
However, sometimes things don't go the way we'd expect, and we'd like to try and help out if we can.

To contact the Testcontainers team and other users you can:

* Join our [Slack team](https://slack.testcontainers.org)
* [Search our issues tracker](https://github.com/testcontainers/testcontainers-go/issues), or raise a new issue if you find any bugs or have suggested improvements
* [Search Stack Overflow](https://stackoverflow.com/questions/tagged/testcontainers), especially among posts tagged with `testcontainers`

---

### Examples Nginx (`docs/examples/nginx.md`)

# Nginx


[Creating a Nginx container](../../examples/nginx/nginx.go)



[Test for a Nginx container](../../examples/nginx/nginx_test.go)

---

### Features Build From Dockerfile (`docs/features/build_from_dockerfile.md`)

# Build from Dockerfile

_Testcontainers for Go_ gives you the ability to build an image and run a container
from a Dockerfile.

You can do so by specifying a `Context` (the filepath to the build context on
your local filesystem) and optionally a `Dockerfile` (defaults to "Dockerfile")
like so:


[Building From a Dockerfile including Repository and Tag](../../from_dockerfile_test.go) inside_block:fromDockerfileIncludingRepo


As you can see, you can also specify the `Repo` and `Tag` optional fields to use for the image. If not passed, the
image will be built with a random name and tag.

If your Dockerfile expects build args: 

```Dockerfile
FROM alpine@sha256:51b67269f354137895d43f3b3d810bfacd3945438e94dc5ac55fdac340352f48

ARG FOO

```
You can specify them like:


[Building From a Dockerfile including build arguments](../../docker_test.go) inside_block:fromDockerfileWithBuildArgs


## Dynamic Build Context

If you would like to send a build context that you created in code (maybe you have a dynamic Dockerfile), you can
send the build context as an `io.Reader` since the Docker Daemon accepts it as a tar file, you can use the [tar](https://golang.org/pkg/archive/tar/) package to create your context.

To do this you would use the `ContextArchive` attribute in the `FromDockerfile` struct.

```go
var buf bytes.Buffer
tarWriter := tar.NewWriter(&buf)
// ... add some files
if err := tarWriter.Close(); err != nil {
	// do something with err
}
reader := bytes.NewReader(buf.Bytes())
fromDockerfile := testcontainers.FromDockerfile{
	ContextArchive: reader,
}
```

**Please Note** if you specify a `ContextArchive` this will cause _Testcontainers for Go_ to ignore the path passed
in to `Context`.

## Ignoring files in the build context

The same as Docker has a `.dockerignore` file to ignore files in the build context, _Testcontainers for Go_ also supports this feature.
A `.dockerignore` living in the root of the build context will be used to filter out files that should not be sent to the Docker daemon.
The `.dockerignore` file won't be sent to the Docker daemon either.

!!! note
    At this moment, _Testcontainers for Go_ does not support Dockerfile-specific `.dockerignore` files.

## Images requiring auth

If you are building a local Docker image that is fetched from a Docker image in a registry requiring authentication
(e.g., assuming you are fetching from a custom registry such as `myregistry.com`), _Testcontainers for Go_ will automatically
discover the credentials for the given Docker image from the Docker config, as described [here](./docker_auth.md).

```go
req := ContainerRequest{
    FromDockerfile: testcontainers.FromDockerfile{
        Context: "/path/to/build/context",
        Dockerfile: "CustomDockerfile",
	},
}
```

## Keeping built images

Per default, built images are deleted after being used.
However, some images you build might have no or only minor changes during development.
Building them for each test run might take a lot of time.
You can avoid this by setting `KeepImage` in `FromDockerfile`.
If the image is being kept, cached layers might be reused during building or even the whole image.

```go
req := ContainerRequest{
    FromDockerfile: testcontainers.FromDockerfile{
        // ...
		KeepImage: true,
	},
}
```

## Advanced usage

In the case you need to pass additional arguments to the `docker build` command, you can use the `BuildOptionsModifier` attribute in the `FromDockerfile` struct.

This field holds a function that has access to Docker's ImageBuildOptions type, which is used to build the image. You can use this modifier **on your own risk** to modify the build options with as many options as you need.


[Building From a Dockerfile including build options modifier](../../from_dockerfile_test.go) inside_block:buildFromDockerfileWithModifier
[Dockerfile including target](../../testdata/target.Dockerfile)

---

### Features Common Functional Options (`docs/features/common_functional_options.md`)

#### Basic Options

##### WithExposedPorts

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

If you need to expose additional ports from the container, you can use `testcontainers.WithExposedPorts`. For example:

```golang
ctr, err := mymodule.Run(ctx, "docker.io/myservice:1.2.3", 
    testcontainers.WithExposedPorts("8080/tcp", "9090/tcp"))
```

##### WithEnv

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.29.0"><span class="tc-version">:material-tag: v0.29.0</span></a>

If you need to either pass additional environment variables to a container or override them, you can use `testcontainers.WithEnv` for example:

```golang
ctr, err = mymodule.Run(ctx, "docker.io/myservice:1.2.3", testcontainers.WithEnv(map[string]string{"FOO": "BAR"}))
```

##### WithWaitStrategy

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>

If you need to set a different wait strategy for the container, you can use `testcontainers.WithWaitStrategy` with a valid wait strategy.

!!!info
    The default deadline for the wait strategy is 60 seconds.

##### WithWaitStrategyAndDeadline

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>

At the same time, it's possible to set a wait strategy and a custom deadline with `testcontainers.WithWaitStrategyAndDeadline`.

##### WithAdditionalWaitStrategy

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.38.0"><span class="tc-version">:material-tag: v0.38.0</span></a>

If you need to add a wait strategy to the existing wait strategy, you can use `testcontainers.WithAdditionalWaitStrategy`.

!!!info
    The default deadline for the wait strategy is 60 seconds.

##### WithAdditionalWaitStrategyAndDeadline

- - Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.38.0"><span class="tc-version">:material-tag: v0.38.0</span></a>

At the same time, it's possible to add a wait strategy and a custom deadline with `testcontainers.WithAdditionalWaitStrategyAndDeadline`.

##### WithEntrypoint

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

If you need to completely replace the container's entrypoint, you can use `testcontainers.WithEntrypoint`. For example:

```golang
ctr, err := mymodule.Run(ctx, "docker.io/myservice:1.2.3", 
    testcontainers.WithEntrypoint("/bin/sh", "-c", "echo hello"))
```

##### WithEntrypointArgs

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

If you need to append commands to the container's entrypoint, you can use `testcontainers.WithEntrypointArgs`. For example:

```golang
ctr, err := mymodule.Run(ctx, "docker.io/myservice:1.2.3", 
    testcontainers.WithEntrypointArgs("echo", "hello"))
```

##### WithCmd

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

If you need to completely replace the container's command, you can use `testcontainers.WithCmd`. For example:

```golang
ctr, err := mymodule.Run(ctx, "docker.io/myservice:1.2.3", 
    testcontainers.WithCmd("echo", "hello"))
```

##### WithCmdArgs

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

If you need to append commands to the container's command, you can use `testcontainers.WithCmdArgs`. For example:

```golang
ctr, err := mymodule.Run(ctx, "docker.io/myservice:1.2.3", 
    testcontainers.WithCmdArgs("echo", "hello"))
```

##### WithLabels

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

If you need to add Docker labels to the container, you can use `testcontainers.WithLabels`. For example:

```golang
ctr, err := mymodule.Run(ctx, "docker.io/myservice:1.2.3", 
    testcontainers.WithLabels(map[string]string{
        "environment": "testing",
        "project":     "myapp",
    }))
```

#### Lifecycle Options

##### WithLifecycleHooks

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.38.0"><span class="tc-version">:material-tag: v0.38.0</span></a>

If you need to set the lifecycle hooks for the container, you can use `testcontainers.WithLifecycleHooks`, which replaces the existing lifecycle hooks with the new ones.

##### WithAdditionalLifecycleHooks

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.38.0"><span class="tc-version">:material-tag: v0.38.0</span></a>

You can also use `testcontainers.WithAdditionalLifecycleHooks`, which appends the new lifecycle hooks to the existing ones.

##### WithStartupCommand

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.25.0"><span class="tc-version">:material-tag: v0.25.0</span></a>

Testcontainers exposes the `WithStartupCommand(e ...Executable)` option to run arbitrary commands in the container right after it's started.

!!!info
    To better understand how this feature works, please read the [Create containers: Lifecycle Hooks](/features/creating_container/#lifecycle-hooks) documentation.

It also exports an `Executable` interface, defining the following methods:

- `AsCommand()`, which returns a slice of strings to represent the command and positional arguments to be executed in the container;
- `Options()`, which returns the slice of functional options with the Docker's ExecConfigs used to create the command in the container (the working directory, environment variables, user executing the command, etc) and the possible output format (Multiplexed).

You could use this feature to run a custom script, or to run a command that is not supported by the module right after the container is started.

##### WithAfterReadyCommand

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.28.0"><span class="tc-version">:material-tag: v0.28.0</span></a>

Testcontainers exposes the `WithAfterReadyCommand(e ...Executable)` option to run arbitrary commands in the container right after it's ready, which happens when the defined wait strategies have finished with success.

!!!info
    To better understand how this feature works, please read the [Create containers: Lifecycle Hooks](/features/creating_container/#lifecycle-hooks) documentation.

It leverages the `Executable` interface to represent the command and positional arguments to be executed in the container.

You could use this feature to run a custom script, or to run a command that is not supported by the module right after the container is ready.

#### Files & Mounts Options

##### WithFiles

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

If you need to copy files into the container, you can use `testcontainers.WithFiles`. For example:

```golang
ctr, err := mymodule.Run(ctx, "docker.io/myservice:1.2.3", 
    testcontainers.WithFiles([]testcontainers.ContainerFile{
        {
            HostFilePath:      "/path/to/local/file.txt",
            ContainerFilePath: "/container/file.txt",
            FileMode:          0o644,
        },
    }))
```

This option allows you to copy files from the host into the container at creation time.

##### WithMounts

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

If you need to add volume mounts to the container, you can use `testcontainers.WithMounts`. For example:

```golang
ctr, err := mymodule.Run(ctx, "docker.io/myservice:1.2.3", 
    testcontainers.WithMounts([]testcontainers.ContainerMount{
        {
            Source: testcontainers.GenericVolumeMountSource{Name: "appdata"},
            Target: "/app/data",
        },
    }))
```

##### WithTmpfs

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

If you need to add tmpfs mounts to the container, you can use `testcontainers.WithTmpfs`. For example:

```golang
ctr, err := mymodule.Run(ctx, "docker.io/myservice:1.2.3", 
    testcontainers.WithTmpfs(map[string]string{
        "/tmp": "size=100m",
        "/run": "size=100m",
    }))
```

##### WithImageMount

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

Since Docker v28, it's possible to mount an image to a container, passing the source image name, the relative subpath to mount in that image, and the mount point in the target container.

This option validates that the subpath is a relative path, raising an error otherwise.


[Image Mount](../../modules/ollama/examples_test.go) inside_block:mountImage


In the code above, which mounts the directory in which Ollama models are stored, the `targetImage` is the name of the image containing the models (an Ollama image where the models are already pulled).

!!!warning
    Using this option fails the creation of the container if the underlying container runtime does not support the `image mount` feature.

#### Build Options

##### WithDockerfile

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

Testcontainers exposes the `testcontainers.WithDockerfile` option to build a container from a Dockerfile.
The functional option receives a `testcontainers.FromDockerfile` struct that is applied to the container request before starting the container. As a result, the container is built and started in one go.

```golang
df := testcontainers.FromDockerfile{
	Context:    ".",
	Dockerfile: "Dockerfile",
	Repo:       "testcontainers",
	Tag:        "latest",
	BuildArgs:  map[string]*string{"ARG1": nil, "ARG2": nil},
}   

ctr, err := mymodule.Run(ctx, "docker.io/myservice:1.2.3", testcontainers.WithDockerfile(df))
```

#### Logging Options

##### WithLogConsumers

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.28.0"><span class="tc-version">:material-tag: v0.28.0</span></a>

If you need to consume the logs of the container, you can use `testcontainers.WithLogConsumers` with a valid log consumer. An example of a log consumer is the following:

```golang
type TestLogConsumer struct {
	Msgs []string
}

func (g *TestLogConsumer) Accept(l Log) {
	g.Msgs = append(g.Msgs, string(l.Content))
}
```

##### WithLogConsumerConfig

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.38.0"><span class="tc-version">:material-tag: v0.38.0</span></a>

If you need to set the log consumer config for the container, you can use `testcontainers.WithLogConsumerConfig`. This option completely replaces the existing log consumer config, including the log consumers and the log production options.

##### WithLogger

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.29.0"><span class="tc-version">:material-tag: v0.29.0</span></a>

If you need to either pass logger to a container, you can use `testcontainers.WithLogger`.

!!!info
	Consider calling this before other "With" functions as these may generate logs.

In this example we also use the testcontainers-go `log.TestLogger`, which writes to the passed in `testing.TB` using `Logf`.
The result is that we capture all logging from the container into the test context meaning its
hidden behind `go test -v` and is associated with the relevant test, providing the user with
useful context instead of appearing out of band.

```golang
func TestHandler(t *testing.T) {
    logger := log.TestLogger(t)
    ctr, err := mymodule.Run(ctx, "docker.io/myservice:1.2.3", testcontainers.WithLogger(logger))
    CleanupContainer(t, ctr)
    require.NoError(t, err)
    // Do something with container.
}
```

Please read the [Following Container Logs](/features/follow_logs) documentation for more information about creating log consumers.

#### Image Options

##### WithAlwaysPull

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.38.0"><span class="tc-version">:material-tag: v0.38.0</span></a>

If you need to pull the image before starting the container, you can use `testcontainers.WithAlwaysPull()`.

##### WithImageSubstitutors

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.26.0"><span class="tc-version">:material-tag: v0.26.0</span></a>

In more locked down / secured environments, it can be problematic to pull images from Docker Hub and run them without additional precautions.

An image name substitutor converts a Docker image name, as may be specified in code, to an alternative name. This is intended to provide a way to override image names, for example to enforce pulling of images from a private registry.

_Testcontainers for Go_ exposes an interface to perform this operation: `ImageSubstitutor`, and a No-operation implementation to be used as reference for custom implementations:


[Image Substitutor Interface](../../options.go) inside_block:imageSubstitutor
[Noop Image Substitutor](../../container_test.go) inside_block:noopImageSubstitutor


Using the `WithImageSubstitutors` options, you could define your own substitutions to the container images. E.g. adding a prefix to the images so that they can be pulled from a Docker registry other than Docker Hub. This is the usual mechanism for using Docker image proxies, caches, etc.

##### WithImagePlatform

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.38.0"><span class="tc-version">:material-tag: v0.38.0</span></a>

If you need to set the platform for a container, you can use `testcontainers.WithImagePlatform(platform string)`.

#### Networking Options

##### WithNetwork

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.27.0"><span class="tc-version">:material-tag: v0.27.0</span></a>

By default, the container is started in the default Docker network. If you want to use an already existing Docker network you created in your code, you can use the `network.WithNetwork(aliases []string, nw *testcontainers.DockerNetwork)` option, which receives an alias as parameter and your network, attaching the container to it, and setting the network alias for that network.

In the case you need to retrieve the network name, you can simply read it from the struct's `Name` field. E.g. `nw.Name`.

!!!warning
    This option is not checking whether the network exists or not. If you use a network that doesn't exist, the container will start in the default Docker network, as in the default behavior.

##### WithNetworkByName

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.38.0"><span class="tc-version">:material-tag: v0.38.0</span></a>

If you want to attach your containers to an already existing Docker network by its name, you can use the `network.WithNetworkName(aliases []string, networkName string)` option, which receives an alias as parameter and the network name, attaching the container to it, and setting the network alias for that network.

!!!warning
    In case the network name is `bridge`, no aliases are set. This is because network-scoped alias is supported only for containers in user defined networks.

##### WithBridgeNetwork

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.38.0"><span class="tc-version">:material-tag: v0.38.0</span></a>

If you want to attach your containers to the `bridge` network, you can use the `network.WithBridgeNetwork()` option.

!!!warning
    The `bridge` network is the default network for Docker. It's not a user defined network, so it doesn't support network-scoped aliases.

##### WithNewNetwork

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.27.0"><span class="tc-version">:material-tag: v0.27.0</span></a>

If you want to attach your containers to a throw-away network, you can use the `network.WithNewNetwork(ctx context.Context, aliases []string, opts ...network.NetworkCustomizer)` option, which receives an alias as parameter, creating the new network with a random name, attaching the container to it, and setting the network alias for that network.

In the case you need to retrieve the network name, you can use the `Networks(ctx)` method of the `Container` interface, right after it's running, which returns a slice of strings with the names of the networks where the container is attached.

#### Advanced Options

##### WithHostPortAccess

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.31.0"><span class="tc-version">:material-tag: v0.31.0</span></a>

If you need to access a port that is already running in the host, you can use `testcontainers.WithHostPortAccess` for example:

```golang
ctr, err = mymodule.Run(ctx, "docker.io/myservice:1.2.3", testcontainers.WithHostPortAccess(8080))
```

To understand more about this feature, please read the [Exposing host ports to the container](/features/networking/#exposing-host-ports-to-the-container) documentation.

##### WithConfigModifier

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>
- Chainable since <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>

If you need an advanced configuration for the container, modifying the container's configuration, you can use the `testcontainers.WithConfigModifier` option, which gives access to the underlying Docker's Config type.

This option can be called multiple times; each modifier is chained and applied in order, with the last call applied last.

##### WithHostConfigModifier

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>
- Chainable since <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>

If you need an advanced configuration for the container, modifying the container's host configuration, you can use the `testcontainers.WithHostConfigModifier` option, which gives access to the underlying Docker's HostConfig type.

This option can be called multiple times; each modifier is chained and applied in order, with the last call applied last.

##### WithEndpointSettingsModifier

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>
- Chainable since <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>

If you need an advanced configuration for the container, modifying the container's endpoint settings, you can use the `testcontainers.WithEndpointSettingsModifier` option, which gives access to the underlying Docker's EndpointSettings type.

This option can be called multiple times; each modifier is chained and applied in order, with the last call applied last.

##### CustomizeRequest

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>

This option will merge the customized request into the module's own `ContainerRequest`.

```go
ctr, err := mymodule.Run(ctx, "docker.io/myservice:1.2.3",
    /* Other module options */
    testcontainers.CustomizeRequest(testcontainers.GenericContainerRequest{
        ContainerRequest: testcontainers.ContainerRequest{
            Cmd: []string{"-c", "log_statement=all"},
        },
    }),
)
```

The above example is updating the predefined command of the image, **appending** them to the module's command.

!!!info
    This can't be used to replace the command, only to append options.

##### WithName

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.38.0"><span class="tc-version">:material-tag: v0.38.0</span></a>

If you need to set the name of the container, you can use the `testcontainers.WithName` option.

```golang
ctr, err := mymodule.Run(ctx, "docker.io/myservice:1.2.3", 
    testcontainers.WithName("my-container-name"),
)
```

!!!warning
    This option is not checking whether the container name is already in use. If you use a name that is already in use, an error is returned.
    At the same time, we discourage using this option as it might lead to unexpected behavior, but we understand that in some cases it might be useful.

##### WithNoStart

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.38.0"><span class="tc-version">:material-tag: v0.38.0</span></a>

If you need to prevent the container from being started after creation, you can use the `testcontainers.WithNoStart` option.

##### WithProvider

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.39.0"><span class="tc-version">:material-tag: v0.39.0</span></a>

If you need specify which provider to use to run the container,  you can use the `testcontainers.WithProvider` option.
Currently only `docker` or `podman` are supported. 

#### Experimental Options

##### WithReuseByName

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

This option marks a container to be reused if it exists or create a new one if it doesn't.
With the current implementation, the container name must be provided to identify the container to be reused.

```golang
ctr, err := mymodule.Run(ctx, "docker.io/myservice:1.2.3", 
    testcontainers.WithReuseByName("my-container-name"),
)
```

!!!warning
    Reusing a container is experimental and the API is subject to change for a more robust implementation that is not based on container names.

---

### Features Common Functional Options List (`docs/features/common_functional_options_list.md`)

The following options are exposed by the `testcontainers` package.

### Basic Options

- [`WithExposedPorts`](/features/creating_container/#withexposedports) Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>
- [`WithEnv`](/features/creating_container/#withenv) Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.29.0"><span class="tc-version">:material-tag: v0.29.0</span></a>
- [`WithWaitStrategy`](/features/creating_container/#withwaitstrategy) Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>
- [`WithAdditionalWaitStrategy`](/features/creating_container/#withadditionalwaitstrategy) Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.38.0"><span class="tc-version">:material-tag: v0.38.0</span></a>
- [`WithWaitStrategyAndDeadline`](/features/creating_container/#withwaitstrategyanddeadline) Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>
- [`WithAdditionalWaitStrategyAndDeadline`](/features/creating_container/#withadditionalwaitstrategyanddeadline) Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.38.0"><span class="tc-version">:material-tag: v0.38.0</span></a>
- [`WithEntrypoint`](/features/creating_container/#withentrypoint) Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>
- [`WithEntrypointArgs`](/features/creating_container/#withentrypointargs) Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>
- [`WithCmd`](/features/creating_container/#withcmd) Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>
- [`WithCmdArgs`](/features/creating_container/#withcmdargs) Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>
- [`WithLabels`](/features/creating_container/#withlabels) Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

### Lifecycle Options

- [`WithLifecycleHooks`](/features/creating_container/#withlifecyclehooks) Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.38.0"><span class="tc-version">:material-tag: v0.38.0</span></a>
- [`WithAdditionalLifecycleHooks`](/features/creating_container/#withadditionallifecyclehooks) Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.38.0"><span class="tc-version">:material-tag: v0.38.0</span></a>
- [`WithStartupCommand`](/features/creating_container/#withstartupcommand) Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.25.0"><span class="tc-version">:material-tag: v0.25.0</span></a>
- [`WithAfterReadyCommand`](/features/creating_container/#withafterreadycommand) Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.28.0"><span class="tc-version">:material-tag: v0.28.0</span></a>

### Files & Mounts Options

- [`WithFiles`](/features/creating_container/#withfiles) Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>
- [`WithMounts`](/features/creating_container/#withmounts) Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>
- [`WithTmpfs`](/features/creating_container/#withtmpfs) Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>
- [`WithImageMount`](/features/creating_container/#withimagemount) Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

### Build Options

- [`WithDockerfile`](/features/creating_container/#withdockerfile) Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

### Logging Options

- [`WithLogConsumers`](/features/creating_container/#withlogconsumers) Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.28.0"><span class="tc-version">:material-tag: v0.28.0</span></a>
- [`WithLogConsumerConfig`](/features/creating_container/#withlogconsumerconfig) Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.38.0"><span class="tc-version">:material-tag: v0.38.0</span></a>
- [`WithLogger`](/features/creating_container/#withlogger) Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.29.0"><span class="tc-version">:material-tag: v0.29.0</span></a>

### Image Options

- [`WithAlwaysPull`](/features/creating_container/#withalwayspull) Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.38.0"><span class="tc-version">:material-tag: v0.38.0</span></a>
- [`WithImageSubstitutors`](/features/creating_container/#withimagesubstitutors) Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.26.0"><span class="tc-version">:material-tag: v0.26.0</span></a>
- [`WithImagePlatform`](/features/creating_container/#withimageplatform) Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.38.0"><span class="tc-version">:material-tag: v0.38.0</span></a>

### Networking Options

- [`WithNetwork`](/features/creating_container/#withnetwork) Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.27.0"><span class="tc-version">:material-tag: v0.27.0</span></a>
- [`WithNetworkByName`](/features/creating_container/#withnetworkbyname) Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.38.0"><span class="tc-version">:material-tag: v0.38.0</span></a>
- [`WithBridgeNetwork`](/features/creating_container/#withbridgenetwork) Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.38.0"><span class="tc-version">:material-tag: v0.38.0</span></a>
- [`WithNewNetwork`](/features/creating_container/#withnewnetwork) Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.27.0"><span class="tc-version">:material-tag: v0.27.0</span></a>

### Advanced Options

- [`WithHostPortAccess`](/features/creating_container/#withhostportaccess) Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.31.0"><span class="tc-version">:material-tag: v0.31.0</span></a>
- [`WithConfigModifier`](/features/creating_container/#withconfigmodifier) Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a> · Chainable since <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
- [`WithHostConfigModifier`](/features/creating_container/#withhostconfigmodifier) Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a> · Chainable since <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
- [`WithEndpointSettingsModifier`](/features/creating_container/#withendpointsettingsmodifier) Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a> · Chainable since <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>
- [`CustomizeRequest`](/features/creating_container/#customizerequest) Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>
- [`WithName`](/features/creating_container/#withname) Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.38.0"><span class="tc-version">:material-tag: v0.38.0</span></a>
- [`WithNoStart`](/features/creating_container/#withnostart) Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.38.0"><span class="tc-version">:material-tag: v0.38.0</span></a>
- [`WithProvider`](/features/creating_container/#withprovider) Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.39.0"><span class="tc-version">:material-tag: v0.39.0</span></a>


### Experimental Options

- [`WithReuseByName`](/features/creating_container/#withreusebyname) Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

---

### Features Configuration (`docs/features/configuration.md`)

# Custom configuration

You can override some default properties if your environment requires that.

## Configuration locations
The configuration will be loaded from multiple locations. Properties are considered in the following order:

1. Environment variables
2. `.testcontainers.properties` in user's home folder. Example locations:  
**Linux:** `/home/myuser/.testcontainers.properties`  
**Windows:** `C:/Users/myuser/.testcontainers.properties`  
**macOS:** `/Users/myuser/.testcontainers.properties`

Note that when using environment variables, configuration property names should be set in upper 
case with underscore separators, preceded by `TESTCONTAINERS_` - e.g. `ryuk.disabled` becomes 
`TESTCONTAINERS_RYUK_DISABLED`.

### Supported properties

_Testcontainers for Go_ provides a struct type to represent the configuration:


[Supported properties](../../internal/config/config.go) inside_block:testcontainersConfig


You can read it with the `ReadConfig()` function:

```go
cfg := testcontainers.ReadConfig()
```

For advanced users, the Docker host connection can be configured **via configuration** in `~/.testcontainers.properties`, but environment variables will take precedence.
Please see [Docker host detection](#docker-host-detection) for more information.

The example below illustrates how to configure the Docker host connection via properties file:

```properties
docker.host=tcp://my.docker.host:1234       # Equivalent to the DOCKER_HOST environment variable.
docker.tls.verify=1                         # Equivalent to the DOCKER_TLS_VERIFY environment variable
docker.cert.path=/some/path                 # Equivalent to the DOCKER_CERT_PATH environment variable
```

## Customizing images

Please read more about customizing images in the [Image name substitution](image_name_substitution.md) section.

## Customizing Ryuk, the resource reaper

1. Ryuk must be started as a privileged container. For that, you can set the `TESTCONTAINERS_RYUK_CONTAINER_PRIVILEGED` **environment variable**, or the  `ryuk.container.privileged` **property** to `true`.
1. If your environment already implements automatic cleanup of containers after the execution,
but does not allow starting privileged containers, you can turn off the Ryuk container by setting
`TESTCONTAINERS_RYUK_DISABLED` **environment variable** , or the  `ryuk.disabled` **property** to `true`.
1. You can specify the connection timeout for Ryuk by setting the `RYUK_CONNECTION_TIMEOUT` **environment variable**, or the `ryuk.connection.timeout` **property**. The default value is 1 minute.
1. You can specify the reconnection timeout for Ryuk by setting the `RYUK_RECONNECTION_TIMEOUT` **environment variable**, or the `ryuk.reconnection.timeout` **property**. The default value is 10 seconds.
1. You can configure Ryuk to run in verbose mode by setting any of the `ryuk.verbose` **property** or the `RYUK_VERBOSE` **environment variable**. The default value is `false`.

!!!info
    For more information about Ryuk, see [Garbage Collector](garbage_collector.md).

!!!warn
    If using Ryuk and the Compose module, please increase the `ryuk.connection.timeout` to at least 5 minutes.
    This is because the Compose module may take longer to start all the services. Besides, the `ryuk.reconnection.timeout`
    should be increased to at least 30 seconds. For further information, please check [https://github.com/testcontainers/testcontainers-go/pull/2485](https://github.com/testcontainers/testcontainers-go/pull/2485).

!!!warn
    The following environment variables for configuring Ryuk have been deprecated:
    `TESTCONTAINERS_RYUK_CONNECTION_TIMEOUT`, `TESTCONTAINERS_RYUK_RECONNECTION_TIMEOUT` and
    `TESTCONTAINERS_RYUK_VERBOSE` have been replaced by `RYUK_CONNECTION_TIMEOUT`
    `RYUK_RECONNECTION_TIMEOUT` and `RYUK_VERBOSE` respectively.

## Docker host detection

_Testcontainers for Go_ will attempt to detect the Docker environment and configure everything to work automatically.

However, sometimes customization is required. _Testcontainers for Go_ will respect the following order:

1. Read the **tc.host** property in the `~/.testcontainers.properties` file. E.g. `tc.host=tcp://my.docker.host:1234`

2. Read the **DOCKER_HOST** environment variable. E.g. `DOCKER_HOST=unix:///var/run/docker.sock`
See [Docker environment variables](https://docs.docker.com/engine/reference/commandline/cli/#environment-variables) for more information.

3. Read the Go context for the **DOCKER_HOST** key. E.g. `ctx.Value("DOCKER_HOST")`. This is used internally for the library to pass the Docker host to the resource reaper.

4. Read the default Docker socket path, without the unix schema. E.g. `/var/run/docker.sock`

5. Read the **docker.host** property in the `~/.testcontainers.properties` file. E.g. `docker.host=tcp://my.docker.host:1234`

6. Read the rootless Docker socket path, checking in the following alternative locations:
    1. `${XDG_RUNTIME_DIR}/.docker/run/docker.sock`.
    2. `${HOME}/.docker/run/docker.sock`.
    3. `${HOME}/.docker/desktop/docker.sock`.
    4. `/run/user/${UID}/docker.sock`, where `${UID}` is the user ID of the current user.

7. The library panics if none of the above are set, meaning that the Docker host was not detected.

## Docker socket path detection

_Testcontainers for Go_ will attempt to detect the Docker socket path and configure everything to work automatically.

However, sometimes customization is required. _Testcontainers for Go_ will respect the following order:

1. Read the **tc.host** property in the `~/.testcontainers.properties` file. E.g. `tc.host=tcp://my.docker.host:1234`. If this property is set, the returned Docker socket path
will be the default Docker socket path: `/var/run/docker.sock`.

2. Read the **TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE** environment variable.
Path to Docker's socket. Used by Ryuk, Docker Compose, and a few other containers that need to perform Docker actions.  

    Example: `/var/run/docker-alt.sock`

3. If the Operative System retrieved by the Docker client is "Docker Desktop", and the host is running on Windows, it will return the `//var/run/docker.sock` UNC Path. Else return the default docker socket path for rootless docker.

4. Get the current Docker Host from the existing strategies: see [Docker host detection](#docker-host-detection).

5. If the socket contains the unix schema, the schema is removed (e.g. `unix:///var/run/docker.sock` -> `/var/run/docker.sock`)

6. Else, the default location of the docker socket is used: `/var/run/docker.sock`

The library panics if the Docker host cannot be discovered.

---

### Features Creating Container (`docs/features/creating_container.md`)

# How to create a container

Testcontainers are a wrapper around the Docker daemon designed for tests. Anything you can run in Docker, you can spin
up with Testcontainers and integrate into your tests:

* NoSQL databases or other data stores (e.g. Redis, ElasticSearch, MongoDB)
* Web servers/proxies (e.g. NGINX, Apache)
* Log services (e.g. Logstash, Kibana)
* Other services developed by your team/organization which are already dockerized

## Run

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

`testcontainers.Run` defines the container that should be run, similar to the `docker run` command.

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

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

The following test creates an NGINX container on both the `bridge` (docker default
network) and the `foo` network and validates that it returns 200 for the status code.

It also demonstrates how to use `CleanupContainer`, which ensures that the nginx container
is removed when the test ends even if the underlying container errored,
as well as the `CleanupNetwork` which does the same for networks.

The alternatives for these outside of tests as a `defer` are `TerminateContainer`
and `Network.Remove` which can be seen in the examples.


[Creating a container](../../examples_test.go) inside_block:ExampleRun


## Customizing the container

{% include "../features/common_functional_options.md" %}

## GenericContainer

!!!warning
	`GenericContainer` is the old way to create a container, and we recommend using `Run` instead,
	as it could be deprecated in the future.

`testcontainers.GenericContainer` defines the container that should be run, similar to the `docker run` command.

The following test creates an NGINX container on both the `bridge` (docker default
network) and the `foo` network and validates that it returns 200 for the status code.

It also demonstrates how to use `CleanupContainer`, which ensures that the nginx container
is removed when the test ends even if the underlying `GenericContainer` errored,
as well as the `CleanupNetwork` which does the same for networks.

The alternatives for these outside of tests as a `defer` are `TerminateContainer`
and `Network.Remove` which can be seen in the examples.

```
/* Detailed source-code truncated for AI context efficiency. */
```

### Lifecycle hooks

_Testcontainers for Go_ allows you to define your own lifecycle hooks for better control over your containers. You just need to define functions that return an error and receive the Go context as the first argument.

You'll be able to pass multiple lifecycle hooks using the `WithLifecycleHooks` and `WithAdditionalLifecycleHooks` options, passing an array of `testcontainers.ContainerLifecycleHooks`. The first one replaces the existing lifecycle hooks with the new ones, while the second one appends the new lifecycle hooks to the existing ones.

The `testcontainers.ContainerLifecycleHooks` struct defines the following lifecycle hooks, each of them backed by an array of functions representing the hooks:

* `PreBuilds` - hooks that are executed before the image is built. This hook is only available when creating a container from a Dockerfile
* `PostBuilds` - hooks that are executed after the image is built. This hook is only available when creating a container from a Dockerfile
* `PreCreates` - hooks that are executed before the container is created
* `PostCreates` - hooks that are executed after the container is created
* `PreStarts` - hooks that are executed before the container is started
* `PostStarts` - hooks that are executed after the container is started
* `PostReadies` - hooks that are executed after the container is ready
* `PreStops` - hooks that are executed before the container is stopped
* `PostStops` - hooks that are executed after the container is stopped
* `PreTerminates` - hooks that are executed before the container is terminated
* `PostTerminates` - hooks that are executed after the container is terminated

_Testcontainers for Go_ defines some default lifecycle hooks that are always executed in a specific order with respect to the user-defined hooks. The order of execution is the following:

1. default `pre` hooks.
2. user-defined `pre` hooks.
3. user-defined `post` hooks.
4. default `post` hooks.

Inside each group, the hooks will be executed in the order they were defined.

!!!info
	The default hooks are for logging (applied to all hooks), customising the Docker config (applied to the pre-create hook), copying files in to the container (applied to the post-create hook), adding log consumers (applied to the post-start and pre-terminate hooks), and running the wait strategies as a readiness check (applied to the post-start hook).

It's important to note that the `Readiness` of a container is defined by the wait strategies configured for the container. **This hook is executed right after the `PostStarts` hook**. If you want additional readiness checks, add a `PostReadies` hook, which runs after the default ones. The `PostStarts` hooks do not imply readiness; don't rely on them for that.

!!!warning
	Up to `v0.37.0`, the readiness hook included checks for all the exposed ports to be ready. This is not the case anymore, and the readiness hook only uses the wait strategies defined for the container to determine if the container is ready.

In the following example, we are going to create a container using all the lifecycle hooks, all of them printing a message when any of the lifecycle hooks is called:


[Extending container with lifecycle hooks](../../lifecycle_test.go) inside_block:optsWithLifecycleHooks


#### Default Logging Hook

_Testcontainers for Go_ comes with a default logging hook that will print a log message for each container lifecycle event, using the default logger. You can add your own logger by passing the `testcontainers.DefaultLoggingHook` option to the `Run` options, passing a reference to your preferred logger:


[Use a custom logger for container hooks](../../lifecycle_test.go) inside_block:optsWithDefaultLoggingHook
[Custom Logger implementation](../../lifecycle_test.go) inside_block:customLoggerImplementation


### Advanced Settings

The aforementioned `Run` function represents a straightforward way to configure containers, but you may need more advanced settings regarding the Docker config, host config, and endpoint settings types. For those advanced settings, _Testcontainers for Go_ offers a way to fully customize the container and those internal Docker types. These customisations, called _modifiers_, are applied just before the internal call to the Docker client to create the container.


[Using modifiers](../../lifecycle_test.go) inside_block:reqWithModifiers


!!!warning
	The only special case where the modifiers are not applied last, is when there are no exposed ports and the container does not use a network mode from a container (e.g. `req.NetworkMode = container.NetworkMode("container:$CONTAINER_ID")`). In that case, _Testcontainers for Go_ will extract the ports from the underlying Docker image and export them.

## Reusable container

Using the `WithReuseByName` option you can reuse an existing container. Reuse works only when you provide an
existing container name to this option. If the name is not found among existing containers,
the function will create a new container. If the name is empty, an error is returned.

The following test creates an NGINX container, adds a file into it and then reuses the container again for checking the file:

```
/* Detailed source-code truncated for AI context efficiency. */
```

## Parallel running

`testcontainers.ParallelContainers` - defines the containers that should be run in parallel mode.

The following test creates two NGINX containers in parallel:

```go
package main

import (
    "context"
    "fmt"
    "log"

    "github.com/testcontainers/testcontainers-go"
)

func main() {
    ctx := context.Background()

    requests := testcontainers.ParallelContainerRequest{
        {
            ContainerRequest: testcontainers.ContainerRequest{

                Image: "nginx",
                ExposedPorts: []string{
                    "10080/tcp",
                },
            },
            Started: true,
        },
        {
            ContainerRequest: testcontainers.ContainerRequest{

                Image: "nginx",
                ExposedPorts: []string{
                    "10081/tcp",
                },
            },
            Started: true,
        },
    }

    res, err := testcontainers.ParallelContainers(ctx, requests, testcontainers.ParallelContainersOptions{})
    for _, c := range res {
        c := c
        defer func() {
            if err := testcontainers.TerminateContainer(c); err != nil {
                log.Printf("failed to terminate container: %s", c)
            }
        }()
    }

    if err != nil {
        e, ok := err.(testcontainers.ParallelContainersError)
        if !ok {
            log.Printf("unknown error: %v", err)
            return
        }

        for _, pe := range e.Errors {
            fmt.Println(pe.Request, pe.Error)
        }
        return
    }
}
```

---

### Features Docker Auth (`docs/features/docker_auth.md`)

# Authentication with Docker

Sometimes the Docker images you use live in a private Docker registry. For that reason, _Testcontainers for Go_ gives you the ability to read the Docker configuration
and retrieve the authentication for a given registry. To achieve it, _Testcontainers for Go_ will internally check, in this particular order:
	
1. the `DOCKER_AUTH_CONFIG` environment variable, unmarshalling the string value from its JSON representation and using it as the Docker config.
2. the `DOCKER_CONFIG` environment variable, as an alternative path to the Docker config file.
3. else it will load the default Docker config file, which lives in the user's home, e.g. `~/.docker/config.json`
4. it will use the right Docker credential helper to retrieve the authentication (user, password and base64 representation) for the given registry.

To understand how the Docker credential helpers work, please refer to the [official documentation](https://docs.docker.com/engine/reference/commandline/login/#credential-helpers).

!!! info
	_Testcontainers for Go_ uses [https://github.com/cpuguy83/dockercfg](https://github.com/cpuguy83/dockercfg) to retrieve the authentication from the credential helpers.

_Testcontainers for Go_ will automatically discover the credentials for a given Docker image from the Docker config, as described above. For that, it will extract the Docker registry from the image name, and for that registry will try to locate the authentication in the Docker config, returning an empty string if the registry is not found. As a consequence, all the fields to pass credentials to the container request will be deprecated.

```go
req := ContainerRequest{
	Image: "myregistry.com/myimage:latest",
}
```

In the case you are building an image from the Dockerfile, the authentication will be automatically retrieved from the Docker config, so you don't need to pass it explicitly:


[Building From a Dockerfile does not need Auth credentials anymore](../../docker_test.go) inside_block:fromDockerfileWithBuildArgs

---

### Features Docker Compose (`docs/features/docker_compose.md`)

# Using Docker Compose

Similar to generic containers support, it's also possible to run a bespoke set
of services specified in a docker-compose.yml file.

This is intended to be useful on projects where Docker Compose is already used
in dev or other environments to define services that an application may be
dependent upon.

## Using `docker compose` directly

!!!warning
	The minimal version of Go required to use this module is **1.26**.

```
go get github.com/testcontainers/testcontainers-go/modules/compose
```

Because `compose` v2 is implemented in Go it's possible for _Testcontainers for Go_ to
use [`github.com/docker/compose`](https://github.com/docker/compose) directly and skip any process execution/_docker-compose-in-a-container_ scenario.
The `ComposeStack` API exposes this variant of using `docker compose` in an easy way.

Before using the Compose module, there is some configuration that needs to be applied first.
It customizes the behaviour of the `Ryuk` container, which is used to clean up the resources created by the `docker compose` stack.
Please refer to [the Ryuk configuration](../configuration/#customizing-ryuk-the-resource-reaper) for more information.

### Usage

Use the advanced `NewDockerComposeWith(...)` constructor allowing you to customise the compose execution with options:

- `StackIdentifier`: the identifier for the stack, which is used to name the network and containers. If not passed, a random identifier is generated.
- `WithStackFiles`: specify the Docker Compose stack files to use, as a variadic argument of string paths where the stack files are located.
- `WithStackReaders`: specify the Docker Compose stack files to use, as a variadic argument of `io.Reader` instances. It will create a temporary file in the temp dir of the given O.S., that will be removed after the `Down` method is called. You can use both `WithComposeStackFiles` and `WithComposeStackReaders` at the same time.


[Define Compose File](../../modules/compose/compose_examples_test.go) inside_block:defineComposeFile
[Define Options](../../modules/compose/compose_examples_test.go) inside_block:defineStackWithOptions
[Start Compose Stack](../../modules/compose/compose_examples_test.go) inside_block:upComposeStack
[Get Service Names](../../modules/compose/compose_examples_test.go) inside_block:getServiceNames
[Get Service Container](../../modules/compose/compose_examples_test.go) inside_block:getServiceContainer


#### Compose Up options

- `Recreate`: recreate the containers. If any other value than `api.RecreateNever`, `api.RecreateForce` or `api.RecreateDiverged` is provided, the default value `api.RecreateForce` will be used.
- `RecreateDependencies`: recreate dependent containers. If any other value than `api.RecreateNever`, `api.RecreateForce` or `api.RecreateDiverged` is provided, the default value `api.RecreateForce` will be used.
- `RemoveOrphans`: remove orphaned containers when the stack is upped.
- `Wait`: will wait until the containers reached the running|healthy state.

#### Compose Down options

- `RemoveImages`: remove images after the stack is stopped. The `RemoveImagesAll` option will remove all images, while `RemoveImagesLocal` will remove only the images that don't have a tag.
- `RemoveOrphans`: remove orphaned containers after the stack is stopped.
- `RemoveVolumes`: remove volumes after the stack is stopped.

### Interacting with compose services

To interact with service containers after a stack was started it is possible to get a `*testcontainers.DockerContainer` instance via the `ServiceContainer(...)` function.
The function takes a **service name** (and a `context.Context`) and returns either a `*testcontainers.DockerContainer` or an `error`.

Furthermore, there's the convenience function `Services()` to get a list of all services **defined** by the current project.
Note that not all of them need necessarily be correctly started as the information is based on the given compose files.

### Wait strategies

Just like with the containers created by _Testcontainers for Go_, you can also apply wait strategies to `docker compose` services.
The `ComposeStack.WaitForService(...)` function allows you to apply a wait strategy to **a service by name**.
All wait strategies are executed in parallel to both improve startup performance by not blocking too long and to fail
early if something's wrong.

#### Example


[Compose Example](../../modules/compose/compose_examples_test.go) inside_block:ExampleNewDockerComposeWith_waitForService


### Compose environment

`docker compose` supports expansion based on environment variables.
The `ComposeStack` supports this as well in two different variants:

- `ComposeStack.WithEnv(m map[string]string) ComposeStack` to parameterize stacks from your test code
- `ComposeStack.WithOsEnv() ComposeStack` to parameterize tests from the OS environment e.g. in CI environments

### Docs

Also have a look at [ComposeStack](https://pkg.go.dev/github.com/testcontainers/testcontainers-go#ComposeStack) docs for
further information.

## Usage of the deprecated Local `docker compose` binary

!!! warning
    This API is deprecated and superseded by `ComposeStack` which takes advantage of `compose` v2 being
    implemented in Go as well by directly using the upstream project.

You can override Testcontainers' default behaviour and make it use a
docker compose binary installed on the local machine. This will generally yield
an experience that is closer to running docker compose locally, with the caveat
that Docker Compose needs to be present on dev and CI machines.

### Examples


[Invoke Example](../../modules/compose/compose_local_examples_test.go) inside_block:ExampleLocalDockerCompose_Invoke


Note that the environment variables in the `env` map will be applied, if
possible, to the existing variables declared in the Docker Compose file.

In the following example, we demonstrate how to stop a Docker Compose created project using the
convenient `Down` method.


[Down Example](../../modules/compose/compose_local_examples_test.go) inside_block:ExampleLocalDockerCompose_Down

---

### Features Files And Mounts (`docs/features/files_and_mounts.md`)

# Copying data into a container

Copying data of any type into a container is a very common practice when working with containers. This section will show you how to do it using _Testcontainers for Go_.

## Copying files to a container

If you would like to copy a file to a container, you can do it in two different manners:

1. Adding a list of files in the `ContainerRequest`, which will be copied before the container starts:


[Copying a list of files](../../docker_files_test.go) inside_block:copyFileOnCreate


The `ContainerFile` struct will accept the following fields:

- `HostFilePath`: the path to the file in the host machine. Optional (see below).
- `Reader`: a `io.Reader` that will be used to copy the file to the container. Optional.
- `ContainerFilePath`: the path to the file in the container. Mandatory.
- `Mode`: the file mode, which is optional.

!!!info
    If the `Reader` field is set, the `HostFilePath` field will be ignored.

2. Using the `CopyFileToContainer` method on a `running` container:


[Copying files to a running container](../../docker_files_test.go) inside_block:copyFileAfterCreate
[Wait for hello](../../testdata/waitForHello.sh)


## Copying directories to a container

It's also possible to copy an entire directory to a container, and that can happen before and/or after the container gets into the `Running` state. As an example, you could need to bulk-copy a set of files, such as a configuration directory that does not exist in the underlying Docker image.

It's important to notice that, when copying the directory to the container, the container path must exist in the Docker image. And this is a strong requirement for files to be copied _before_ the container is started, as we cannot create the full path at that time.

You can leverage the very same mechanism used for copying files to a container, but for directories:

1. The first way is using the `Files` field in the `ContainerRequest` struct, as shown in the previous section, but using the path of a directory as `HostFilePath`. Like so:


[Copying a directory using files](../../docker_files_test.go) inside_block:copyDirectoryToContainer


2. The second way uses the existing `CopyFileToContainer` method, which will internally check if the host path is a directory, calling the `CopyDirToContainer` method if needed:


[Copying a directory to a running container](../../docker_files_test.go) inside_block:copyDirectoryToRunningContainerAsFile


3. The last third way uses the `CopyDirToContainer` method, directly, which, as you probably know, needs the existence of the parent directory in order to copy the directory:


[Copying a directory to a running container](../../docker_files_test.go) inside_block:copyDirectoryToRunningContainerAsDir


## Copying files from a container

It's also possible to copy files from a container to the host machine. This can be done by using the `CopyFileFromContainer` method on the `Container` type, which will return an error and an `io.ReadCloser` that you can use to read the file content.


[Copying a file from a container](../../examples_test.go) inside_block:copyFileFromContainer


In the above example, we previously copied the file `/tmp/file.txt` to the container, and then we copied it back to the host machine, reading the content of the file.

## Volume mapping

It is possible to map a Docker volume into the container using the `Mounts` attribute at the `ContainerRequest` struct. For that, please pass an instance of the `GenericVolumeMountSource` type, which allows you to specify the name of the volume to be mapped, and the path inside the container where it should be mounted:


[Volume mounts](../../mounts_test.go) inside_block:volumeMounts


!!!tip
    This ability of creating volumes is also available for remote Docker hosts.

!!!warning
    Bind mounts are not supported, as it could not work with remote Docker hosts.

!!!tip
    It is recommended to copy data from your local host machine to a test container using the file copy API 
    described below, as it is much more portable.

## Mounting images

Since Docker v28, it is possible to mount the file system of an image into a container using the `Mounts` attribute at the `ContainerRequest` struct. For that, use the `DockerImageMountSource` type, which allows you to specify the name of the image to be mounted, and the subpath inside the container where it should be mounted, or simply call the `ImageMount` function, which does exactly that:


[Image mounts](../../lifecycle_test.go) inside_block:imageMounts


!!!warning
    If the subpath is not a relative path, the creation of the container will fail.

!!!info
    Mounting images fails the creation of the container if the underlying container runtime does not support the `image mount` feature, which is available since Docker v28.

---

### Features Follow Logs (`docs/features/follow_logs.md`)

# Following Container Logs

The log-following functionality follows a producer-consumer model: the container produces logs, and your code consumes them.
So if you wish to follow container logs, you have to do two things:

1. set up log consumers.
2. configure the log production of the container (e.g. timeout for the logs).

As logs are written to either `stdout`, or `stderr` (`stdin` is not supported) they will be forwarded (produced) to any associated log consumer.

## Creating a LogConsumer

A `LogConsumer` must implement the `LogConsumer` interface, and it could be as simple as directly printing the log to `stdout`,
as in the following example:


[The LogConsumer Interface](../../logconsumer.go) inside_block:logConsumerInterface
[The Log struct](../../logconsumer.go) inside_block:logStruct
[Example LogConsumer](../../testing.go) inside_block:exampleLogConsumer


You can associate `LogConsumer`s in two manners:

1. as part of the `ContainerRequest` struct.
2. with the `FollowOutput` function (deprecated).

## Passing the LogConsumers in the ContainerRequest

This will represent the current way for associating `LogConsumer`s. You simply define your consumers, and attach them as a slice using the `WithLogConsumerConfig` functional option.
See the following example, where `g` is an instance of a given `LogConsumer` struct.


[Passing LogConsumers](../../logconsumer_test.go) inside_block:logConsumersAtRequest


Please check that it's possible to configure the log production with a slice of functional options. These options must be of the `LogProductionOption` type:

```go
type LogProductionOption func(*DockerContainer)
```

At the moment, _Testcontainers for Go_ exposes an option to set log production timeout, using the `WithLogProductionTimeout` function.

_Testcontainers for Go_ will read this log producer/consumer configuration to automatically start producing logs if and only if the consumers slice contains at least one valid `LogConsumer`.

## Manually using the FollowOutput function

!!!warning
	This method is not recommended, as it requires you to manually manage the `LogConsumer` lifecycle.
	We recommend using the `ContainerRequest` struct to associate `LogConsumer`s, as it's the simplest and most straightforward method.
	If you use both methods, you can get an error, as the `StartLogProducer` function could be called twice, which is not allowed.

	As a consequence, this lifecycle (`StartLogProducer`, `FollowOutput` and `StopLogProducer) will be **deprecated** in the future, delegating the control to the library.

Instead of passing the `LogConsumer` as part of the `ContainerRequest` struct, you can manually call the `FollowOutput` function on a `Container` instance.
This allows you to dynamically add `LogConsumer`s to a running container, although it forces you to manually manage the `LogConsumer` lifecycle,
calling `StartLogProducer` **after** the `FollowOutput` function, and do it just once.

You can define a log consumer like so:

```go
type TestLogConsumer struct {
	Msgs []string // store the logs as a slice of strings
}

func (g *TestLogConsumer) Accept(l testcontainers.Log) {
	g.Msgs = append(g.Msgs, string(l.Content))
}
```

And then associate it with a container like so:

```go
g := TestLogConsumer{
	Msgs: []string{},
}

// Remember that this method will be deprecated in the future
c.FollowOutput(&g) // must be called before StarLogProducer

// Remember that this method will be deprecated in the future
err := c.StartLogProducer(ctx)
if err != nil {
	// do something with err
}

// some stuff happens...

// Remember that this method will be deprecated in the future
err = c.StopLogProducer()
if err != nil {
	// do something with err
}
```

## Stopping the Log Production

The production of logs is automatically stopped in `c.Terminate()`, so you don't have to worry about that.

!!! warning
	It can be done manually during container lifecycle using `c.StopLogProducer()`, but it's not recommended, as it will be deprecated in the future.

## Listening to errors

When the log production fails to start within given timeout (causing a context deadline) or there's an error returned while closing the reader it will no longer panic, but instead will return an error over a channel. You can listen to it using `DockerContainer.GetLogProductionErrorChannel()` method:

```go
func (c *DockerContainer) GetLogProductionErrorChannel() <-chan error {
	return c.producerError
}
```

This allows you to, for example, retry restarting the log production if it fails to start the first time.

For example, you would start the log production normally, defining the log production configuration at the `ContainerRequest` struct, and then:

```go
// start log production normally, using the ContainerRequest struct, or
// using the deprecated c.StartLogProducer method.
// err = container.StartLogProducer(ctx, WithLogProductionTimeout(10*time.Second))

// listen to errors in a detached goroutine
go func(done chan struct{}, timeout time.Duration) {
	for {
		select {
		case logErr := <-container.GetLogProductionErrorChannel():
			if logErr != nil {
				// do something with error
				// for example, retry starting the log production 
				// (here we retry it once, in real life you might want to retry it more times)
				startErr := container.StartLogProducer(ctx, timeout)
				if startErr != nil {
					return 
				}
		case <-done:
			return
		}
	}
}(cons.logListeningDone, time.Duration(10*time.Second))
```

---

### Features Garbage Collector (`docs/features/garbage_collector.md`)

# Garbage Collector

Typically, an integration test creates one or more containers. This can mean a
lot of containers running by the time everything is done. We need to have a way
to clean up after ourselves to keep our machines running smoothly.

Containers can be unused because:

1. Test is over and the container is not needed anymore.
2. Test failed, we do not need that container anymore because next build will
   create new containers.

## Terminate function

As we saw previously there are at least two ways to remove unused containers.
The primary method is to use the `Terminate(context.Context)` function that is
available when a container is created. Use `defer` to ensure that it is called
on test completion.

The `Terminate` function can be customised with termination options to determine how a container is removed: termination timeout, and the ability to remove container volumes are supported at the moment. You can build the default options using the `testcontainers.NewTerminationOptions` function.

#### NewTerminateOptions

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.35.0"><span class="tc-version">:material-tag: v0.35.0</span></a>

If you want to attach option to container termination, you can use the `testcontainers.NewTerminateOptions(ctx context.Context, opts ...TerminateOption) *TerminateOptions` option, which receives a TerminateOption as parameter, creating custom termination options to be passed on the container termination.

##### Terminate Options

###### [StopContext](../../cleanup.go)
Sets the context for the Container termination.

- **Function**: `StopContext(ctx context.Context) TerminateOption`
- **Default**: The context passed in `Terminate()`
- **Usage**:
```go
err := container.Terminate(ctx,StopContext(context.Background()))
```

###### [StopTimeout](../../cleanup.go)
Sets the timeout for stopping the Container.

- **Function**: ` StopTimeout(timeout time.Duration) TerminateOption`
- **Default**:  10 seconds
- **Usage**:
```go
err := container.Terminate(ctx, StopTimeout(20 * time.Second))
```

###### [RemoveVolumes](../../cleanup.go)
Sets the volumes to be removed during Container termination.

- **Function**: ` RemoveVolumes(volumes ...string) TerminateOption`
- **Default**:  Empty (no volumes removed)
- **Usage**:
```go
err := container.Terminate(ctx, RemoveVolumes("vol1", "vol2"))
```


!!!tip

    Remember to `defer` as soon as possible so you won't forget. The best time
    is as soon as you call `testcontainers.GenericContainer` but remember to
    check for the `err` first.

## Ryuk

[Ryuk](https://github.com/testcontainers/moby-ryuk) (also referred to as
`Reaper` in this package) removes containers/networks/volumes created by
_Testcontainers for Go_ after a specified delay. It is a project developed by the
Testcontainers organization and is used across the board for many of the
different language implementations.

When you run one test, you will see an additional container called `ryuk`
alongside all of the containers that were specified in your test. It relies on
container labels to determine which resources were created by the package
to determine the entities that are safe to remove. If a container is running
for more than 10 seconds, it will be killed.

!!!warning

    This feature can be disabled in two different manners, but it can cause **unexpected behavior** in your environment:

    1. adding `ryuk.disabled=true` to the `.testcontainers.properties` file.
    2. setting the `TESTCONTAINERS_RYUK_DISABLED=true` environment variable. This manner takes precedence over the properties file.

    We recommend using it only for Continuous Integration services that have their
    own mechanism to clean up resources.

Even if you do not call Terminate, Ryuk ensures that the environment will be
kept clean and even cleans itself when there is nothing left to do.

---

### Features Image Name Substitution (`docs/features/image_name_substitution.md`)

# Image name substitution

_Testcontainers for Go_ supports automatic substitution of Docker image names.

This allows the replacement of an image name specified in test code with an alternative name - for example, to replace the 
name of a Docker Hub image dependency with an alternative hosted on a private image registry.

This is advisable to avoid Docker Hub rate limiting, and some companies will prefer this for policy reasons.

!!!info
    As of November 2020 Docker Hub pulls are rate limited. As Testcontainers uses Docker Hub for standard images, some users may hit these rate limits and should mitigate accordingly. Suggested mitigations are noted in [this issue in Testcontainers for Java](https://github.com/testcontainers/testcontainers-java/issues/3099) at present.

This page describes two approaches for image name substitution:

* [Automatically modifying Docker Hub image names](#automatically-modifying-docker-hub-image-names), prefixing them with a private registry URL.
* [Using an Image Name Substitutor](#developing-a-custom-function-for-transforming-image-names-on-the-fly), developing a custom function for transforming image names on the fly.

!!!warning
    It is assumed that you have already set up a private registry hosting [all the Docker images your build requires](../supported_docker_environment/image_registry_rate_limiting.md#which-images-are-used-by-testcontainers).

## Automatically modifying Docker Hub image names

_Testcontainers for Go_ can be configured to modify Docker Hub image names on the fly to apply a prefix string.

Consider this if:

* Developers and CI machines need to use different image names. For example, developers are able to pull images from Docker Hub, but CI machines need to pull from a private registry.
* Your private registry has copies of images from Docker Hub where the names are predictable, and just adding a prefix is enough. 
  For example, `registry.mycompany.com/mirror/mysql:8.0.36` can be derived from the original Docker Hub image name (`mysql:8.0.36`) with a consistent prefix string: `registry.mycompany.com/mirror`

In this case, image name references in code are **unchanged**.
i.e. you would leave as-is:


[Unchanged direct Docker Hub image name](../../container_test.go) inside_block:directDockerHubReference


You can then configure _Testcontainers for Go_ to apply a given prefix (e.g. `registry.mycompany.com/mirror`) to every image that it tries to pull from Docker Hub. Important to notice that **the prefix should not include a trailing slash**. This can be done in one of two ways:

* Setting the `TESTCONTAINERS_HUB_IMAGE_NAME_PREFIX=registry.mycompany.com/mirror` environment variable.
* Via config file, setting `hub.image.name.prefix` in the `~/.testcontainers.properties` file in your user home directory.

_Testcontainers for Go_ will automatically apply the prefix to every image that it pulls from Docker Hub - please verify that all [the required images](#images-used-by-testcontainers) exist in your registry.

_Testcontainers for Go_ will not apply the prefix to:

* non-Hub image names (e.g. where another registry is set)
* Docker Hub image names where the hub registry is explicitly part of the name (i.e. anything with a `registry.hub.docker.com` host part)

## Developing a custom function for transforming image names on the fly

Consider this if:

* You have complex rules about which private registry images should be used as substitutes, e.g.:
    * non-deterministic mapping of names meaning that a [name prefix](#automatically-modifying-docker-hub-image-names) cannot be used, or
    * rules depending upon developer identity or location, or
* you wish to add audit logging of images used in the build, or
* you wish to prevent accidental usage of images that are not on an approved list.

In this case, image name references in code are **unchanged**. i.e. you would leave as-is:


[Unchanged direct Docker Hub image name](../../container_test.go) inside_block:directDockerHubReference


You can implement a custom image name substitutor by:

* implementing the `ImageNameSubstitutor` interface, exposed by the `testcontainers` package.
* configuring _Testcontainers for Go_ to use your custom implementation, defined at the `ContainerRequest` level.

The following is an example image substitutor implementation prepending the `registry.hub.docker.com/library/` prefix, used in the tests:


[Image Substitutor Interface](../../options.go) inside_block:imageSubstitutor
[Docker prefix Image Substitutor](../../container_test.go) inside_block:dockerImageSubstitutor
[Applying the substitutor](../../container_test.go) inside_block:applyImageSubstitutors


## Images used by Testcontainers

As of the current version of Testcontainers ({{latest_version}}):

* every image directly used by your tests
* images pulled by Testcontainers itself to support functionality:
    * [`testcontainers/ryuk`](https://hub.docker.com/r/testcontainers/ryuk) - performs fail-safe cleanup of containers, and always required (unless [Ryuk is disabled](./configuration.md#customizing-ryuk-the-resource-reaper)).
    * [`alpine`](https://hub.docker.com/r/_/alpine).
    * [`Docker in Docker`](https://hub.docker.com/_/docker).
    * [`nginx`](https://hub.docker.com/r/_/nginx).
    * [`delayed nginx`](https://hub.docker.com/r/menedev/delayed-nginx).
    * [`localstack`](https://hub.docker.com/r/localstack/localstack).
    * [`mysql`](https://hub.docker.com/r/_/mysql).
    * [`postgres`](https://hub.docker.com/r/_/postgres).
    * [`postgis`](https://hub.docker.com/r/postgis/postgis).
    * [`redis`](https://hub.docker.com/r/_/redis).
    * [`registry`](https://hub.docker.com/r/_/registry).

---

### Features Networking (`docs/features/networking.md`)

# Networking and communicating with containers

## Creating networks

Apart from creating containers, `Testcontainers for Go` allows you to create networks. This is useful when you need to connect multiple containers to the same network.

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.27.0"><span class="tc-version">:material-tag: v0.27.0</span></a>

For that, please import the `testcontainers/network` package.

```go
import "github.com/testcontainers/testcontainers-go/network"
```

Then, you can create a network using the `network.New` function. This function receives a variadic list of options that can be used to configure the network.

- `WithAttachable()`
- `WithCheckDuplicate()`
- `WithDriver(driver string)`
- `WithEnableIPv6()`
- `WithInternal()`
- `WithLabels(labels map[string]string)`
- `WithIPAMConfig(config *network.IPAMConfig)`

It's important to mention that the name of the network is automatically generated by the library, and it's not possible to set it manually. However, you can retrieve the name of the network using the `Name` field of the `DockerNetwork` struct returned by the `New` function.

### Usage example


[Creating a network](../../network/examples_test.go) inside_block:createNetwork
[Creating a network with options](../../network/examples_test.go) inside_block:newNetworkWithOptions
 

## Exposing container ports to the host

It is common to want to connect to a container from your test process, running on the test 'host' machine.
For example, you may be testing some code that needs to connect to a backend or data store container.

Generally, each required port needs to be explicitly exposed. For example, we can specify one or more ports as follows:


[Exposing ports](../../docker_test.go) inside_block:exposePorts


Note that this exposed port number is from the *perspective of the container*. 

*From the host's perspective* Testcontainers actually exposes this on a random free port.
This is by design, to avoid port collisions that may arise with locally running software or in between parallel test runs.

Because there is this layer of indirection, it is necessary to ask Testcontainers for the actual mapped port at runtime.
This can be done using the `MappedPort` function, which takes the original (container) port as an argument:


[Retrieving actual ports at runtime](../../container_test.go) inside_block:mappedPort


!!! warning
    Because the randomised port mapping happens during container startup, the container must be running at the time `MappedPort` is called. 
    You may need to ensure that the startup order of components in your tests caters for this.

## Getting the container host

When running with a local Docker daemon, exposed ports will usually be reachable on `localhost`.
However, in some CI environments they may instead be reachable on a different host.

As such, Testcontainers provides a convenience function to obtain an address on which the container should be reachable from the host machine.


[Getting the container host](../../docker_test.go) inside_block:containerHost


It is normally advisable to use `Host` and `MappedPort` together when constructing addresses - for example:


[Getting the container host and mapped port](../../docker_test.go) inside_block:buildingAddresses


!!! info
    Setting the `TESTCONTAINERS_HOST_OVERRIDE` environment variable overrides the host of the docker daemon where the container port is exposed. For example, `TESTCONTAINERS_HOST_OVERRIDE=172.17.0.1`.

## Exposing host ports to the container

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.31.0"><span class="tc-version">:material-tag: v0.31.0</span></a>

In some cases it is necessary to make a network connection from a container to a socket that is listening on the host machine. Natively, Docker has limited support for this model across platforms. Testcontainers, however, makes this possible, allowing your code to access services running on the host machine.

In this example, assume that `freePorts` is a slice of ports on our test host machine where different servers (e.g. a web application) are running.

We can simply create a container and expose these ports to the container using the `ContainerRequest` struct:


[Exposing the host ports](../../port_forwarding_test.go) inside_block:hostAccessPorts


!!!warning
    Note that the server/s listening on those ports on the host must have been started before the container is created.

From a container's perspective, the hostname will be `host.testcontainers.internal` and the port will be the same value as any in the `freePorts` slice. _Testcontainers for Go_ exposes the host internal name as the `testcontainers.HostInternal` constant, so you can use it to build the address to connect to the host on the exposed port.


[Accessing the exposed host port from a container](../../port_forwarding_test.go) inside_block:wgetHostInternal


In the above example we are executing an HTTP request from the command line inside the given container to the host machine.

### How it works

When you expose a host port to a container, _Testcontainers for Go_ creates an SSHD server companion container, which will be used to forward the traffic from the container to the host machine. This is done by creating a tunnel between the container and the host machine through the SSHD server container.

You can find more information about this SSHD server container on its GitHub repository: [https://github.com/testcontainers/sshd-docker](https://github.com/testcontainers/sshd-docker).


[SSHD Server Docker Image](../../port_forwarding.go) inside_block:hubSshdImage


!!!important
    At this moment, each container request will use a new SSHD server container. This means that if you create multiple containers with exposed host ports, each one will have its own SSHD server container.

## Docker's host networking mode

From [Docker documentation](https://docs.docker.com/network/drivers/host/):

> If you use the host network mode for a container, that container’s network stack is not isolated from the Docker host (the container shares the host’s networking namespace), and the container does not get its own IP-address allocated. For instance, if you run a container which binds to port 80 and you use host networking, the container’s application is available on port 80 on the host’s IP address.

But according to those docs, it's supported only for Linux hosts:

> The host networking driver only works on Linux hosts, and is not supported on Docker Desktop for Mac, Docker Desktop for Windows, or Docker EE for Windows Server.

In the case you need to skip a test on non-Linux hosts, you can use the `SkipIfDockerDesktop` function:


[Skipping tests on non-Linux hosts](../../network/network_test.go) inside_block:skipIfDockerDesktop


It will try to get a Docker client and obtain its Info. In the case the Operating System is "Docker Desktop", it will skip the test.

## Advanced networking

Docker provides the ability for you to create custom networks and place containers on one or more networks. Then, communication can occur between networked containers without the need of exposing ports through the host. With Testcontainers, you can do this as well. 

!!! tip
    Note that _Testcontainers for Go_ allows a container to be on multiple networks including network aliases.

For more information about how to create networks using _Testcontainers for Go_, please refer to the [How to create a network](./creating_networks.md) section.


[Creating custom networks](../../network/network_test.go) inside_block:testNetworkAliases

---

### Features Override Container Command (`docs/features/override_container_command.md`)

# Executing commands

## Container startup command

By default the container will execute whatever command is specified in the image's Dockerfile. If you would like to send a CMD (command) to a container, you can pass it in to
the container request via the `Cmd` field. For example:

```go
req := ContainerRequest{
	Image: "alpine",
	WaitingFor: wait.ForAll(
		wait.ForLog("command override!"),
	),
	Cmd: []string{"echo", "command override!"},
}
```

!!!info
    If you are using a module, you can use the `testcontainers.CustomizeRequest` option to add arguments to the command. Check the individual module's pages for more information on their commands.

This option will merge the customized request into the module's request, appending any additional `Cmd` arguments to the
module's command. This can't be used to replace the command, only to append options.
Check the individual module's pages for more information on their commands.

## Executing a command

You can execute a command inside a running container, similar to a `docker exec` call:


[Executing a command](../../docker_test.go) inside_block:exec_example


This can be useful for software that has a command line administration tool. You can also get the logs of the command execution (from an object that implements the [io.Reader](https://pkg.go.dev/io#Reader) interface). For example:



[Command logs](../../docker_test.go) inside_block:exec_reader_example


This is done this way, because it brings more flexibility to the user, rather than returning a string.

---

### Features Test Session Semantics (`docs/features/test_session_semantics.md`)

# Test Session Semantics

The test session semantics is a feature that allows _Testcontainers for Go_ to identify the current test session
and tag the containers created by the library with a unique session ID.

This is needed because each Go package will be run in a separate process, so we need a way to identify the current test execution
to aggregate the tests executed in it.

By test session, we mean:

- a single `go test` invocation (including flags).
- a single `go test ./...` invocation, for all subpackages from that location (including flags).
- the execution of a single test or a set of tests using the IDE.

As a consequence, _Testcontainers for Go_ will use the parent process ID (pid) of the current process and its creation date
to generate a unique session ID.

We are using the parent pid because the current `go test` process running a given Go package will be a child of one of the following:

- the process that is running the tests, e.g.: `go test`;
- the process that is running the application in development mode, e.g. `go run main.go -tags dev`;
- the process that is running the tests in the IDE, e.g.: `go test ./...`.

That's why we need to use the parent pid to identify the current test session, as it must be unique.

Finally, we will hash the combination of the `testcontainers-go:` string with the parent pid and the creation date
of that parent process to generate a unique session ID.

After that, the `sessionID` will be used to:

- identify the test session, aggregating the test execution of multiple packages in the same test session.
- pass the `sessionID` to the container runtime, as an HTTP header to the daemon.
- tag the containers created by _Testcontainers for Go_, adding a label to the container with this session ID.

## Overriding the session ID

Deriving the session ID from the parent process works when the processes taking part in a test session
share a parent, which is the case for `go test` and for the IDE. When that is not true, the processes
end up in different sessions: some build systems and CI setups run each test target in isolation, and
the parent process they are given is not guaranteed to be stable or shared.

For those cases the session ID can be set explicitly, either with the `TESTCONTAINERS_SESSION_ID`
**environment variable** or with the `session.id` **property**. When set, the value is used as-is,
instead of being derived, so every process configured with the same value takes part in the same session.

!!!warning
    Setting this value will preclude runs from creating more than one reaper. Therefore, changes to Ryuk
    settings past its creation will be ignored.

The session ID is used to build the name of the reaper container (`reaper_<sessionID>`), so a configured
value must produce a name the container runtime accepts. It must:

- not be empty;
- contain only alphanumeric characters, dots (`.`), hyphens (`-`) and underscores (`_`);
- be at most 121 characters long, so that the resulting container name stays within the 128 character
  limit imposed by the container runtime.

A configured value that does not satisfy these constraints is rejected when the configuration is read,
reporting the offending value and the reason. The session IDs generated by the library always satisfy
them, so this only applies to values coming from the configuration.

### Bazel

Bazel is a concrete example of a build system where the session ID needs to be set explicitly, because it
does not provide the conditions the derivation relies on. Its
[Test Encyclopedia](https://bazel.build/reference/test-encyclopedia) states that _"the current process id,
process group id, session id, and parent process id are unspecified"_, so the parent process the library
would derive the session ID from is not guaranteed to be stable or shared across test targets. Sharding
makes this more visible, as the test runner is launched once per shard.

Two more details of the test environment matter:

- `HOME` is set to the value of `$TEST_TMPDIR`, a private directory for the test, so the
  `~/.testcontainers.properties` file is not picked up.
- The test environment is sanitised: tests _"should not depend on the presence, absence, or value of any
  environment variable not listed"_ in the encyclopedia, so `TESTCONTAINERS_SESSION_ID` does not reach the
  test unless it is explicitly propagated.

That leaves the environment variable, declared with `--test_env`, as the way to share a session across test
targets. The value can be taken from the invocation environment:

```shell
bazel test //... --test_env=TESTCONTAINERS_SESSION_ID
```

or set independently of it:

```shell
bazel test //... --test_env=TESTCONTAINERS_SESSION_ID=my-session
```

---

### Features Tls (`docs/features/tls.md`)

# TLS certificates

Interacting with services that require TLS certificates is a common issue when working with containers. You can create one or more on-the-fly certificates in order to communicate with your services.

_Testcontainers for Go_ uses a library to generate certificates on-the-fly. This library is called [tlscert](https://github.com/mdelapenya/tlscert).

### Examples

In the following example we are going to start an HTTP server with a self-signed certificate.
It exposes one single handler that will return a simple message when accessed.
The example will also create a client that will connect to the server using the generated certificate,
demonstrating how to use the generated certificate to communicate with a service.


[Create a self-signed certificate](../../modules/rabbitmq/examples_test.go) inside_block:exampleSelfSignedCert
[Sign a self-signed certificate](../../modules/rabbitmq/examples_test.go) inside_block:exampleSignSelfSignedCert

---

### Modules Activemq (`docs/modules/activemq.md`)

# ActiveMQ

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

## Introduction

The Testcontainers module for Apache ActiveMQ Classic. This module is distinct from the [Artemis](./artemis.md) module, which targets Apache ActiveMQ Artemis (the next-generation broker).

## Adding this module to your project dependencies

Please run the following command to add the ActiveMQ module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/activemq
```

## Usage example


[Creating a ActiveMQ container](../../modules/activemq/examples_test.go) inside_block:runActiveMQContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

The ActiveMQ module exposes one entrypoint function to create the ActiveMQ container, and this function receives three parameters:

```golang
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(), "apache/activemq-classic:5.18")`.

### Container Options

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

#### WithAdminCredentials

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

Sets the username and password for the ActiveMQ web console administrator. The credentials are
propagated via the `ACTIVEMQ_WEB_ADMIN_NAME` and `ACTIVEMQ_WEB_ADMIN_PASSWORD` environment
variables. The wait strategy is also updated to authenticate with the provided credentials.

The default credentials are `admin`/`admin`.


[With admin credentials](../../modules/activemq/activemq_test.go) inside_block:withAdminCredentials


{% include "../features/common_functional_options_list.md" %}

### Container Methods

The ActiveMQ container exposes the following methods:

#### AdminUser

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

The `AdminUser()` method returns the administrator username used to access the web console.


[Get admin user](../../modules/activemq/examples_test.go) inside_block:adminUser


#### AdminPassword

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

The `AdminPassword()` method returns the administrator password used to access the web console.


[Get admin password](../../modules/activemq/examples_test.go) inside_block:adminPassword


#### BrokerURL

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

The `BrokerURL(ctx)` method returns the OpenWire broker URL as a string with the
format `tcp://<host>:<port>`, using the mapped `61616/tcp` port.


[Get broker URL](../../modules/activemq/activemq_test.go) inside_block:brokerURL


#### WebConsoleURL

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

The `WebConsoleURL(ctx)` method returns the HTTP URL of the ActiveMQ web console as a string
with the format `http://<host>:<port>`, using the mapped `8161/tcp` port.


[Get web console URL](../../modules/activemq/activemq_test.go) inside_block:webConsoleURL

---

### Modules Aerospike (`docs/modules/aerospike.md`)

# Aerospike

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

## Introduction

The Testcontainers module for Aerospike.

## Adding this module to your project dependencies

Please run the following command to add the Aerospike module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/aerospike
```

## Usage example


[Creating a Aerospike container](../../modules/aerospike/examples_test.go) inside_block:runAerospikeContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

The Aerospike module exposes one entrypoint function to create the Aerospike container, and this function receives three parameters:

```golang
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(), "aerospike/aerospike-server:latest")`.

### Container Options

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

{% include "../features/common_functional_options_list.md" %}

## Examples

### Aerospike Client


[Aerospike Client](../../modules/aerospike/examples_test.go) inside_block:usingClient

---

### Modules Arangodb (`docs/modules/arangodb.md`)

# ArangoDB

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

## Introduction

The Testcontainers module for ArangoDB.

## Adding this module to your project dependencies

Please run the following command to add the ArangoDB module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/arangodb
```

## Usage example


[Creating a ArangoDB container](../../modules/arangodb/examples_test.go) inside_block:runArangoDBContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

The ArangoDB module exposes one entrypoint function to create the ArangoDB container, and this function receives three parameters:

```golang
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(), "arangodb:3.11.5")`.

### Container Options

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

#### WithRootPassword

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

The `WithRootPassword` function sets the root password for the ArangoDB container.

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The ArangoDB container exposes the following methods:

#### Credentials

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

The `Credentials` method returns the credentials for the ArangoDB container, in the form of a tuple of two strings: the username and the password.

```golang
func (c *Container) Credentials() (string, string)
```

#### HTTPEndpoint

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

The `HTTPEndpoint` method returns the HTTP endpoint of the ArangoDB container, using the following format: `http://$host:$port`.

---

### Modules Artemis (`docs/modules/artemis.md`)

# Apache ActiveMQ Artemis

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.23.0"><span class="tc-version">:material-tag: v0.23.0</span></a>

## Introduction

The Testcontainers module for Artemis.

## Adding this module to your project dependencies

Please run the following command to add the Artemis module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/artemis
```

## Usage example


[Creating to an Artemis container](../../modules/artemis/examples_test.go) inside_block:runArtemisContainer



[Connecting to an Artemis container](../../modules/artemis/examples_test.go) inside_block:connectToArtemisContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.32.0"><span class="tc-version">:material-tag: v0.32.0</span></a>

!!!info
    The `RunContainer(ctx, opts...)` function is deprecated and will be removed in the next major release of _Testcontainers for Go_.

The Artemis module exposes one entrypoint function to create the Artemis container, and this function receives three parameters:

```golang
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(), "apache/activemq-artemis:2.30.0")`.

### Container Options

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

#### WithCredentials

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.23.0"><span class="tc-version">:material-tag: v0.23.0</span></a>

If you need to change the default admin credentials (i.e. `artemis:artemis`) use `WithCredentials`.


[With credentials](../../modules/artemis/artemis_test.go) inside_block:withCredentials


#### WithAnonymousLogin

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.23.0"><span class="tc-version">:material-tag: v0.23.0</span></a>

If you need to enable anonymous logins (which are disabled by default) use `WithAnonymousLogin`.


[With Anonymous Login](../../modules/artemis/artemis_test.go) inside_block:withAnonymousLogin


#### WithExtraArgs

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.23.0"><span class="tc-version">:material-tag: v0.23.0</span></a>

If you need to pass custom arguments to the `artemis create` command, use `WithExtraArgs`.
The default is `--http-host 0.0.0.0 --relax-jolokia`.
Setting this value will override the default.

!!!info
    Please see the documentation on `artemis create` for the available options here: [https://activemq.apache.org/components/artemis/documentation/latest/using-server.html#options](https://activemq.apache.org/components/artemis/documentation/latest/using-server.html#options)


[With Extra Arguments](../../modules/artemis/artemis_test.go) inside_block:withExtraArgs


{% include "../features/common_functional_options_list.md" %}

### Container Methods

The Artemis container exposes the following methods:

#### User

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.23.0"><span class="tc-version">:material-tag: v0.23.0</span></a>

User returns the administrator username.


[Retrieving the Administrator User](../../modules/artemis/examples_test.go) inside_block:containerUser


#### Password

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.23.0"><span class="tc-version">:material-tag: v0.23.0</span></a>

Password returns the administrator password.


[Retrieving the Administrator Password](../../modules/artemis/examples_test.go) inside_block:containerPassword


#### BrokerEndpoint

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.23.0"><span class="tc-version">:material-tag: v0.23.0</span></a>

BrokerEndpoint returns the host:port for the combined protocols endpoint.


[Get broker endpoint](../../modules/artemis/artemis_test.go) inside_block:brokerEndpoint


#### ConsoleURL

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.23.0"><span class="tc-version">:material-tag: v0.23.0</span></a>

ConsoleURL returns the URL for the management console.


[Get console URL](../../modules/artemis/artemis_test.go) inside_block:consoleURL

---

### Modules Azure (`docs/modules/azure.md`)

# Azure

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.36.0"><span class="tc-version">:material-tag: v0.36.0</span></a>

## Introduction

The Testcontainers module for Azure.

## Adding this module to your project dependencies

Please run the following command to add the Azure module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/azure
```

## Usage example

The Azure module exposes the following Go packages:

- [Azurite](#azurite): `github.com/testcontainers/testcontainers-go/modules/azure/azurite`.
- [EventHubs](#eventhubs): `github.com/testcontainers/testcontainers-go/modules/azure/eventhubs`.
- [ServiceBus](#servicebus): `github.com/testcontainers/testcontainers-go/modules/azure/servicebus`.
!!! warning "EULA Acceptance"
    Due to licensing restrictions you are required to explicitly accept an End User License Agreement (EULA) for the EventHubs container image. This is facilitated through the `WithAcceptEULA` function.
- [CosmosDB](#cosmosdb): `github.com/testcontainers/testcontainers-go/modules/azure/cosmosdb`.
- [Lowkey Vault](#lowkey-vault): `github.com/testcontainers/testcontainers-go/modules/azure/lowkeyvault`.
- [Azure SQL Edge](#azure-sql-edge): `github.com/testcontainers/testcontainers-go/modules/azure/sqledge`.

[Creating a Azurite container](../../modules/azure/azurite/examples_test.go) inside_block:runAzuriteContainer


## Azurite

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.36.0"><span class="tc-version">:material-tag: v0.36.0</span></a>

The Azurite module exposes one entrypoint function to create the Azurite container, and this function receives three parameters:

```golang
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.

### Default Credentials

The Azurite container uses the following default credentials:


[Default Credentials](../../modules/azure/azurite/azurite.go) inside_block:defaultCredentials


#### Image

Use the second argument in the `Run` function to set a valid Docker image.
In example: `Run(context.Background(), "mcr.microsoft.com/azure-storage/azurite:3.28.0")`.

### Container Options

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

#### WithEnabledServices

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.40.0"><span class="tc-version">:material-tag: v0.40.0</span></a>

The default Azurite container entrypoint runs all three storage services: blob, queue, and table. Use this option to specify the required services for fewer exposed ports and slightly reduced container resources. E.g. `azurite.WithEnabledServices(azurite.BlobService)`.

#### WithInMemoryPersistence

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.36.0"><span class="tc-version">:material-tag: v0.36.0</span></a>

If you want to use in-memory persistence, you can use `WithInMemoryPersistence(megabytes float64)`. E.g. `azurite.WithInMemoryPersistence(64.0)`.

Please read the [Azurite documentation](https://github.com/Azure/Azurite?tab=readme-ov-file#use-in-memory-storage) for more information.

!!! warning
    This option is only available in Azurite versions `3.28.0` and later.

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The Azurite container exposes the following methods:

#### BlobServiceURL

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.36.0"><span class="tc-version">:material-tag: v0.36.0</span></a>

Returns the service URL to connect to the Blob service of the Azurite container and an error, passing the Go context as parameter.

#### QueueServiceURL

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.36.0"><span class="tc-version">:material-tag: v0.36.0</span></a>

Returns the service URL to connect to the Queue service of the Azurite container and an error, passing the Go context as parameter.

#### TableServiceURL

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.36.0"><span class="tc-version">:material-tag: v0.36.0</span></a>

Returns the service URL to connect to the Table service of the Azurite container and an error, passing the Go context as parameter.

### Examples

#### Blob Operations

In the following example, we will create a container with Azurite and perform some blob operations. For that, using the default
credentials, we will create an Azurite container, upload a blob to it, list the blobs, and download the blob. Finally, we will remove the created blob and container.


[Create Container](../../modules/azure/azurite/examples_test.go) inside_block:runForBlobOperations
[Create Shared Key Credential](../../modules/azure/azurite/examples_test.go) inside_block:createSharedKeyCredential
[Create Client](../../modules/azure/azurite/examples_test.go) inside_block:createClient
[Create Container](../../modules/azure/azurite/examples_test.go) inside_block:createContainer
[Upload and Download Blob](../../modules/azure/azurite/examples_test.go) inside_block:uploadDownloadBlob
[List Blobs](../../modules/azure/azurite/examples_test.go) inside_block:listBlobs
[Delete Blob](../../modules/azure/azurite/examples_test.go) inside_block:deleteBlob
[Delete Container](../../modules/azure/azurite/examples_test.go) inside_block:deleteContainer


#### Queue Operations

In the following example, we will create an Azurite container and perform some queue operations. For that, using the default
credentials, we will create a queue, list the queues, and finally we will remove the created queue.


[Run Azurite Container](../../modules/azure/azurite/examples_test.go) inside_block:runForQueueOperations
[Create Shared Key Credential](../../modules/azure/azurite/examples_test.go) inside_block:queueOperations_createSharedKeyCredential
[Create Client](../../modules/azure/azurite/examples_test.go) inside_block:queueOperations_createClient
[Create Queue](../../modules/azure/azurite/examples_test.go) inside_block:createQueue
[List Queues](../../modules/azure/azurite/examples_test.go) inside_block:listQueues
[Delete Queue](../../modules/azure/azurite/examples_test.go) inside_block:deleteQueue


#### Table Operations

In the following example, we will create an Azurite container and perform some table operations. For that, using the default
credentials, we will create a table, list the tables, and finally we will remove the created table.


[Run Azurite Container](../../modules/azure/azurite/examples_test.go) inside_block:runForTableOperations
[Create Shared Key Credential](../../modules/azure/azurite/examples_test.go) inside_block:tableOperations_createSharedKeyCredential
[Create Client](../../modules/azure/azurite/examples_test.go) inside_block:tableOperations_createClient
[Create Table](../../modules/azure/azurite/examples_test.go) inside_block:createTable
[List Tables](../../modules/azure/azurite/examples_test.go) inside_block:listTables
[Delete Table](../../modules/azure/azurite/examples_test.go) inside_block:deleteTable


## EventHubs

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.36.0"><span class="tc-version">:material-tag: v0.36.0</span></a>

The EventHubs module exposes one entrypoint function to create the EventHubs container, and this function receives three parameters:

```golang
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.

The EventHubs container needs an Azurite container to be running. By default, _Testcontainers for Go_ **automatically creates a Docker network and an Azurite container** for EventHubs to work.
When terminating the EventHubs container, the Azurite container and the Docker network are also terminated.
If you want to manage the Azurite container and network yourself, use the [`WithAzuriteContainer`](#withazuritecontainer) option instead.

#### Image

Use the second argument in the `Run` function to set a valid Docker image.
In example: `Run(context.Background(), "mcr.microsoft.com/azure-messaging/eventhubs-emulator:2.0.1")`.

### Container Options

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

#### WithAzurite

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.36.0"><span class="tc-version">:material-tag: v0.36.0</span></a>

This option allows you to set a different Azurite Docker image, instead of the default one, and also pass options to the Azurite container, in the form of a variadic argument of `testcontainers.ContainerCustomizer`.

!!! warning
    `WithAzurite` and [`WithAzuriteContainer`](#withazuritecontainer) are mutually exclusive. Passing both to `Run` returns an error. If you already have a running Azurite container, use `WithAzuriteContainer` instead — the image and options set here will not apply.

#### WithAcceptEULA

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.36.0"><span class="tc-version">:material-tag: v0.36.0</span></a>

This option allows you to accept the EULA for the EventHubs container.

#### WithAzuriteContainer

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.43.0"><span class="tc-version">:material-tag: v0.43.0</span></a>

This option allows you to supply a pre-existing Azurite container and Docker network instead of letting the module create them automatically. When this option is used, calling `Terminate()` on the EventHubs container will **not** stop or remove the Azurite container or the network — the caller is responsible for their lifecycle.

!!! warning
    `WithAzuriteContainer` and [`WithAzurite`](#withazurite) are mutually exclusive. Passing both to `Run` returns an error. Any Azurite image or options set via `WithAzurite` are ignored when `WithAzuriteContainer` is supplied.


[Create Network](../../modules/azure/eventhubs/examples_test.go) inside_block:withAzuriteContainer_network
[Start Azurite](../../modules/azure/eventhubs/examples_test.go) inside_block:withAzuriteContainer_azurite
[Run EventHubs with external Azurite](../../modules/azure/eventhubs/examples_test.go) inside_block:withAzuriteContainer_eventhubs


#### WithConfig

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.36.0"><span class="tc-version">:material-tag: v0.36.0</span></a>

This option allows you to set a custom EventHubs config file for the EventHubs container.

The config file must be a valid EventHubs config file, and it must be a valid JSON object.


[EventHubs JSON Config](../../modules/azure/eventhubs/testdata/eventhubs_config.json)


#### WithConfigObject

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.43.0"><span class="tc-version">:material-tag: v0.43.0</span></a>

This option is the statically-typed counterpart to `WithConfig`. It accepts a `*Config` value built with the functional-options API (`NewConfig`, `WithNamespace`, `WithEntity`, `WithConsumerGroup`, `WithLoggingType`) and marshals it to JSON at container start time.

The emulator enforces the following hard limits, which `NewConfig` validates before the container starts:

- Exactly **1 namespace**, whose name must be `eventhubs.EmulatorNamespaceName` (`"emulatorns1"`, case-insensitive).
- At most **10 entities** per namespace.
- Partition count **1–32** per entity.
- At most **20 consumer groups** per entity.


[Build Config](../../modules/azure/eventhubs/examples_test.go) inside_block:withConfigObject_buildConfig
[Run EventHubs with Config Object](../../modules/azure/eventhubs/examples_test.go) inside_block:withConfigObject_run


{% include "../features/common_functional_options_list.md" %}

### Container Methods

The EventHubs container exposes the following methods:

#### ConnectionString

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.36.0"><span class="tc-version">:material-tag: v0.36.0</span></a>

Returns the connection string to connect to the EventHubs container and an error, passing the Go context as parameter.

### Examples

#### Send events to EventHubs

In the following example, inspired by the [Azure Event Hubs Go SDK](https://learn.microsoft.com/en-us/azure/event-hubs/event-hubs-go-get-started-send), we are creating an EventHubs container and sending events to it.


[EventHubs Config](../../modules/azure/eventhubs/examples_test.go) inside_block:cfg
[Run EventHubs Container](../../modules/azure/eventhubs/examples_test.go) inside_block:runEventHubsContainer
[Create Producer Client](../../modules/azure/eventhubs/examples_test.go) inside_block:createProducerClient
[Create Sample Events](../../modules/azure/eventhubs/examples_test.go) inside_block:createSampleEvents
[Create Batch](../../modules/azure/eventhubs/examples_test.go) inside_block:createBatch
[Send Event Data Batch to the EventHub](../../modules/azure/eventhubs/examples_test.go) inside_block:sendEventDataBatch


#### Build a typed config with NewConfig

The `NewConfig` function provides a statically-typed, validated alternative to writing the JSON config by hand.


[Build Config](../../modules/azure/eventhubs/examples_test.go) inside_block:ExampleNewConfig_build


## ServiceBus

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.36.0"><span class="tc-version">:material-tag: v0.36.0</span></a>

The ServiceBus module exposes one entrypoint function to create the ServiceBus container, and this function receives three parameters:

```golang
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.

The ServiceBus container needs a MSSQL Server container to be running, for that reason _Testcontainers for Go_ **automatically creates a Docker network and an MSSQL Server container** for ServiceBus to work.
When terminating the ServiceBus container, the MSSQL Server container and the Docker network are also terminated.

!!! info
    Since version `1.1.2` of the ServiceBus emulator, it's possible to set the `SQL_WAIT_INTERVAL` environment variable to the given seconds.
    This module sets it to `0` by default, because the MSSQL Server container is started first.

#### Image

Use the second argument in the `Run` function to set a valid Docker image.
In example: `Run(context.Background(), "mcr.microsoft.com/azure-messaging/servicebus-emulator:1.1.2")`.

### Container Options

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

#### WithMSSQL

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.36.0"><span class="tc-version">:material-tag: v0.36.0</span></a>

This option allows you to set a different MSSQL Server Docker image, instead of the default one, and also pass options to the MSSQL container, in the form of a variadic argument of `testcontainers.ContainerCustomizer`.

#### WithAcceptEULA

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.36.0"><span class="tc-version">:material-tag: v0.36.0</span></a>

This option allows you to accept the EULA for the ServiceBus container.

#### WithConfig

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.36.0"><span class="tc-version">:material-tag: v0.36.0</span></a>

This option allows you to set a custom ServiceBus config file for the ServiceBus container.

The config file must be a valid ServiceBus config file, and it must be a valid JSON object.


[ServiceBus JSON Config](../../modules/azure/servicebus/testdata/servicebus_config.json)


{% include "../features/common_functional_options_list.md" %}

### Container Methods

The ServiceBus container exposes the following methods:

#### ConnectionString

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.36.0"><span class="tc-version">:material-tag: v0.36.0</span></a>

Returns the connection string to connect to the ServiceBus container and an error, passing the Go context as parameter.

### Examples

#### Send events to ServiceBus

In the following example, inspired by the [Azure Event Hubs Go SDK](https://learn.microsoft.com/en-us/azure/event-hubs/event-hubs-go-get-started-send), we are creating an EventHubs container and sending events to it.


[ServiceBus Config](../../modules/azure/servicebus/examples_test.go) inside_block:cfg
[Run ServiceBus Container](../../modules/azure/servicebus/examples_test.go) inside_block:runServiceBusContainer
[Create Client](../../modules/azure/servicebus/examples_test.go) inside_block:createClient
[Send messages to a Queue](../../modules/azure/servicebus/examples_test.go) inside_block:sendMessages
[Receive messages from a Queue](../../modules/azure/servicebus/examples_test.go) inside_block:receiveMessages


## CosmosDB

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.40.0"><span class="tc-version">:material-tag: v0.40.0</span></a>

The CosmosDB module exposes one entrypoint function to create the CosmosDB container, and this function receives three parameters:

```golang
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(), "mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview")`.

### Container Options

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

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The CosmosDB container exposes the following methods:

#### ConnectionString

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.40.0"><span class="tc-version">:material-tag: v0.40.0</span></a>

Returns the connection string to connect to the CosmosDB container and an error, passing the Go context as parameter.

### Examples

#### Connect and Create database


[Connect_CreateDatabase](../../modules/azure/cosmosdb/examples_test.go) inside_block:ExampleRun_connect


## Lowkey Vault

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.41.0"><span class="tc-version">:material-tag: v0.41.0</span></a>

The Lowkey Vault module exposes one entrypoint function to create the Lowkey Vault container, and this function receives three parameters:

```golang
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(), "nagyesta/lowkey-vault:7.3.48-ubi10-minimal")`.

### Container Options

The Lowkey Vault container exposes two ports, one for the Key Vault API and one for the metadata endpoints such as the token endpoint.
Since the Key Vault API supports multiple vaults and selects the active vault based on the host authority of the request URL, the 
container can be configured in two ways:

#### Local mode

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.41.0"><span class="tc-version">:material-tag: v0.41.0</span></a>

The default mode is to run the Key Vault container on localhost, meaning that both the Key Vault API and the metadata endpoints are 
exposed using random host ports, and the container is accessible only from the host machine. The default vault is automatically created 
and is made available using the host address. 

#### Network mode

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.41.0"><span class="tc-version">:material-tag: v0.41.0</span></a>

To prepare the container for running in a network and making it accessible from other containers in the network, you can use the 
`WithNetworkAlias` option. For example:
```golang
Run(ctx, "nagyesta/lowkey-vault:7.3.48-ubi10-minimal",
    lowkeyvault.WithNetworkAlias("lowkey-vault", aNetwork),
)
```

### Container Methods

The Lowkey Vault container exposes the following methods:

#### ConnectionURL

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.41.0"><span class="tc-version">:material-tag: v0.41.0</span></a>

Returns the connection URL to connect to the Key Vault API of the Lowkey Vault container and an error, passing the Go context and an 
`accessMode` as parameters. The access mode can be either `lowkeyvault.Local` or `lowkeyvault.Network` depending on the mode you wish
to use to connect to the Key Vault API.

#### IdentityEndpoint

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.41.0"><span class="tc-version">:material-tag: v0.41.0</span></a>

Returns the URL pointing to the token endpoint of the Lowkey Vault container and an error, passing the Go context and an `accessMode` 
as parameters. The access mode can be either `lowkeyvault.Local` or `lowkeyvault.Network` depending on the mode you wish to use to 
access the token endpoint. This can be set as the value of the `IDENTITY_ENDPOINT` environment variable without modification on the  
machine which will connect to the Lowkey Vault container. When using the Azure Key Vault SDK for Go, this will let you authenticate 
with managed identities by using the `azidentity.NewDefaultAzureCredential(nil)` as a credential.

#### IdentityHeader

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.41.0"><span class="tc-version">:material-tag: v0.41.0</span></a>

Can return the string which must be set as the value of the `IDENTITY_HEADER` environment variable without modification on the  
machine which will connect to the Lowkey Vault container. When using the Azure Key Vault SDK for Go, this will let you authenticate
with managed identities by using the `azidentity.NewDefaultAzureCredential(nil)` as a credential.

#### Client

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.41.0"><span class="tc-version">:material-tag: v0.41.0</span></a>

Returns a `http.Client` and requires the Go context as parameter. This method can be used to prepare a `http.Client` for connecting 
to the Key Vault API of the Lowkey Vault container using a self-signed certificate. This is necessary since the Lowkey Vault container
uses a self-signed certificate by default.

### Examples

#### Use the Secrets API in Local mode

In the following example, we are starting the Lowkey Vault container in Local mode, set a secret and retrieve it using the Key Vault Secrets API.


[Run Lowkey Vault Container in Local mode](../../modules/azure/lowkeyvault/examples_test.go) inside_block:createContainerWithLocalMode
[Create Client](../../modules/azure/lowkeyvault/examples_test.go) inside_block:prepareTheSecretClient
[Set and get a secret](../../modules/azure/lowkeyvault/examples_test.go) inside_block:setAndFetchTheSecret


#### Use the Keys API in Local mode

In the following example, we are starting the Lowkey Vault container in Local mode, create a key and encrypt and decrypt a message with it.


[Run Lowkey Vault Container in Local mode](../../modules/azure/lowkeyvault/examples_test.go) inside_block:createContainerWithLocalMode
[Create Client](../../modules/azure/lowkeyvault/examples_test.go) inside_block:prepareTheKeyClient
[Create a key](../../modules/azure/lowkeyvault/examples_test.go) inside_block:createKey
[Encrypt a message with the key](../../modules/azure/lowkeyvault/examples_test.go) inside_block:encryptMessage
[Decrypt cipher text with the key](../../modules/azure/lowkeyvault/examples_test.go) inside_block:decryptCipherText


#### Use the Certificates API in Local mode

In the following example, we are starting the Lowkey Vault container in Local mode, create a certificate using the Key Vault Certificates
API, and fetch the content of the certificate as a PKCS12 store using the Key Vault Secrets API.


[Run Lowkey Vault Container in Local mode](../../modules/azure/lowkeyvault/examples_test.go) inside_block:createContainerWithLocalMode
[Create Certificate Client](../../modules/azure/lowkeyvault/examples_test.go) inside_block:prepareTheCertClient
[Create a certificate](../../modules/azure/lowkeyvault/examples_test.go) inside_block:createCertificate
[Create Secret Client](../../modules/azure/lowkeyvault/examples_test.go) inside_block:prepareTheSecretClient
[Fetch the certificate details](../../modules/azure/lowkeyvault/examples_test.go) inside_block:fetchCertDetails


#### Use the Secrets API in Network mode

In the following example, we are starting the Lowkey Vault container in Network mode and setting the parameters of a Go client
container which will be used to connect to the Key Vault API of the Lowkey Vault container in Network mode.


[Run Lowkey Vault Container in Network mode](../../modules/azure/lowkeyvault/examples_test.go) inside_block:createContainerWithNetwork
[Get the endpoint details in Network mode](../../modules/azure/lowkeyvault/examples_test.go) inside_block:obtainEndpointUrls
[Configure the client container](../../modules/azure/lowkeyvault/examples_test.go) inside_block:configureClient

## Azure SQL Edge

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

The Azure SQL Edge module exposes one entrypoint function to create the Azure SQL Edge container, and this function receives three parameters:

```golang
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.

Azure SQL Edge is an ARM64-compatible SQL Server variant for IoT and edge scenarios. It uses the same `sqlserver://` wire protocol as SQL Server on port 1433.

#### Image

Use the second argument in the `Run` function to set a valid Docker image.
In example: `Run(context.Background(), "mcr.microsoft.com/azure-sql-edge:1.0.7")`.

!!! warning "EULA Acceptance"
    Due to licensing restrictions you are required to explicitly accept an End User License Agreement (EULA) for the Azure SQL Edge container image. This is facilitated through the `WithAcceptEULA` option. `Run` returns an error if it is not provided.

### Container Options

When starting the Azure SQL Edge container, you can pass options in a variadic way to configure it.

#### WithAcceptEULA

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

Accepts the Microsoft Azure SQL Edge End-User License Agreement. This option is **required**; `Run` returns an error if it is not provided.

#### WithPassword

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

If you need to set a different SA password, you can use `sqledge.WithPassword` with a valid password. E.g. `sqledge.WithPassword("Strong@Passw0rd")`.

!!!info
    The password must adhere to the [SQL Server Password Policy](https://learn.microsoft.com/en-us/sql/relational-databases/security/password-policy): at least 8 characters containing uppercase letters, lowercase letters, digits, and special characters. The default `Strong!Passw0rd` already meets this requirement.

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The Azure SQL Edge container exposes the following methods:

#### ConnectionString

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

This method returns the connection string to connect to the Azure SQL Edge container, using the default `1433` port and the `master` database.
It is possible to pass extra parameters to the connection string, e.g. `encrypt=false` or `TrustServerCertificate=true`, in a variadic way.

```golang
connectionString, err := container.ConnectionString(ctx, "encrypt=false", "TrustServerCertificate=true")
```

### Examples


[Creating an Azure SQL Edge container](../../modules/azure/sqledge/examples_test.go) inside_block:runSQLEdgeContainer

---

### Modules Azurite (`docs/modules/azurite.md`)

# Azurite

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.32.0"><span class="tc-version">:material-tag: v0.32.0</span></a>

!!!warning
    This module is deprecated and will be removed in the next major release of _Testcontainers for Go_. Please use [Azurite from the Azure module](../azure/#azurite) instead.

---

### Modules Cassandra (`docs/modules/cassandra.md`)

# Cassandra

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.26.0"><span class="tc-version">:material-tag: v0.26.0</span></a>

## Introduction

The Testcontainers module for Cassandra.

## Adding this module to your project dependencies

Please run the following command to add the Cassandra module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/cassandra
```

## Usage example


[Creating a Cassandra container](../../modules/cassandra/examples_test.go) inside_block:runCassandraContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.32.0"><span class="tc-version">:material-tag: v0.32.0</span></a>

!!!info
    The `RunContainer(ctx, opts...)` function is deprecated and will be removed in the next major release of _Testcontainers for Go_.

The Cassandra module exposes one entrypoint function to create the Cassandra container, and this function receives three parameters:

```golang
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*CassandraContainer, 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(), "cassandra:4.1.3")`.

### Container Options

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

#### WithInitScripts

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.26.0"><span class="tc-version">:material-tag: v0.26.0</span></a>

If you would like to do additional initialization in the Cassandra container, add one or more `*.cql` or `*.sh` scripts to the container request with the `WithInitScripts` function.
Those files will be copied after the container is created but before it's started under root directory.

An example of a `*.sh` script that creates a keyspace and table is shown below:


[Init script content](../../modules/cassandra/testdata/init.sh)


#### WithConfigFile

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.26.0"><span class="tc-version">:material-tag: v0.26.0</span></a>

In the case you have a custom config file for Cassandra, it's possible to copy that file into the container before it's started, using the `WithConfigFile(cfgPath string)` function.

!!!warning
    You should provide a valid Cassandra configuration file, otherwise the container will fail to start.

#### WithTLS

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.41.0"><span class="tc-version">:material-tag: v0.41.0</span></a>

If you need to enable TLS/SSL encryption for client connections, you can use the `cassandra.WithTLS()` option. 

When enabled, the container will:
- Generate self-signed certificates automatically
- Configure Cassandra to use client encryption
- Expose the SSL port (9142)

Use the `TLSConfig()` method on the returned container to get the `*tls.Config` for client connections. The method returns an error if TLS was not enabled via `WithTLS()`.


[Creating a Cassandra container with TLS](../../modules/cassandra/examples_test.go) inside_block:runCassandraContainerWithTLS
[Getting TLS connection configuration](../../modules/cassandra/examples_test.go) inside_block:getTLSConnectionHost


{% include "../features/common_functional_options_list.md" %}

### Container Methods

The Cassandra container exposes the following methods:

#### ConnectionHost

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.26.0"><span class="tc-version">:material-tag: v0.26.0</span></a>

This method returns the host and port of the Cassandra container, using the default, `9042/tcp` port. E.g. `localhost:9042`


[Get connection host](../../modules/cassandra/cassandra_test.go) inside_block:connectionHost


#### TLSConfig

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.41.0"><span class="tc-version">:material-tag: v0.41.0</span></a>

This method returns the TLS configuration for secure connections to the Cassandra container. It can only be used when the container was created with the `WithTLS()` option. Returns an error if TLS was not enabled.


[Get TLS config](../../modules/cassandra/cassandra_test.go) inside_block:tlsConfig

---

### Modules Chroma (`docs/modules/chroma.md`)

# Chroma

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.29.0"><span class="tc-version">:material-tag: v0.29.0</span></a>

## Introduction

The Testcontainers module for Chroma.

## Resources

- [Chroma Docs](https://docs.trychroma.com/getting-started) - Chroma official documentation.
- [Chroma Cookbook](http://cookbook.chromadb.dev) - Community-driven Chroma cookbook.

## Adding this module to your project dependencies

Please run the following command to add the Chroma module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/chroma
```

## Usage example


[Creating a Chroma container](../../modules/chroma/examples_test.go) inside_block:runChromaContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.32.0"><span class="tc-version">:material-tag: v0.32.0</span></a>

!!!info
    The `RunContainer(ctx, opts...)` function is deprecated and will be removed in the next major release of _Testcontainers for Go_.

The Chroma module exposes one entrypoint function to create the Chroma container, and this function receives three parameters:

```golang
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*ChromaContainer, 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(), "chromadb/chroma:1.4.0")`.

### Container Options

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

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The Chroma container exposes the following methods:

#### REST Endpoint

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.29.0"><span class="tc-version">:material-tag: v0.29.0</span></a>

This method returns the REST endpoint of the Chroma container, using the default `8000` port.


[Get REST endpoint](../../modules/chroma/chroma_test.go) inside_block:restEndpoint


## Examples

### Getting a Chroma client

The following example demonstrates how to create a Chroma client using the Chroma module.

First of all, you need to import the Chroma module and the chroma-go client:

```golang
import (
    chromago "github.com/amikos-tech/chroma-go/pkg/api/v2"
)
```

Then, you can create a Chroma client using the Chroma module:


[Get the client](../../modules/chroma/examples_test.go) inside_block:getClient


### Working with Collections


[Create Collection](../../modules/chroma/examples_test.go) inside_block:createCollection
[List Collections](../../modules/chroma/examples_test.go) inside_block:listCollections
[Add Data to Collection](../../modules/chroma/examples_test.go) inside_block:addData
[Query Collection](../../modules/chroma/examples_test.go) inside_block:queryCollection
[Delete Collection](../../modules/chroma/examples_test.go) inside_block:deleteCollection

---

### Modules Clickhouse (`docs/modules/clickhouse.md`)

# ClickHouse

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.23.0"><span class="tc-version">:material-tag: v0.23.0</span></a>

## Introduction

The Testcontainers module for ClickHouse.

## Adding this module to your project dependencies

Please run the following command to add the ClickHouse module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/clickhouse
```

## Usage example


[Test for a ClickHouse container](../../modules/clickhouse/examples_test.go) inside_block:runClickHouseContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.32.0"><span class="tc-version">:material-tag: v0.32.0</span></a>

!!!info
    The `RunContainer(ctx, opts...)` function is deprecated and will be removed in the next major release of _Testcontainers for Go_.

The ClickHouse module exposes one entrypoint function to create the ClickHouse container, and this function receives three parameters:

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

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

### Container Ports

Here you can find the list with the default ports used by the ClickHouse container.


[Container Ports](../../modules/clickhouse/clickhouse.go) inside_block:containerPorts


#### Image

Use the second argument in the `Run` function to set a valid Docker image.
In example: `Run(context.Background(), "clickhouse/clickhouse-server:23.3.8.21-alpine")`.

### Container Options

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

#### Set username, password and database name

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.23.0"><span class="tc-version">:material-tag: v0.23.0</span></a>

If you need to set a different database, and its credentials, you can use `WithUsername`, `WithPassword`, `WithDatabase`
options. E.g. `WithUsername("user")`, `WithPassword("password")`, `WithDatabase("db")`.

!!!info
    The default values for the username is `default`, for password is `clickhouse` and for the default database name is `clickhouse`.

#### WithInitScripts

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.23.0"><span class="tc-version">:material-tag: v0.23.0</span></a>

If you would like to do additional initialization in the ClickHouse container, add one or more `*.sql`, `*.sql.gz`, or `*.sh` scripts to the container request.
Those files will be copied after the container is created but before it's started under `/docker-entrypoint-initdb.d`. According to ClickHouse Docker image,
it will run any `*.sql` files, run any executable `*.sh` scripts, and source any non-executable `*.sh` scripts found in that directory to do further
initialization before starting the service.


[Include init scripts](../../modules/clickhouse/clickhouse_test.go) inside_block:withInitScripts



[Init script content](../../modules/clickhouse/testdata/init-db.sh)


#### Zookeeper

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.28.0"><span class="tc-version">:material-tag: v0.28.0</span></a>

Clusterized ClickHouse requires to start Zookeeper and pass link to it via `config.xml`.


[Include zookeeper](../../modules/clickhouse/clickhouse_test.go) inside_block:withZookeeper


!!!warning
    The `WithZookeeper` option will `panic` if it's not possible to create the Zookeeper config file.

#### WithConfigFile

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.23.0"><span class="tc-version">:material-tag: v0.23.0</span></a>

If you need to set a custom configuration, the module provides the `WithConfigFile` option to pass the path to a custom configuration file in XML format.


[XML config file](../../modules/clickhouse/testdata/config.xml)


In the case you want to pass a YAML configuration file, you can use the `WithYamlConfigFile` option.


[YAML config file](../../modules/clickhouse/testdata/config.yaml)


{% include "../features/common_functional_options_list.md" %}

### Container Methods

The ClickHouse container exposes the following methods:

#### ConnectionHost

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.23.0"><span class="tc-version">:material-tag: v0.23.0</span></a>

This method returns the host and port of the ClickHouse container, using the default, native `9000/tcp` port. E.g. `localhost:9000`


[Get connection host](../../modules/clickhouse/clickhouse_test.go) inside_block:connectionHost


#### ConnectionString

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.23.0"><span class="tc-version">:material-tag: v0.23.0</span></a>

This method returns the dsn connection string to connect to the ClickHouse container, using the default, native `9000/tcp` port obtained from the `ConnectionHost` method.
It's possible to pass extra parameters to the connection string, e.g. `dial_timeout=300ms` or `skip_verify=false`, in a variadic way.

e.g. `clickhouse://default:pass@localhost:9000?dial_timeout=300ms&skip_verify=false`


[Get connection string](../../modules/clickhouse/clickhouse_test.go) inside_block:connectionString

---

### Modules Cockroachdb (`docs/modules/cockroachdb.md`)

# CockroachDB

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.28.0"><span class="tc-version">:material-tag: v0.28.0</span></a>

## Introduction

The Testcontainers module for CockroachDB.

## Adding this module to your project dependencies

Please run the following command to add the CockroachDB module to your Go dependencies:

```shell
go get github.com/testcontainers/testcontainers-go/modules/cockroachdb
```

## Usage example


[Creating a CockroachDB container](../../modules/cockroachdb/examples_test.go) inside_block:runCockroachDBContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.32.0"><span class="tc-version">:material-tag: v0.32.0</span></a>

!!!info
    The `RunContainer(ctx, opts...)` function is deprecated and will be removed in the next major release of _Testcontainers for Go_.

The CockroachDB module exposes one entrypoint function to create the CockroachDB container, and this function receives three parameters:

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

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

### Container Options

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

#### Image

Use the second argument in the `Run` function to set a valid Docker image.
In example: `Run(context.Background(), "cockroachdb/cockroach:latest-v23.1")`.

#### Database

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.28.0"><span class="tc-version">:material-tag: v0.28.0</span></a>

Set the database that is created & dialled with `cockroachdb.WithDatabase`.

#### User and Password

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.28.0"><span class="tc-version">:material-tag: v0.28.0</span></a>

You can configure the container to create a user with a password by setting `cockroachdb.WithUser` and `cockroachdb.WithPassword`.

`cockroachdb.WithPassword` is incompatible with `cockroachdb.WithInsecure`.

#### Store size

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.28.0"><span class="tc-version">:material-tag: v0.28.0</span></a>

Control the maximum amount of memory used for storage, by default this is 100% but can be changed by provided a valid option to `WithStoreSize`. Checkout https://www.cockroachlabs.com/docs/stable/cockroach-start#store for the full range of options available.

#### TLS authentication

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.35.0"><span class="tc-version">:material-tag: v0.35.0</span></a>

`cockroachdb.WithInsecure` lets you disable the use of TLS on connections.

`cockroachdb.WithInsecure` is incompatible with `cockroachdb.WithPassword`.

#### Initialization Scripts

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.35.0"><span class="tc-version">:material-tag: v0.35.0</span></a>

`cockroachdb.WithInitScripts` adds the given scripts to those automatically run when the container starts.
These will be ignored if data exists in the `/cockroach/cockroach-data` directory within the container.

#### No Cluster Defaults

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.35.0"><span class="tc-version">:material-tag: v0.35.0</span></a>

`cockroachdb.WithNoClusterDefaults` disables the default cluster settings script.

Without this option Cockroach containers run `data/cluster-defaults.sql` on startup
which configures the settings recommended by Cockroach Labs for
[local testing clusters](https://www.cockroachlabs.com/docs/stable/local-testing)
unless data exists in the `/cockroach/cockroach-data` directory within the container.

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The CockroachDB container exposes the following methods:

#### ConnectionString

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.28.0"><span class="tc-version">:material-tag: v0.28.0</span></a>

Dial address to open a new connection.

#### MustConnectionString

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.28.0"><span class="tc-version">:material-tag: v0.28.0</span></a>

Same as `ConnectionString` but any error to generate the address will raise a panic

#### TLSConfig

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.28.0"><span class="tc-version">:material-tag: v0.28.0</span></a>

Returns `*tls.Config` setup to allow you to dial your client over TLS, if enabled, else this will error with `cockroachdb.ErrTLSNotEnabled`.

!!!info
    The `TLSConfig()` function is deprecated and will be removed in the next major release of _Testcontainers for Go_.

#### ConnectionConfig

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.35.0"><span class="tc-version">:material-tag: v0.35.0</span></a>

Returns `*pgx.ConnConfig` which can be passed to `pgx.ConnectConfig` to open a new connection.

---

### Modules Consul (`docs/modules/consul.md`)

# Consul

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.28.0"><span class="tc-version">:material-tag: v0.28.0</span></a>

## Introduction

The Testcontainers module for Consul.

## Adding this module to your project dependencies

Please run the following command to add the Consul module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/consul
```

## Usage example


[Creating a Consul container](../../modules/consul/examples_test.go) inside_block:runConsulContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.32.0"><span class="tc-version">:material-tag: v0.32.0</span></a>

!!!info
    The `RunContainer(ctx, opts...)` function is deprecated and will be removed in the next major release of _Testcontainers for Go_.

The Consul module exposes one entrypoint function to create the Consul container, and this function receives three parameters:

```golang
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*ConsulContainer, 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(), "hashicorp/consul:1.15")`.

### Container Options

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

#### Configuration File

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.28.0"><span class="tc-version">:material-tag: v0.28.0</span></a>

If you need to customize the behavior for the deployed node you can use either `WithConfigString(config string)` or `WithConfigFile(configPath string)`.
The configuration has to be in JSON format and will be loaded at the node startup.

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The Consul container exposes the following method:

#### ApiEndpoint

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.28.0"><span class="tc-version">:material-tag: v0.28.0</span></a>

This method returns the connection string to connect to the Consul container API, using the default `8500` port.


[Using ApiEndpoint with the Consul client](../../modules/consul/examples_test.go) inside_block:connectConsul

---

### Modules Couchbase (`docs/modules/couchbase.md`)

# Couchbase

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>

## Introduction

The Testcontainers module for Couchbase.

## Adding this module to your project dependencies

Please run the following command to add the Couchbase module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/couchbase
```

## Usage example


[Creating a Couchbase container](../../modules/couchbase/examples_test.go) inside_block:runCouchbaseContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.32.0"><span class="tc-version">:material-tag: v0.32.0</span></a>

!!!info
    The `RunContainer(ctx, opts...)` function is deprecated and will be removed in the next major release of _Testcontainers for Go_.

The Couchbase module exposes one entrypoint function to create the Couchbase container, and this function receives three parameters:

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

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

Once the container is started, it will perform the following operations, **in this particular order**:

* Wait until the node is online, waiting for the `/pools` endpoint in the management port to return a 200 HTTP status code.
* Check for Enterprise services, sending a GET request to the `/pools` endpoint in the management port. If the response contains the `isEnterprise` key set to `false`, it will check if the Analytics or the Eventing services are enabled. If so, it will raise an error.
* Rename the node, sending a POST request to the `/node/controller/rename` endpoint in the management port.
* Initialize the services, sending a POST request to the `/node/controller/setupServices` endpoint in the management port, passing as body of the request the list of enabled services.
* Set the memory quotas, sending a POST request to the `/pools/default` endpoint in the management port, passing as body of the request the memory quota for each enabled service.
* Configure the Admin user, sending a POST request to the `/settings/web` endpoint in the management port, passing as body of the request the username and password of the admin user.
* Configure the external ports, sending a POST request to the `/node/controller/setupAlternateAddresses/external` endpoint in the management port, passing as body of the request the external mapped ports for each enabled service.
* If the `Index` service is enabled, configure the indexer, sending a POST request to the `/settings/indexes` endpoint in the management port, passing as body of the request the defined storage mode. If the Community Edition is used, it will make sure the storage mode is `forestdb`. If the Enterprise Edition is used, it will make sure the storage mode is not `forestdb`, changing to `memory_optimized` in that case.
* Finally, it will wait for all nodes to be healthy. Depending on the enabled services, it will use a different wait strategy to check if the node is healthy:
	- It will wait for the `/pools/default` endpoint in the management port to return a 200 HTTP status code and the response body to contain the `healthy` key set to `true`.
	- If the `Query` service is enabled, it will wait for the `/admin/ping` endpoint in the query port to return a 200 HTTP status code.
	- If the `Analytics` service is enabled, it will wait for the `/admin/ping` endpoint in the analytics port to return a 200 HTTP status code.
	- If the `Eventing` service is enabled, it will wait for the `/api/v1/config` endpoint in the eventing port to return a 200 HTTP status code.

### Container Ports

Here you can find the list with the default ports used by the Couchbase container. The Management ports (`MGMT_PORT` and `MGMT_SSL_PORT`) and the Service ports for `kv`, `query` and `search` are exposed by default.

!!!tip
	You can export the service ports for Analytics and Eventing by using the `WithServiceAnalytics` and `WithServiceEventing` optional functions.


[Container Ports](../../modules/couchbase/couchbase.go) inside_block:containerPorts



#### Image

Use the second argument in the `Run` function to set a valid Docker image.
In example: `Run(context.Background(), "couchbase:6.5.1")`.

You can find the Docker images that are currently tested in this module, for the Enterprise and Community editions, in the following list:


[Docker images](../../modules/couchbase/couchbase_test.go) inside_block:dockerImages


### Container Options

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

#### Credentials

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>

If you need to change the default credentials for the admin user, you can use `WithAdminCredentials(user, password)` with a valid username and password.
When the password has less than 6 characters, the container won't be created and the `New` function will throw an error.

!!!info
	In the case this optional function is not called, the default username is `Administrator` and the default password is `password`.

#### Buckets

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>

When creating a new Couchbase container, you can create one or more buckets. The module exposes a `WithBuckets` optional function that accepts a slice of buckets to be created.
To create a new bucket, the module also exposes a `NewBucket` function, where you can pass the bucket name.

It's possible to customize a newly created bucket, using the following options:

- `WithQuota`: sets the bucket quota in megabytes. The minimum value is 100 MB.
- `WithReplicas`: sets the number of replicas for this bucket. The minimum value is 0 and the maximum value is 3.
- `WithFlushEnabled`: sets whether the bucket should be flushed when the container is stopped.
- `WithPrimaryIndex`: sets whether the primary index should be created for this bucket.


[Adding a new bucket](../../modules/couchbase/couchbase_test.go) inside_block:withBucket


#### Index Storage

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>

It's possible to set the storage mode to be used for all global secondary indexes in the cluster.

!!!warning
	Please note: `plasma` and `memory optimized` are options in the **Enterprise Edition** of Couchbase Server. If you are using the Community Edition, the only value allowed is `forestdb`.


[Storage types](../../modules/couchbase/storage_mode.go) inside_block:storageTypes


#### Services

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>

By default, the container will start with the following services: `kv`, `n1ql`, `fts` and `index`.

!!!warning
	When running the Enterprise Edition of Couchbase Server, the module provides two functions to enable or disable services:
	`WithServiceAnalytics` and `WithServiceEventing`. Else, it will throw an error and the container won't be created.

{% include "../features/common_functional_options_list.md" %}

### Container Methods

#### ConnectionString

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>

The `ConnectionString` method returns the connection string to connect to the Couchbase container instance. 
It returns a string with the format `couchbase://<host>:<port>`.

#### Username

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>

The `Username` method returns the username of the Couchbase administrator. 

#### Password

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>

The `Password` method returns the password of the Couchbase administrator.

---

### Modules Couchdb (`docs/modules/couchdb.md`)

# CouchDB

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

## Introduction

The Testcontainers module for Apache CouchDB, a document-oriented NoSQL database that uses JSON to store data, JavaScript as its query language using MapReduce, and HTTP for an API.

## Adding this module to your project dependencies

Please run the following command to add the CouchDB module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/couchdb
```

## Usage example


[Creating a CouchDB container](../../modules/couchdb/examples_test.go) inside_block:runCouchDBContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

The CouchDB module exposes one entrypoint function to create the CouchDB container, and this function receives three parameters:

```golang
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(), "couchdb:3")`.

### Container Options

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

#### WithAdminCredentials

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

Sets the admin username and password for the CouchDB container.
These credentials are used to authenticate against the CouchDB HTTP API and are reflected in the connection string returned by `ConnectionString`.

The default credentials are `admin` / `password`.

E.g. `couchdb.WithAdminCredentials("myuser", "mypassword")`.

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The CouchDB container exposes the following methods:

#### ConnectionString

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

The `ConnectionString` method returns the connection string to connect to the CouchDB container.
It returns a string with the format `http://user:password@host:5984`.

E.g. `http://admin:password@localhost:32768`.

It can be used to configure a CouchDB HTTP client:


[Using ConnectionString](../../modules/couchdb/examples_test.go) inside_block:runCouchDBContainer

---

### Modules Cratedb (`docs/modules/cratedb.md`)

# CrateDB

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

## Introduction

The Testcontainers module for CrateDB.

CrateDB is a distributed SQL database that combines the power of Lucene-based full-text search with the convenience of standard SQL. It offers PostgreSQL wire-protocol compatibility, making it easy to connect with existing PostgreSQL drivers and tools, and is optimised for real-time analytics on large datasets.

## Adding this module to your project dependencies

Please run the following command to add the CrateDB module to your Go dependencies:

```shell
go get github.com/testcontainers/testcontainers-go/modules/cratedb
```

## Usage example


[Creating a CrateDB container](../../modules/cratedb/examples_test.go) inside_block:runCrateDBContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

The CrateDB module exposes one entrypoint function to create the CrateDB container, and this function receives three parameters:

```golang
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.

### Container Ports

Here you can find the list with the default ports used by the CrateDB container.


[Container Ports](../../modules/cratedb/cratedb.go) inside_block:containerPorts


#### Image

Use the second argument in the `Run` function to set a valid Docker image.
For example: `Run(context.Background(), "crate:5.7")`.

### Container Options

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

#### WithHeapSize

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

Sets the JVM heap size for the CrateDB process via the `CRATE_HEAP_SIZE` environment variable.
The default value is `512m`.

```golang
cratedb.WithHeapSize("1g")
```

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The CrateDB container exposes the following methods:

#### HTTPEndpoint

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

Returns the HTTP endpoint (Admin UI and REST API) of the CrateDB container on port `4200/tcp`.

```golang
endpoint, err := cratedbContainer.HTTPEndpoint(ctx)
// endpoint: "http://localhost:32768"
```

#### PGConnectionString

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

Returns the PostgreSQL wire-protocol connection string for the CrateDB container on port `5432/tcp`.
CrateDB's built-in superuser is `crate` with no password, and the default schema is `doc`.
Accepts an optional variadic list of extra query parameters, e.g. `"sslmode=disable"` or `"connect_timeout=10"`.

```golang
connStr, err := cratedbContainer.PGConnectionString(ctx, "sslmode=disable")
// connStr: "postgres://crate@localhost:32769/doc?sslmode=disable"
```

---

### Modules Databend (`docs/modules/databend.md`)

# Databend

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.34.0"><span class="tc-version">:material-tag: v0.34.0</span></a>

## Introduction

The Testcontainers module for Databend.

## Adding this module to your project dependencies

Please run the following command to add the Databend module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/databend
```

## Usage example


[Creating a Databend container](../../modules/databend/examples_test.go) inside_block:runDatabendContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.34.0"><span class="tc-version">:material-tag: v0.34.0</span></a>

The Databend module exposes one entrypoint function to create the Databend container, and this function receives three parameters:

```golang
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*DatabendContainer, 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(), "datafuselabs/databend:v1.2.615")`.

### Container Options

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

#### Set username, password

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.34.0"><span class="tc-version">:material-tag: v0.34.0</span></a>

If you need to set a different user/password/database, you can use `WithUsername`, `WithPassword` options.

!!!info
The default values for the username is `databend`, for password is `databend` and for the default database name is `default`.

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The Databend container exposes the following methods:

#### ConnectionString

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.34.0"><span class="tc-version">:material-tag: v0.34.0</span></a>

This method returns the connection string to connect to the Databend container, using the default `8000` port.
It's possible to pass extra parameters to the connection string, e.g. `sslmode=disable`.


[Get connection string](../../modules/databend/databend_test.go) inside_block:connectionString


#### MustGetConnectionString

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.34.0"><span class="tc-version">:material-tag: v0.34.0</span></a>

`MustConnectionString` panics if the address cannot be determined.

---

### Modules Dex (`docs/modules/dex.md`)

# Dex

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.43.0"><span class="tc-version">:material-tag: v0.43.0</span></a>

## Introduction

The Testcontainers module for [Dex](https://dexidp.io/), a CNCF-sandbox OIDC
provider. The module lets Go tests spin up a real Dex instance and exercise
OAuth2/OIDC flows end-to-end instead of mocking the token endpoint.

## Adding this module to your project dependencies

Please run the following command to add the Dex module to your Go dependencies:

```bash
go get github.com/testcontainers/testcontainers-go/modules/dex
```

## Usage example


[Creating a Dex container](../../modules/dex/examples_test.go) inside_block:runContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.43.0"><span class="tc-version">:material-tag: v0.43.0</span></a>

The Dex module exposes one entrypoint function to create the Dex container,
and this function receives three parameters:

```golang
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(), "dexidp/dex:v2.45.1")`.

!!! warning
    The `client_credentials` grant requires Dex ≥ v2.46.0 or the
    `dexidp/dex:master` image. On `v2.45.x` and earlier the token endpoint
    returns `unsupported_grant_type` even with `WithEnableClientCredentials()`
    set. The module does not validate the image tag — pin a compatible image
    when using that grant.

### Container Options

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

#### Clients

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.43.0"><span class="tc-version">:material-tag: v0.43.0</span></a>

`Client` is an opaque value type. Construct it with `NewClient(id, opts...)`
so invalid values surface at call-site. `NewClient` returns
`(Client, error)`; client options accept variadic URIs and grant types.

```golang
app, err := dex.NewClient("my-app",
    dex.WithClientSecret("secret"),
    dex.WithClientRedirectURIs("http://localhost:8080/callback"),
    dex.WithClientGrantTypes("authorization_code", "refresh_token"),
    dex.WithClientName("My App"),
)
// ...
c, err := dex.Run(ctx, "dexidp/dex:v2.45.1", dex.WithClient(app))
```

Additional client options: `WithClientPublic()` marks the client as public
(PKCE, no secret).

Clients added at runtime via `AddClient` inherit Dex's defaults
(`authorization_code` + `refresh_token`) because Dex's gRPC `api.Client`
proto has no `grant_types` field. Clients needing other grants must be
declared pre-start via `WithClient`.

#### Users

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.43.0"><span class="tc-version">:material-tag: v0.43.0</span></a>

`User` is an opaque value type. `NewUser(email, username, password, opts...)`
returns `(User, error)`. Use `WithUserID(id)` to pin the stable `sub` claim;
otherwise a UUIDv4 is generated at YAML render time.

```golang
user, err := dex.NewUser("user@example.com", "user", "password",
    dex.WithUserID("stable-sub-123"),
)
// ...
c, err := dex.Run(ctx, "dexidp/dex:v2.45.1", dex.WithUser(user))
```

Adding `WithUser` keeps Dex's built-in password DB connector enabled. Use
`WithDisablePasswordDB()` to turn it off when the configuration only uses
other connectors.

#### Connectors

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.43.0"><span class="tc-version">:material-tag: v0.43.0</span></a>

`WithConnector(type, id, name)` enables a Dex connector. Supported types:

- `ConnectorPassword` — Dex's built-in static password DB. Enabled by
  default; no-op when passed explicitly.
- `ConnectorMock` — Dex's `mockCallback` test connector. Returns a fixed
  user (`kilgore@kilgore.trout`) and bypasses the login form.

Blank `id` or `name` values are rejected at `Run` time.

#### Issuer

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.43.0"><span class="tc-version">:material-tag: v0.43.0</span></a>

By default the issuer is derived from the host and mapped HTTP port:
`http://<host>:<mappedPort>/dex`. `WithIssuer(url)` overrides the default.
Use it when the issuer must be reachable from other containers (shared
Docker network with a network alias); the caller owns reachability.

#### Storage

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.43.0"><span class="tc-version">:material-tag: v0.43.0</span></a>

`WithStorage(Storage)` selects Dex's storage backend. Available constants:

- `StorageSQLite` — on-disk SQLite database (default). Ephemeral; destroyed
  with the container.
- `StorageMemory` — in-process. Fastest; not shared across replicas.

#### Logging

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.43.0"><span class="tc-version">:material-tag: v0.43.0</span></a>

`WithLogger(*slog.Logger)` routes Dex container logs through a `slog.Logger`.
Unset by default — container logs are discarded. Stderr lines are promoted
to at least `slog.LevelWarn` because Dex writes runtime errors there.

`WithLogLevel(slog.Level)` sets Dex's own `logger.level` YAML key. Values
between slog's fixed levels round down. Default: `slog.LevelInfo`.

#### Client credentials grant

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.43.0"><span class="tc-version">:material-tag: v0.43.0</span></a>

`WithEnableClientCredentials()` sets the env var
`DEX_CLIENT_CREDENTIAL_GRANT_ENABLED_BY_DEFAULT=true`, which Dex ≥ v2.46.0
reads to enable the OAuth2 `client_credentials` grant. Pair with a
compatible image (see the `Image` warning above).

#### Approval screen

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.43.0"><span class="tc-version">:material-tag: v0.43.0</span></a>

`WithSkipApprovalScreen(bool)` toggles Dex's `oauth2.skipApprovalScreen`.
Default: `true` (tests rarely want a human-in-the-loop prompt).

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The Dex container exposes the following methods:

#### IssuerURL

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.43.0"><span class="tc-version">:material-tag: v0.43.0</span></a>

Returns Dex's issuer URL. Empty if `Run` has not started.

#### ConfigEndpoint

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.43.0"><span class="tc-version">:material-tag: v0.43.0</span></a>

Returns the OIDC discovery document URL (`/.well-known/openid-configuration`).

#### JWKSEndpoint

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.43.0"><span class="tc-version">:material-tag: v0.43.0</span></a>

Returns the JSON Web Key Set URL (`/keys`).

#### TokenEndpoint

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.43.0"><span class="tc-version">:material-tag: v0.43.0</span></a>

Returns the OAuth2 token URL (`/token`).

#### AuthEndpoint

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.43.0"><span class="tc-version">:material-tag: v0.43.0</span></a>

Returns the OAuth2 authorization URL (`/auth`).

#### GRPCEndpoint

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.43.0"><span class="tc-version">:material-tag: v0.43.0</span></a>

Returns `host:mappedPort` for Dex's gRPC admin API. Takes a `context.Context`
and returns an error if the container is not started or the Docker API
call fails.

```golang
target, err := c.GRPCEndpoint(ctx)
```

#### AddClient

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.43.0"><span class="tc-version">:material-tag: v0.43.0</span></a>

Registers a client at runtime via Dex's gRPC admin API. Returns
`ErrClientExists` when the ID is already registered. Not safe for
concurrent use.

#### RemoveClient

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.43.0"><span class="tc-version">:material-tag: v0.43.0</span></a>

Deletes a client by ID. Returns a plain error containing `"not found"` for
unknown IDs. Not safe for concurrent use.

#### AddUser

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.43.0"><span class="tc-version">:material-tag: v0.43.0</span></a>

Registers a user in Dex's password DB at runtime via gRPC. Returns
`ErrUserExists` when the email is already registered. Not safe for
concurrent use.

#### RemoveUser

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.43.0"><span class="tc-version">:material-tag: v0.43.0</span></a>

Deletes a user by email. Returns a plain error containing `"not found"` for
unknown emails. Not safe for concurrent use.

### ID token claims

Dex's password connector emits these standard claims in ID tokens:

- `sub` — stable user ID (auto-generated UUIDv4 when `NewUser` is called
  without `WithUserID`).
- `email` — user's email address.
- `email_verified` — always `true` for static password entries.
- `name` — the username.
- `iss` — the issuer URL.
- `aud` — the client ID.

Dex does NOT emit the `preferred_username` claim; use the `name` claim
instead when a human-readable identifier is needed.

### Known limitations

- Runtime-added clients inherit Dex's default grants.
- `client_credentials` requires `WithEnableClientCredentials()` and Dex ≥
  v2.46.0 or the `:master` image tag.
- gRPC admin API is plaintext. TLS not supported day 1.
- `mockCallback` emits a fixed user; parameterized flows need the password
  connector with a pre-seeded user.
- SQLite storage is container-local and ephemeral.
- Bcrypt cost ≥ 10 is enforced by Dex for both YAML and gRPC password paths.

---

### Modules Dind (`docs/modules/dind.md`)

# DinD (Docker in Docker)

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.36.0"><span class="tc-version">:material-tag: v0.36.0</span></a>

## Introduction

The Testcontainers module for DinD (Docker in Docker).

## Adding this module to your project dependencies

Please run the following command to add the DinD module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/dind
```

## Usage example


[Creating a DinD container](../../modules/dind/examples_test.go) inside_block:runDinDContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.36.0"><span class="tc-version">:material-tag: v0.36.0</span></a>

The DinD module exposes one entrypoint function to create the DinD container, and this function receives three parameters:

```golang
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

If you need to set a different DinD Docker image, you can set a valid Docker image as the second argument in the `Run` function.
E.g. `Run(context.Background(), "docker:28.0.1-dind")`.

### Container Options

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

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The DinD container exposes the following methods:

#### Host

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.36.0"><span class="tc-version">:material-tag: v0.36.0</span></a>

The `Host` method returns the DinD URL, to be used for connecting
to the Docker API using a Docker client. It'll be returned in the format of `string`.


[Host](../../modules/dind/examples_test.go) inside_block:didnHost
[Get a Docker client](../../modules/dind/examples_test.go) inside_block:getDockerClient


#### LoadImage

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.36.0"><span class="tc-version">:material-tag: v0.36.0</span></a>

The `LoadImage` method loads an image into the docker in docker daemon.

This is useful for testing images generated locally without having to push them to a public docker registry.

The images must be already present in the node running the test. [DockerProvider](https://pkg.go.dev/github.com/testcontainers/testcontainers-go#DockerProvider) offers a method for pulling images, which can be used from the test code to ensure the image is present locally before loading them to the daemon.

---

### Modules Dockermcpgateway (`docs/modules/dockermcpgateway.md`)

# Docker MCP Gateway

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.39.0"><span class="tc-version">:material-tag: v0.39.0</span></a>

## Introduction

The Testcontainers module for the Docker MCP Gateway.

## Adding this module to your project dependencies

Please run the following command to add the Docker MCP Gateway module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/dockermcpgateway
```

## Usage example


[Creating a DockerMCPGateway container](../../modules/dockermcpgateway/examples_test.go) inside_block:run_mcp_gateway


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.39.0"><span class="tc-version">:material-tag: v0.39.0</span></a>

The DockerMCPGateway module exposes one entrypoint function to create the DockerMCPGateway container, and this function receives three parameters:

```golang
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(), "docker/mcp-gateway:latest")`.

### Container Options

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

{% include "../features/common_functional_options_list.md" %}

#### WithTools

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.39.0"><span class="tc-version">:material-tag: v0.39.0</span></a>

Use the `WithTools` option to set the tools from a server to be available in the MCP Gateway container. Adding multiple tools for the same server will append to the existing tools for that server, and no duplicate tools will be added for the same server.

```golang
dockermcpgateway.WithTools("brave", []string{"brave_local_search", "brave_web_search"})
```

#### WithSecrets

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.39.0"><span class="tc-version">:material-tag: v0.39.0</span></a>

Use the `WithSecrets` option to set the tools from a server to be available in the MCP Gateway container. Empty keys are not allowed, although empty values are allowed for a key.

```golang
dockermcpgateway.WithSecret("github_token", "test_value")
dockermcpgateway.WithSecrets(map[string]{
    "github_token": "test_value",
    "foo":          "bar",
})
```

### Container Methods

The DockerMCPGateway container exposes the following methods:

#### Tools

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.39.0"><span class="tc-version">:material-tag: v0.39.0</span></a>

Returns a map of tools available in the MCP Gateway container, where the key is the server name and the value is a slice of tool names.

```golang
tools := ctr.Tools()
```

#### GatewayEndpoint

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.39.0"><span class="tc-version">:material-tag: v0.39.0</span></a>

Returns the endpoint of the MCP Gateway container, which is a string containing the host and mapped port for the default MCP Gateway port (8811/tcp).

```golang
endpoint := ctr.GatewayEndpoint()
```
### Examples

#### Connecting to the MCP Gateway using an MCP client

This example shows the usage of the MCP Gateway module to connect with an [MCP client](https://github.com/modelcontextprotocol/go-sdk).


[Run the MCP Gateway](../../modules/dockermcpgateway/examples_test.go) inside_block:run_mcp_gateway
[Get MCP Gateway's endpoint](../../modules/dockermcpgateway/examples_test.go) inside_block:get_gateway
[Connect with an MCP client](../../modules/dockermcpgateway/examples_test.go) inside_block:connect_mcp_client
[List tools](../../modules/dockermcpgateway/examples_test.go) inside_block:list_tools

---

### Modules Dockermodelrunner (`docs/modules/dockermodelrunner.md`)

# Docker Model Runner

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

## Introduction

The Testcontainers module for DockerModelRunner.

## Adding this module to your project dependencies

Please run the following command to add the DockerModelRunner module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/dockermodelrunner
```

## Usage example


[Creating a DockerModelRunner container](../../modules/dockermodelrunner/examples_test.go) inside_block:runWithModel


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

The Docker Model Runner module exposes two entrypoint functions to create the Docker Model Runner container:

#### Run

This function receives two parameters:

```golang
func Run(ctx context.Context, opts ...testcontainers.ContainerCustomizer) (*Container, error)
```

- `context.Context`, the Go context.
- `testcontainers.ContainerCustomizer`, a variadic argument for passing options.

!!! info
    This function will use the default `socat` image under the hood. Please refer to the [socat module](../socat.md) for more information.

#### Image

Use the second argument in the `Run` function to set a valid Docker image.
In example: `Run(context.Background(), "alpine/socat:1.8.0.1")`.

### Container Options

When starting the Docker Model Runner container, you can pass options in a variadic way to configure it.

#### WithModel

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

Use the `WithModel` option to set the model to pull when the container is started. Please be aware, that only Models as OCI Artifacts are compatible with Docker Model Runner.

```golang
dockermodelrunner.WithModel("ai/llama3.2:latest")
```

!!! warning
    Multiple calls to this function overrides the previous value.

 You can find a curated collection of cutting-edge AI models as OCI Artifacts, from lightweight on-device models to high-performance LLMs on [Docker Hub](https://hub.docker.com/u/ai).

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The Docker Model Runner container exposes the following methods:

#### PullModel

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

Use the `PullModel` method to pull a model from the Docker Model Runner. Make sure the passed context is not done before the pull operation is completed, so that the pull operation is cancelled.


[Pulling a model at runtime](../../modules/dockermodelrunner/examples_test.go) inside_block:runPullModel


!!! info
     You can find a curated collection of cutting-edge AI models as OCI Artifacts, from lightweight on-device models to high-performance LLMs on [Docker Hub](https://hub.docker.com/u/ai).

#### InspectModel

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

Use the `InspectModel` method to inspect a model from the Docker Model Runner, by providing the model namespace and name.


[Getting a model at runtime](../../modules/dockermodelrunner/examples_test.go) inside_block:runInspectModel


The namespace and name of the model is in the format of `<name>:<tag>`, which defines Models as OCI Artifacts in Docker Hub, therefore the namespace is the organization and the name is the repository.

E.g. `ai/smollm2:360M-Q4_K_M`. See [Models as OCI Artifacts](https://hub.docker.com/u/ai) for more information.

#### ListModels

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

Use the `ListModels` method to list all models that are already pulled locally, using the Docker Model Runner format.


[Listing all models](../../modules/dockermodelrunner/examples_test.go) inside_block:runListModels

---

### Modules Dolt (`docs/modules/dolt.md`)

# Dolt

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.31.0"><span class="tc-version">:material-tag: v0.31.0</span></a>

## Introduction

The Testcontainers module for Dolt.

## Adding this module to your project dependencies

Please run the following command to add the Dolt module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/dolt
```

## Usage example


[Creating a Dolt container](../../modules/dolt/examples_test.go) inside_block:runDoltContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.32.0"><span class="tc-version">:material-tag: v0.32.0</span></a>

!!!info
    The `RunContainer(ctx, opts...)` function is deprecated and will be removed in the next major release of _Testcontainers for Go_.

The Dolt module exposes one entrypoint function to create the Dolt container, and this function receives three parameters:

```golang
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*DoltContainer, 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(), "dolthub/dolt-sql-server:1.32.4")`.

### Container Options

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

#### Set username, password and database name

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.31.0"><span class="tc-version">:material-tag: v0.31.0</span></a>

If you need to set a different database, and its credentials, you can use `WithUsername`, `WithPassword`, `WithDatabase`
options.

!!!info
The default values for the username is `root`, for password is `test` and for the default database name is `test`.

#### WithScripts

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.31.0"><span class="tc-version">:material-tag: v0.31.0</span></a>

If you would like to perform DDL or DML operations in the Dolt container, add one or more `*.sql`, `*.sql.gz`, or `*.sh`
scripts to the container request, using the `WithScripts(scriptPaths ...string)`. Those files will be copied under `/docker-entrypoint-initdb.d`.

#### WithDoltCloneRemoteUrl

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.31.0"><span class="tc-version">:material-tag: v0.31.0</span></a>

If you would like to clone data from a remote into the Dolt container, add an `*.sh`
scripts to the container request, using the `WithScripts(scriptPaths ...string)`. Additionally, use `WithDoltCloneRemoteUrl(url string)` to specify
the remote to clone, and use `WithDoltCredsPublicKey(key string)` along with `WithCredsFile(credsFile string)` to authorize the Dolt container to clone from the remote.


[Example of Clone script](../../modules/dolt/testdata/clone-db.sh)


#### WithConfigFile

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.31.0"><span class="tc-version">:material-tag: v0.31.0</span></a>

If you need to set a custom configuration, you can use `WithConfigFile` option to pass the path to a custom configuration file.

{% include "../features/common_functional_options_list.md" %}

### Container Methods

#### ConnectionString

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.31.0"><span class="tc-version">:material-tag: v0.31.0</span></a>

This method returns the connection string to connect to the Dolt container, using the default `3306` port.
It's possible to pass extra parameters to the connection string, e.g. `tls=skip-verify` or `application_name=myapp`, in a variadic way.


[Get connection string](../../modules/dolt/dolt_test.go) inside_block:connectionString

---

### Modules Dynamodb (`docs/modules/dynamodb.md`)

# DynamoDB

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.34.0"><span class="tc-version">:material-tag: v0.34.0</span></a>

## Introduction

The Testcontainers module for DynamoDB.

## Adding this module to your project dependencies

Please run the following command to add the DynamoDB module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/dynamodb
```

## Usage example


[Creating a DynamoDB container](../../modules/dynamodb/examples_test.go) inside_block:runDynamoDBContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.34.0"><span class="tc-version">:material-tag: v0.34.0</span></a>

The DynamoDB module exposes one entrypoint function to create the DynamoDB container, and this function receives three parameters:

```golang
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*DynamoDBContainer, 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(), "amazon/dynamodb-local:2.2.1")`.

### Container Options

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

#### WithSharedDB

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.34.0"><span class="tc-version">:material-tag: v0.34.0</span></a>

The `WithSharedDB` option tells the DynamoDB container to use a single database file. At the same time, it marks the container as reusable, which causes that successive calls to the `Run` function will return the same container instance, and therefore, the same database file.

#### WithDisableTelemetry

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.34.0"><span class="tc-version">:material-tag: v0.34.0</span></a>

You can turn off telemetry when starting the DynamoDB container, using the option `WithDisableTelemetry`.

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The DynamoDB container exposes the following methods:

#### ConnectionString

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.34.0"><span class="tc-version">:material-tag: v0.34.0</span></a>

The `ConnectionString` method returns the connection string to the DynamoDB container. This connection string can be used to connect to the DynamoDB container from your application,
using the AWS SDK or any other DynamoDB client of your choice.


[Creating a client](../../modules/dynamodb/dynamodb_test.go) inside_block:createClient


The above example uses `github.com/aws/aws-sdk-go-v2/service/dynamodb` to create a client and connect to the DynamoDB container.

---

### Modules Elasticsearch (`docs/modules/elasticsearch.md`)

# Elasticsearch

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.24.0"><span class="tc-version">:material-tag: v0.24.0</span></a>

## Introduction

The Testcontainers module for Elasticsearch.

## Adding this module to your project dependencies

Please run the following command to add the Elasticsearch module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/elasticsearch
```

## Usage example


[Creating an Elasticsearch container](../../modules/elasticsearch/examples_test.go) inside_block:runElasticsearchContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.32.0"><span class="tc-version">:material-tag: v0.32.0</span></a>

!!!info
    The `RunContainer(ctx, opts...)` function is deprecated and will be removed in the next major release of _Testcontainers for Go_.

The Elasticsearch module exposes one entrypoint function to create the Elasticsearch container, and this function receives three parameters:

```golang
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*ElasticsearchContainer, 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(), "docker.elastic.co/elasticsearch/elasticsearch:8.0.0")`.

### Container Options

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

#### WithPassword

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.24.0"><span class="tc-version">:material-tag: v0.24.0</span></a>

If you need to set a different password to request authorization when performing HTTP requests to the container, you can use the `WithPassword` option.  By default, the username is set to `elastic`, and the password is set to `changeme`.

!!!info
    In versions of Elasticsearch prior to 8.0.0, the default password is empty.


[Custom Password](../../modules/elasticsearch/examples_test.go) inside_block:usingPassword


{% include "../features/common_functional_options_list.md" %}

### Examples

#### Configuring the access to the Elasticsearch container

The Elasticsearch container exposes its settings in order to configure the client to connect to it. With those settings it's very easy to setup up our preferred way to connect to the container. We are going to show you two ways to connect to the container, using the HTTP client from the standard library, and using the Elasticsearch client.

!!!info
    The `TLS` access is only supported on Elasticsearch 8 and above, so please pay attention to how the below examples are using the `CACert` and `URL` settings.

##### Using the standard library's HTTP client


[Create an HTTP client](../../modules/elasticsearch/elasticsearch_test.go) inside_block:createHTTPClient


The `esContainer` instance is obtained from the `elasticsearch.New` function.

In the case you configured the Elasticsearch container to set up a password, you'll need to add the `Authorization` header to the request. You can use the `SetBasicAuth` method from the HTTP request to generate the header value.


[Using an authenticated client](../../modules/elasticsearch/elasticsearch_test.go) inside_block:basicAuthHeader


##### Using the Elasticsearch client

First, you must install the Elasticsearch Go client, so please read their [install guide](https://www.elastic.co/guide/en/elasticsearch/client/go-api/current/installation.html) for more information.


[Create an Elasticsearch client](../../modules/elasticsearch/examples_test.go) inside_block:elasticsearchClient

---

### Modules Etcd (`docs/modules/etcd.md`)

# etcd

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.34.0"><span class="tc-version">:material-tag: v0.34.0</span></a>

## Introduction

The Testcontainers module for etcd.

## Adding this module to your project dependencies

Please run the following command to add the etcd module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/etcd
```

## Usage example


[Creating a etcd container](../../modules/etcd/examples_test.go) inside_block:runetcdContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.34.0"><span class="tc-version">:material-tag: v0.34.0</span></a>

The etcd module exposes one entrypoint function to create the etcd container, and this function receives three parameters:

```golang
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*EtcdContainer, 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(), "gcr.io/etcd-development/etcd:v3.5.14")`.

### Container Options

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

#### WithAdditionalArgs

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.34.0"><span class="tc-version">:material-tag: v0.34.0</span></a>

You can pass additional arguments to the etcd container by using the `WithAdditionalArgs` option. The arguments are passed to the CMD of the etcd container.

#### WithDataDir

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.34.0"><span class="tc-version">:material-tag: v0.34.0</span></a>

You can set the data directory for the etcd container by using the `WithDataDir` boolean option. The data directory where the etcd data is stored is `/data.etcd`.

#### WithNodes

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.34.0"><span class="tc-version">:material-tag: v0.34.0</span></a>

You can set the number of nodes for the etcd cluster by using the `WithNodes` option, passing the node names for each of the nodes. Single-node clusters are not allowed,
for that reason the functional option receives three string arguments: the first node, the second node, and a variadic argument for the rest of the nodes.
The module starts a container for each node, having the first node a reference to the other nodes. E.g. `WithNodes("etcd-1", "etcd-2")`, `WithNodes("etcd-1", "etcd-2", "etcd-3")` and so on.

The module creates a Docker network for the etcd cluster, and the nodes are connected to this network, so that they can communicate with each other through the network.

#### WithClusterToken

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.34.0"><span class="tc-version">:material-tag: v0.34.0</span></a>

Sets the cluster token for the etcd cluster. The cluster token is used to identify the etcd cluster. The default value is `mys3cr3ttok3n`.
The etcd container holds a reference to the cluster token, so you can use it with e.g. `ctr.ClusterToken`.

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The etcd container exposes the following methods:

#### ClientEndpoint

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.34.0"><span class="tc-version">:material-tag: v0.34.0</span></a>

Returns the client endpoint for the etcd container and an error, if any. In the case of a cluster, it returns the client endpoint for the first node.

#### PeerEndpoint

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.34.0"><span class="tc-version">:material-tag: v0.34.0</span></a>

Returns the peer endpoint for the etcd container and an error, if any. In the case of a cluster, it returns the peer endpoint for the first node.

---

### Modules Fakegcsserver (`docs/modules/fakegcsserver.md`)

# FakeGCSServer

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

## Introduction

The Testcontainers module for [FakeGCSServer](https://github.com/fsouza/fake-gcs-server) provides a Google Cloud Storage API emulator for local development and testing.
It runs [fsouza/fake-gcs-server](https://github.com/fsouza/fake-gcs-server) and exposes the GCS JSON API on port 4443 with an in-memory storage backend.

## Adding this module to your project dependencies

Please run the following command to add the FakeGCSServer module to your Go dependencies:

```bash
go get github.com/testcontainers/testcontainers-go/modules/fakegcsserver
```

## Usage example


[Creating a FakeGCSServer container](../../modules/fakegcsserver/examples_test.go) inside_block:runFakeGCSServerContainer


When connecting with the Google Cloud Storage client library, set the `STORAGE_EMULATOR_HOST` environment variable in your tests:

```go
storageURL, err := ctr.StorageURL(ctx)
// storageURL is e.g. "http://localhost:4443/storage/v1"

t.Setenv("STORAGE_EMULATOR_HOST", storageURL)
```

## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

The FakeGCSServer module exposes one entrypoint function to create the FakeGCSServer container, and this function receives three parameters:

```golang
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(), "fsouza/fake-gcs-server:1.47")`.

### Container Options

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

#### WithScheme

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

Sets the HTTP scheme used by the fake-gcs-server. Valid values are `"http"` (default) and `"https"`.

```golang
fakegcsserver.Run(ctx, "fsouza/fake-gcs-server:1.47",
    fakegcsserver.WithScheme("https"),
)
```

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The FakeGCSServer container exposes the following methods:

#### StorageURL

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

Returns the GCS-compatible storage URL for the container. The URL format is `<scheme>://<host>:<port>/storage/v1`, where `scheme` matches the value passed to `WithScheme` (default `"http"`).

```golang
storageURL, err := ctr.StorageURL(ctx)
```

---

### Modules Firebird (`docs/modules/firebird.md`)

# Firebird

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

## Introduction

The Testcontainers module for Firebird, a relational database that runs on Linux, Windows, and Unix platforms.
It exposes a `firebird://` connection string on port `3050`.

## Adding this module to your project dependencies

Please run the following command to add the Firebird module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/firebird
```

## Usage example


[Creating a Firebird container](../../modules/firebird/examples_test.go) inside_block:runFirebirdContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

The Firebird module exposes one entrypoint function to create the Firebird container, and this function receives three parameters:

```golang
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(), "ghcr.io/jacobalberty/firebird:v3.0")`.

### Container Options

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

!!!tip
    You can find all the available configuration and environment variables for the Firebird Docker image on [GitHub](https://github.com/jacobalberty/firebird-docker).

#### WithDatabase

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

Sets the `FIREBIRD_DATABASE` environment variable. The default database name is `test.fdb`.

```golang
firebird.WithDatabase("mydb.fdb")
```

#### WithUsername

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

Sets the `FIREBIRD_USER` environment variable. The default username is `test`.

```golang
firebird.WithUsername("myuser")
```

#### WithPassword

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

Sets the `FIREBIRD_PASSWORD` environment variable. The default password is `test`.

```golang
firebird.WithPassword("mypassword")
```

#### WithSYSDBAPassword

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

Sets the `ISC_PASSWORD` environment variable, which is the SYSDBA master password. The default is `masterkey`.

```golang
firebird.WithSYSDBAPassword("mysysdbapassword")
```

{% include "../features/common_functional_options_list.md" %}

### Container Methods

#### ConnectionString

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

This method returns the connection string to connect to the Firebird container, using the `firebird://` scheme on the default port `3050`.


[Get connection string](../../modules/firebird/firebird_test.go) inside_block:connectionString

---

### Modules Forgejo (`docs/modules/forgejo.md`)

# Forgejo

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.41.0"><span class="tc-version">:material-tag: v0.41.0</span></a>

## Introduction

The Testcontainers module for [Forgejo](https://forgejo.org/), a self-hosted Git forge. Forgejo is a community-driven fork of Gitea, providing a lightweight code hosting solution.

## Adding this module to your project dependencies

Please run the following command to add the Forgejo module to your Go dependencies:

```sh
go get github.com/testcontainers/testcontainers-go/modules/forgejo
```

## Usage example


[Creating a Forgejo container](../../modules/forgejo/examples_test.go) inside_block:runForgejoContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.41.0"><span class="tc-version">:material-tag: v0.41.0</span></a>

The Forgejo module exposes one entrypoint function to create the Forgejo container, and this function receives three parameters:

```golang
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(), "codeberg.org/forgejo/forgejo:11")`.

### Container Options

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

#### Admin Credentials

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.41.0"><span class="tc-version">:material-tag: v0.41.0</span></a>

Use `WithAdminCredentials(username, password, email)` to set the admin user credentials. An admin user is automatically created when the container starts. Default credentials are `forgejo-admin` / `forgejo-admin`.

#### Configuration via Environment

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.41.0"><span class="tc-version">:material-tag: v0.41.0</span></a>

Use `WithConfig(section, key, value)` to set Forgejo configuration values using the `FORGEJO__section__key` environment variable format. See the [Forgejo Configuration Cheat Sheet](https://forgejo.org/docs/latest/admin/config-cheat-sheet/) for available options.

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The Forgejo container exposes the following methods:

#### ConnectionString

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.41.0"><span class="tc-version">:material-tag: v0.41.0</span></a>

The `ConnectionString` method returns the HTTP URL for the Forgejo instance (e.g. `http://localhost:12345`).

#### SSHConnectionString

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.41.0"><span class="tc-version">:material-tag: v0.41.0</span></a>

The `SSHConnectionString` method returns the SSH endpoint for Git operations.

---

### Modules Garage (`docs/modules/garage.md`)

# Garage

Not available until the next release <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>

## Introduction

The Testcontainers module for [Garage](https://garagehq.deuxfleurs.fr/), an S3-compatible object store.
The module starts a single-node server and creates an access key and bucket before accepting S3 requests.
Use an S3 client with path-style addressing, as shown in the example below.

## Adding this module to your project dependencies

Please run the following command to add the Garage module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/garage
```

## Usage example


[Creating a Garage container](../../modules/garage/examples_test.go) inside_block:ExampleRun


## Module Reference

### Run function

- Not available until the next release <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>

The Garage module exposes one entrypoint function to create the Garage container, and this function receives three parameters:

```golang
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.
For example: `Run(context.Background(), "dxflrs/garage:v2.4.1")`.

Garage v2.3.0 or later is required for the `--single-node` and `--default-bucket` bootstrap flags.

### Container Options

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

#### WithCredentials

`garage.WithCredentials(accessKey, secretKey)` sets the initial S3 credentials.
The defaults are `testcontainers` and `testcontainers-secret`, respectively.
The access key must contain at least 8 bytes and the secret key at least 16 bytes.
These credentials are intended for tests. The initial key can create additional buckets using the S3 API.

#### WithBucket

`garage.WithBucket("my-bucket")` changes the initial bucket name from `testcontainers`.
The bucket must have a valid S3 bucket name.

#### WithRegion

`garage.WithRegion("eu-west-1")` changes the S3 region from `garage`.
Configure your S3 client to use the same region.

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The Garage container exposes the following methods:

#### ConnectionString

`ConnectionString(ctx)` returns the S3 HTTP endpoint, including the mapped port.

#### AccessKey and SecretKey

`AccessKey()` and `SecretKey()` return the initial S3 credentials.

#### Bucket

`Bucket()` returns the name of the bucket created at startup.

#### Region

`Region()` returns the configured S3 region.

### Stopping the container

Garage can take the full stop timeout to exit after serving S3 requests. If graceful shutdown is unnecessary
for your tests, use `testcontainers.TerminateContainer(ctr, testcontainers.StopTimeout(0))`
or `testcontainers.CleanupContainer(t, ctr, testcontainers.StopTimeout(0))`.

---

### Modules Gcloud Shared (`docs/modules/gcloud-shared.md`)

#### WithProjectID

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

The `WithProjectID` function sets the project ID for the Google Cloud container.

---

### Modules Gcloud (`docs/modules/gcloud.md`)

# GCloud

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.25.0"><span class="tc-version">:material-tag: v0.25.0</span></a>

## Introduction

The Testcontainers module for GCloud.

## Adding this module to your project dependencies

Please run the following command to add the GCloud module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/gcloud
```

## Usage example

The Google Cloud module exposes the following Go packages:

- [BigQuery](#bigquery): `github.com/testcontainers/testcontainers-go/modules/gcloud/bigquery`.
- [BigTable](#bigtable): `github.com/testcontainers/testcontainers-go/modules/gcloud/bigtable`.
- [Datastore](#datastore): `github.com/testcontainers/testcontainers-go/modules/gcloud/datastore`.
- [Firestore](#firestore): `github.com/testcontainers/testcontainers-go/modules/gcloud/firestore`.
- [Pubsub](#pubsub): `github.com/testcontainers/testcontainers-go/modules/gcloud/pubsub`.
- [Spanner](#spanner): `github.com/testcontainers/testcontainers-go/modules/gcloud/spanner`.
!!!info
    By default, the all the emulators use `gcr.io/google.com/cloudsdktool/cloud-sdk:emulators` as the default Docker image, except for the BigQuery emulator, which uses `ghcr.io/goccy/bigquery-emulator:0.6.1`, and Spanner, which uses `gcr.io/cloud-spanner-emulator/emulator:1.5.40`.

## BigQuery

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

The BigQuery module exposes one entrypoint function to create the BigQuery container, and this function receives three parameters:

```golang
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(), "ghcr.io/goccy/bigquery-emulator:0.6.1")`.

### Container Options

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

{% include "./gcloud-shared.md" %}

#### Data YAML (Seed File)

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

If you would like to do additional initialization in the BigQuery container, add a `data.yaml` file represented by an `io.Reader` to the container request with the `WithDataYAML` function.
That file is copied after the container is created but before it's started. The startup command then used will look like `--project test --data-from-yaml /testcontainers-data.yaml`.

An example of a `data.yaml` file that seeds the BigQuery instance with datasets and tables is shown below:


[Data Yaml content](../../modules/gcloud/bigquery/testdata/data.yaml)


{% include "../features/common_functional_options_list.md" %}

### Examples


[Creating a BigQuery container](../../modules/gcloud/bigquery/examples_test.go) inside_block:runBigQueryContainer
[Obtaining a BigQuery client](../../modules/gcloud/bigquery/examples_test.go) inside_block:bigQueryClient


It's important to set the `option.WithEndpoint()` option using the container's URI, as shown in the client example above.

## BigTable

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

The BigTable module exposes one entrypoint function to create the BigTable container, and this function receives three parameters:

```golang
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(), "gcr.io/google.com/cloudsdktool/cloud-sdk:emulators")`.

### Container Options

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

{% include "./gcloud-shared.md" %}

{% include "../features/common_functional_options_list.md" %}

### Examples


[Creating a BigTable container](../../modules/gcloud/bigtable/examples_test.go) inside_block:runBigTableContainer
[Obtaining a BigTable Admin client](../../modules/gcloud/bigtable/examples_test.go) inside_block:bigTableAdminClient
[Obtaining a BigTable client](../../modules/gcloud/bigtable/examples_test.go) inside_block:bigTableClient


It's important to set the `option.WithEndpoint()` option using the container's URI, as shown in the Admin client example above.

## Datastore

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

The Datastore module exposes one entrypoint function to create the Datastore container, and this function receives three parameters:

```golang
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(), "gcr.io/google.com/cloudsdktool/cloud-sdk:emulators")`.

### Container Options

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

{% include "./gcloud-shared.md" %}

{% include "../features/common_functional_options_list.md" %}

### Examples


[Creating a Datastore container](../../modules/gcloud/datastore/examples_test.go) inside_block:runDatastoreContainer
[Obtaining a Datastore client](../../modules/gcloud/datastore/examples_test.go) inside_block:datastoreClient


It's important to set the `option.WithEndpoint()` option using the container's URI, as shown in the client example above.

## Firestore

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

The Firestore module exposes one entrypoint function to create the Firestore container, and this function receives three parameters:

```golang
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(), "gcr.io/google.com/cloudsdktool/cloud-sdk:emulators")`.

### Container Options

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

{% include "./gcloud-shared.md" %}

### Datastore mode

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

Using the `WithDatastoreMode` option will run the Firestore emulator using `Firestore In Datastore` mode allowing you to use Datastore APIs and clients towards the Firestore emulator.

Requires `cloud-sdk:465.0.0` or higher

{% include "../features/common_functional_options_list.md" %}

### Examples


[Creating a Firestore container](../../modules/gcloud/firestore/examples_test.go) inside_block:runFirestoreContainer
[Obtaining a Firestore client](../../modules/gcloud/firestore/examples_test.go) inside_block:firestoreClient


It's important to set the target string of the `grpc.NewClient` method using the container's URI, as shown in the client example above.

## Pubsub

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

The Pubsub module exposes one entrypoint function to create the Pubsub container, and this function receives three parameters:

```golang
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(), "gcr.io/google.com/cloudsdktool/cloud-sdk:emulators")`.

### Container Options

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

{% include "./gcloud-shared.md" %}

{% include "../features/common_functional_options_list.md" %}

### Examples


[Creating a Pubsub container](../../modules/gcloud/pubsub/examples_test.go) inside_block:runPubsubContainer
[Obtaining a Pubsub client](../../modules/gcloud/pubsub/examples_test.go) inside_block:pubsubClient


It's important to set the target string of the `grpc.NewClient` method using the container's URI, as shown in the client example above.

## Spanner

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

The Spanner module exposes one entrypoint function to create the Spanner container, and this function receives three parameters:

```golang
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(), "gcr.io/cloud-spanner-emulator/emulator:1.5.40")`.

### Container Options

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

{% include "./gcloud-shared.md" %}

{% include "../features/common_functional_options_list.md" %}

### Examples


[Creating a Spanner container](../../modules/gcloud/spanner/examples_test.go) inside_block:runSpannerContainer
[Obtaining a Spanner Admin client](../../modules/gcloud/spanner/examples_test.go) inside_block:spannerAdminClient
[Obtaining a Spanner Database Admin client](../../modules/gcloud/spanner/examples_test.go) inside_block:spannerDBAdminClient


It's important to set the `option.WithEndpoint()` option using the container's URI, as shown in the Admin client example above.

---

### Modules Grafana Lgtm (`docs/modules/grafana-lgtm.md`)

# Grafana LGTM

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.33.0"><span class="tc-version">:material-tag: v0.33.0</span></a>

## Introduction

The Testcontainers module for Grafana LGTM.

## Adding this module to your project dependencies

Please run the following command to add the Grafana module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/grafana-lgtm
```

## Usage example


[Creating a Grafana LGTM container](../../modules/grafana-lgtm/examples_test.go) inside_block:runGrafanaLGTMContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.33.0"><span class="tc-version">:material-tag: v0.33.0</span></a>

!!!info
    The `RunContainer(ctx, opts...)` function is deprecated and will be removed in the next major release of _Testcontainers for Go_.

The Grafana LGTM module exposes one entrypoint function to create the Grafana LGTM container, and this function receives three parameters:

```golang
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*GrafanaLGTMContainer, 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(), "grafana/otel-lgtm:0.6.0")`.

### Container Options

When starting the Grafana LGTM container, you can pass options in a variadic way to configure it.

#### Admin Credentials

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.33.0"><span class="tc-version">:material-tag: v0.33.0</span></a>

If you need to set different admin credentials in the Grafana LGTM container, you can set them using the `WithAdminCredentials(user, password)` option.

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The Grafana LGTM container exposes the following methods:

!!!info
    All the endpoint methods return their endpoints in the format `<host>:<port>`, so please use them accordingly to configure your client.

#### Grafana Endpoint

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.33.0"><span class="tc-version">:material-tag: v0.33.0</span></a>

The `HttpEndpoint(ctx)` method returns the HTTP endpoint to connect to Grafana, using the default `3000` port. The same method with the `Must` prefix returns just the endpoint, and panics if an error occurs.

#### Loki Endpoint

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.33.0"><span class="tc-version">:material-tag: v0.33.0</span></a>

The `LokiEndpoint(ctx)` method returns the HTTP endpoint to connect to Loki, using the default `3100` port. The same method with the `Must` prefix returns just the endpoint, and panics if an error occurs.

#### Tempo Endpoint

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.33.0"><span class="tc-version">:material-tag: v0.33.0</span></a>

The `TempoEndpoint(ctx)` method returns the HTTP endpoint to connect to Tempo, using the default `3200` port. The same method with the `Must` prefix returns just the endpoint, and panics if an error occurs.

#### Otel HTTP Endpoint

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.33.0"><span class="tc-version">:material-tag: v0.33.0</span></a>

The `OtelHTTPEndpoint(ctx)` method returns the endpoint to connect to Otel using HTTP, using the default `4318` port. The same method with the `Must` prefix returns just the endpoint, and panics if an error occurs.

#### Otel gRPC Endpoint

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.33.0"><span class="tc-version">:material-tag: v0.33.0</span></a>

The `OtelGRPCEndpoint(ctx)` method returns the endpoint to connect to Otel using gRPC, using the default `4317` port. The same method with the `Must` prefix returns just the endpoint, and panics if an error occurs.

#### Prometheus Endpoint

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.33.0"><span class="tc-version">:material-tag: v0.33.0</span></a>

The `PrometheusHttpEndpoint(ctx)` method returns the endpoint to connect to Prometheus, using the default `9090` port. The same method with the `Must` prefix returns just the endpoint, and panics if an error occurs.

## Examples

### Traces, Logs and Prometheus metrics for a simple Go process

In this example, a simple application is created to generate traces, logs, and Prometheus metrics.
The application sends data to Grafana LGTM, and the Otel SDK is used to send the data.
The example demonstrates how to set up the Otel SDK and run the Grafana LGTM module,
configuring the Otel library to send data to Grafana LGTM thanks to the endpoints provided by the Grafana LGTM container.


[App sending Otel data](../../modules/grafana-lgtm/examples_test.go) inside_block:rollDiceApp
[Setup Otel SDK](../../modules/grafana-lgtm/examples_test.go) inside_block:setupOTelSDK
[Run the Grafana LGTM container](../../modules/grafana-lgtm/examples_test.go) inside_block:ExampleRun_otelCollector

---

### Modules Inbucket (`docs/modules/inbucket.md`)

# Inbucket

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.28.0"><span class="tc-version">:material-tag: v0.28.0</span></a>

## Introduction

The Testcontainers module for Inbucket.

## Adding this module to your project dependencies

Please run the following command to add the Inbucket module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/inbucket
```

## Usage example


[Creating an Inbucket container](../../modules/inbucket/examples_test.go) inside_block:runInbucketContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.32.0"><span class="tc-version">:material-tag: v0.32.0</span></a>

!!!info
    The `RunContainer(ctx, opts...)` function is deprecated and will be removed in the next major release of _Testcontainers for Go_.

The Inbucket module exposes one entrypoint function to create the Inbucket container, and this function receives three parameters:

```golang
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*InbucketContainer, 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(), "inbucket/inbucket:sha-2d409bb")`.

### Container Options

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

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The Inbucket container exposes the following methods:

#### SmtpConnection

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.28.0"><span class="tc-version">:material-tag: v0.28.0</span></a>

This method returns the connection string to connect to the Inbucket container SMTP service, using the `2500` port.


[Get smtp connection string](../../modules/inbucket/inbucket_test.go) inside_block:smtpConnection


#### WebInterface

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.28.0"><span class="tc-version">:material-tag: v0.28.0</span></a>

This method returns the connection string to connect to the Inbucket container web interface, using the `9000` port.


[Get web interface connection string](../../modules/inbucket/inbucket_test.go) inside_block:webInterface

---

### Modules Influxdb (`docs/modules/influxdb.md`)

# InfluxDB

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.30.0"><span class="tc-version">:material-tag: v0.30.0</span></a>

## Introduction

A testcontainers module for InfluxDB V1 and V2.

## Adding this module to your project dependencies

Please run the following command to add the InfluxDB module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/influxdb
```

## Usage example

### InfluxDB

 
[Creating an InfluxDB V1 container](../../modules/influxdb/examples_test.go) inside_block:runInfluxContainer
[Creating an InfluxDB V2 container](../../modules/influxdb/examples_test.go) inside_block:runInfluxV2Container


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.32.0"><span class="tc-version">:material-tag: v0.32.0</span></a>

!!!info
    The `RunContainer(ctx, opts...)` function is deprecated and will be removed in the next major release of _Testcontainers for Go_.

The InfluxDB module exposes one entrypoint function to create the container, and this function receives three parameters:

```golang
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*InfluxDbContainer, 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(), "influxdb:1.8.0")`.

!!!info
    Note that `influxdb:latest` will pull a version 2 image.

### Container Options

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

!!!tip

    You can find configuration information for the InfluxDB image on [Docker Hub](https://hub.docker.com/_/influxdb) and a list of possible 
    environment variables on [InfluxDB documentation](https://docs.influxdata.com/influxdb/v1/administration/config/).

#### Set username, password and database name

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.30.0"><span class="tc-version">:material-tag: v0.30.0</span></a>

By default, authentication is disabled and no credentials are needed to use the Influx API against the test container.
If you want to test with credentials, include the appropriate environment variables to do so.

#### Configuring InfluxDB V2

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

When running the InfluxDB V2 image, you can override the default configuration by using options prefixed by `influxdb.WithV2`.
The following options are available:

- `WithV2(org, bucket string)`: Configures organization and bucket name. This option is required to run the InfluxDB V2 image.
- `WithV2Auth(org, bucket, username, password string)`: Sets the username and password for the initial user.
- `WithV2SecretsAuth(org, bucket, usernameFile, passwordFile string)`: Sets the username and password file path.
- `WithV2Retention(retention time.Duration)`: Sets the default bucket retention policy.
- `WithV2AdminToken(token string)`:  Sets the admin token for the initial user.
- `WithV2SecretsAdminToken(tokenFile string)`: Sets the admin token file path.

#### WithInitDb

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.30.0"><span class="tc-version">:material-tag: v0.30.0</span></a>

While the InfluxDB image will obey the `/docker-entrypoint-initdb.d` directory as is common, that directory does not
exist in the default image. Instead, you can use the `WithInitDb` option to pass a directory which will be copied to
when the container starts. Any `*.sh` or `*.iql` files in the directory will be processed by the image upon startup.
When executing these scripts, the `init-influxdb.sh` script in the image will start the InfluxDB server, run the
scripts, stop the server, and restart the server.  This makes it tricky to detect the readiness of the container.
This module looks for that and adds some extra tests for readiness, but these could be fragile.

!!!important
    The `WithInitDb` option receives a path to the parent directory of one named `docker-entrypoint-initdb.d`. This is
    because the `docker-entrypoint-initdb.d` directory is not present in the image.

#### WithConfigFile

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.30.0"><span class="tc-version">:material-tag: v0.30.0</span></a>

If you need to set a custom configuration, you can use `WithConfigFile` option to pass the path to a custom configuration file.

{% include "../features/common_functional_options_list.md" %}

### Container Methods

#### ConnectionUrl

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.30.0"><span class="tc-version">:material-tag: v0.30.0</span></a>

This function is a simple helper to return a URL to the container, using the default `8086` port.


[ConnectionUrl](../../modules/influxdb/influxdb_test.go) inside_block:influxConnectionUrl


Please check the existence of two methods: `ConnectionUrl` and `MustConnectionUrl`. The latter is used to avoid the need to handle errors,
while the former is used to return the URL and the error. `MustConnectionUrl` will panic if an error occurs.

!!!info
    The `ConnectionUrl` and `MustConnectionUrl` methods only support HTTP connections at the moment.

---

### Modules K3s (`docs/modules/k3s.md`)

# K3s

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.21.0"><span class="tc-version">:material-tag: v0.21.0</span></a>

## Introduction

The Testcontainers module for K3s.

## Adding this module to your project dependencies

Please run the following command to add the K3s module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/k3s
```

## Usage example


[Test for a K3s container](../../modules/k3s/k3s_test.go) inside_block:runK3sContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.32.0"><span class="tc-version">:material-tag: v0.32.0</span></a>

!!!info
    The `RunContainer(ctx, opts...)` function is deprecated and will be removed in the next major release of _Testcontainers for Go_.

The K3s module exposes one entrypoint function to create the K3s container, and this function receives three parameters:

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

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

### Container Ports

These are the ports used by the K3s container:

[Container Ports](../../modules/k3s/k3s.go) inside_block:containerPorts


#### Image

Use the second argument in the `Run` function to set a valid Docker image.
In example: `Run(context.Background(), "rancher/k3s:v1.27.1-k3s1")`.

### Container Options

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

## WithManifest

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.29.0"><span class="tc-version">:material-tag: v0.29.0</span></a>

The `WithManifest` option loads a manifest obtained from a local file into the cluster. K3s applies it automatically during the startup process

```golang
func WithManifest(manifestPath string) testcontainers.CustomizeRequestOption
```

Example:

```golang
        WithManifest("nginx-manifest.yaml")
```

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The K3s container exposes the following methods:

#### GetKubeConfig

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.21.0"><span class="tc-version">:material-tag: v0.21.0</span></a>

The `GetKubeConfig` method returns the K3s cluster's `kubeconfig`, including the server URL, to be used for connecting
to the Kubernetes Rest Client API using a Kubernetes client. It'll be returned in the format of `[]bytes`.


[Get KubeConfig](../../modules/k3s/k3s_example_test.go) inside_block:GetKubeConfig


#### LoadImages

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.25.0"><span class="tc-version">:material-tag: v0.25.0</span></a>

The `LoadImages` method imports images from the local Docker daemon into the k3s cluster and makes them available to pods.

```golang
func (c *K3sContainer) LoadImages(ctx context.Context, images ...string) error
```

This is useful for testing images built locally without pushing them to a registry or configuring k3s to [use a private registry](https://docs.k3s.io/installation/private-registry).

Images must already be present on the Docker host running the test. [DockerProvider.PullImage](https://pkg.go.dev/github.com/testcontainers/testcontainers-go#DockerProvider.PullImage) is enough for single-architecture image references. When you need a specific OCI platform, use [DockerProvider.PullImageWithOpts](https://pkg.go.dev/github.com/testcontainers/testcontainers-go#DockerProvider.PullImageWithOpts) with [PullDockerImageWithPlatform](https://pkg.go.dev/github.com/testcontainers/testcontainers-go#PullDockerImageWithPlatform).

`LoadImages` delegates to `LoadImagesWithOpts` without save options. It works best with single-architecture image references (for example `amd64/nginx`). For multi-architecture images, use `LoadImagesWithPlatform` or `LoadImagesWithOpts`.

When creating pods that use loaded images, set `imagePullPolicy: Never` so Kubernetes uses the imported image instead of pulling from a registry.

Example:

```golang
provider, err := testcontainers.ProviderDocker.GetProvider()
if err != nil {
    // handle error
}

if err := provider.PullImage(ctx, "amd64/nginx"); err != nil {
    // handle error
}

if err := k3sContainer.LoadImages(ctx, "amd64/nginx"); err != nil {
    // handle error
}
```

#### LoadImagesWithPlatform

The `LoadImagesWithPlatform` method is a convenience wrapper around `LoadImagesWithOpts` that exports and imports an image for a specific OCI platform.

```golang
func (c *K3sContainer) LoadImagesWithPlatform(ctx context.Context, images []string, platform *v1.Platform) error
```

When `platform` is `nil`, behaviour matches `LoadImages`. When `platform` is set, the image is exported and imported for that OCI platform.

Use this method on multi-architecture hosts or when loading multi-architecture image tags. Pull the same platform into Docker first, then load it into k3s:

```golang
hostPlatform := platforms.DefaultSpec()
hostPlatform.OS = "linux"

provider, err := testcontainers.ProviderDocker.GetProvider()
if err != nil {
    // handle error
}

if err := provider.PullImageWithOpts(
    ctx,
    "amd64/nginx",
    testcontainers.PullDockerImageWithPlatform(hostPlatform),
); err != nil {
    // handle error
}

if err := k3sContainer.LoadImagesWithPlatform(ctx, []string{"amd64/nginx"}, &hostPlatform); err != nil {
    // handle error
}
```

#### LoadImagesWithOpts

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.25.0"><span class="tc-version">:material-tag: v0.25.0</span></a>

The `LoadImagesWithOpts` method imports local images into the k3s cluster, passing [SaveImageOption](https://pkg.go.dev/github.com/testcontainers/testcontainers-go#SaveImageOption) values through to `docker save`.

```golang
func (c *K3sContainer) LoadImagesWithOpts(ctx context.Context, images []string, opts ...testcontainers.SaveImageOption) error
```

When [SaveDockerImageWithPlatforms](https://pkg.go.dev/github.com/testcontainers/testcontainers-go#SaveDockerImageWithPlatforms) is passed, containerd import uses the same platform. Without platform options, import does not use `--all-platforms`.

For multiple images on different architectures, call `LoadImagesWithOpts` once per image and platform.

Example with platform:

```golang
hostPlatform := platforms.DefaultSpec()
hostPlatform.OS = "linux"

provider, err := testcontainers.ProviderDocker.GetProvider()
if err != nil {
    // handle error
}

if err := provider.PullImageWithOpts(
    ctx,
    "amd64/nginx",
    testcontainers.PullDockerImageWithPlatform(hostPlatform),
); err != nil {
    // handle error
}

if err := k3sContainer.LoadImagesWithOpts(
    ctx,
    []string{"amd64/nginx"},
    testcontainers.SaveDockerImageWithPlatforms(hostPlatform),
); err != nil {
    // handle error
}
```

---

### Modules K6 (`docs/modules/k6.md`)

# K6

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.26.0"><span class="tc-version">:material-tag: v0.26.0</span></a>

## Introduction

The Testcontainers module for K6.

### Using k6 extensions

This module takes advantage of [k6x](https://github.com/szkiba/k6x) to dynamically build a `k6` binary with all the [k6 extensions](https://k6.io/docs/extensions/get-started/explore/) required by the test script.

## Adding this module to your project dependencies

Please run the following command to add the K6 module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/k6
```

## Usage example


[Creating a httpbin application](../../modules/k6/examples_test.go) inside_block:runHTTPBin
[Obtain IP for the httpbin application](../../modules/k6/examples_test.go) inside_block:getHTTPBinIP
[k6 script for testing httpbin](../../modules/k6/scripts/httpbin.js)
[Creating a K6 container](../../modules/k6/examples_test.go) inside_block:runK6Container


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.32.0"><span class="tc-version">:material-tag: v0.32.0</span></a>

!!!info
    The `RunContainer(ctx, opts...)` function is deprecated and will be removed in the next major release of _Testcontainers for Go_.

The K6 module exposes one entrypoint function to run the K6 container, and this function receives three parameters:

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

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

#### Image

!!! warning
    The K6 module uses a `k6x` image to build a `k6` binary with all the required extensions. Therefore, only the [szkiba/k6x](https://hub.docker.com/r/szkiba/k6x) image should be used with this module.

Use the second argument in the `Run` function to set a valid Docker image.
In example: `Run(context.Background(), "szkiba/k6x:v0.3.1")`.

### Container Options

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

#### SetEnvVar

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.26.0"><span class="tc-version">:material-tag: v0.26.0</span></a>

`SetEnvVar` sets an [environment variable](https://k6.io/docs/using-k6/environment-variables/) for the test script using the '--env' command-line flag in the k6 command in the container.

```golang
k6.New(ctx, k6.SetEnvVar("URL","test.k6.io"), k6.WithTestScript("/tests/test.js"))
```

#### WithCache

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.26.0"><span class="tc-version">:material-tag: v0.26.0</span></a>

Use `WithCache` sets a volume to be used as [cache for building the k6 binary](https://github.com/szkiba/k6x#cache) inside the `k6` container.
This option improves considerably the execution time of test suites that creates multiple `k6` test containers.

By default, a new volume is created and automatically removed when the test session ends.

This is convenient for example for CI/CD environments. In other cases, such as local testing, it can be convenient to reuse the same cache volume across test sessions. In this case, the TC_K6_BUILD_CACHE environment variables can be used to provide the name of a volume to be used and kept across test sessions. If this volume does not exist, it will be created.

```golang
k6.New(ctx, WithCache(), k6.WithTestScript("/tests/test.js"))
```

#### WithCmdOptions

- DEPRECATED: use [testcontainers.WithCmdArgs](/features/creating_container/#withcmdargs) instead
- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.26.0"><span class="tc-version">:material-tag: v0.26.0</span></a>

Use `WithCmdOptions` to pass a variadic list of strings as [options](https://k6.io/docs/using-k6/k6-options/reference/) to the k6 run command

```golang
k6.New(ctx, testcontainers.WithCmdArgs("--vus=10", "--duration=30s"), k6.WithTestScript("/tests/test.js"))
```

#### WithTestScript

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.26.0"><span class="tc-version">:material-tag: v0.26.0</span></a>

Use the `WithTestScript` option to specify the test script to run. The path to the script must be an absolute path. This option copies the script file to the container and pass it to k6's `run` command. At least one `WithTestScript` or `WithRemoteTestScript`  option must be specified.

```golang
k6.New(ctx, k6.WithTestScript("/tests/test.js"))
```

#### WithRemoteTestScript

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.30.0"><span class="tc-version">:material-tag: v0.30.0</span></a>

Use the `WithRemoteTestScript` option to specify the remote test script to run. The path to the remote script must be a http or https url. Basic authentication is supported. This option performs a HTTP `GET` to copy the remote file locally then copies the script file to the container and pass it to k6's `run` command. The default timeout for the `GET` is 60 seconds. Only javascript, or more specifically `Content-Type:text/javascript` is supported.  At least one `WithTestScript` or `WithRemoteTestScript`  option must be specified.

```golang
scriptUrl:="https://raw.githubusercontent.com/testcontainers/testcontainers-go/main/modules/k6/scripts/pass.js"

uri, _ := url.Parse(scriptUrl)
desc := k6.DownloadableFile{Uri: *uri , DownloadDir: t.TempDir()}
options := k6.WithRemoteTestScript(desc)

k6.New(ctx, k6.WithCache(), options)
```

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The K6 container does not expose any method.

---

### Modules Kafka (`docs/modules/kafka.md`)

# Kafka (KRaft)

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.24.0"><span class="tc-version">:material-tag: v0.24.0</span></a>

## Introduction

The Testcontainers module for KRaft: [Apache Kafka Without ZooKeeper](https://developer.confluent.io/learn/kraft).

## Adding this module to your project dependencies

Please run the following command to add the Kafka module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/kafka
```

## Usage example


[Creating a Kafka container](../../modules/kafka/examples_test.go) inside_block:runKafkaContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.32.0"><span class="tc-version">:material-tag: v0.32.0</span></a>

!!!info
    The `RunContainer(ctx, opts...)` function is deprecated and will be removed in the next major release of _Testcontainers for Go_.

The Kafka module exposes one entrypoint function to create the Kafka container, and this function receives three parameters:

```golang
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*KafkaContainer, 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(), "confluentinc/confluent-local:7.5.0")`.

!!! warning
    The minimal required version of Kafka for KRaft mode is `confluentinc/confluent-local:7.4.0`. If you are using an image that
    is different from the official one, please make sure that it's compatible with KRaft mode, as the module won't check
    the version for you.

#### Environment variables

The environment variables that are already set by default are:


[Environment variables](../../modules/kafka/kafka.go) inside_block:envVars


#### Init script

The Kafka container will be started using a custom shell script:


[Init script](../../modules/kafka/kafka.go) inside_block:starterScript


### Container Options

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

#### WithTLS

- Not available until the next release <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>

If you need to test clients against a TLS-secured broker, you can use the `kafka.WithTLS()` option.

When enabled, the container will:

- Generate a self-signed CA and a server certificate signed by it, valid for the host the container is reachable at
- Configure Kafka with a PKCS12 keystore holding the server certificate
- Expose an additional SSL listener on port `9095`, keeping the PLAINTEXT one on port `9093`

If you override `KAFKA_LISTENERS` or `KAFKA_LISTENER_SECURITY_PROTOCOL_MAP`, the SSL listener is still added. If you define it yourself, it must listen on port `9095` and use the `SSL` protocol, otherwise `Run` returns an error.

Use the `BrokersTLS(ctx)` method to get the SSL endpoint and the `TLSConfig()` method to get the `*tls.Config` for client connections.

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The Kafka container exposes the following methods:

#### Brokers

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.24.0"><span class="tc-version">:material-tag: v0.24.0</span></a>

The `Brokers(ctx)` method returns the Kafka brokers as a string slice, containing the host and the random port defined by Kafka's public port (`9093/tcp`).


[Get Kafka brokers](../../modules/kafka/kafka_test.go) inside_block:getBrokers


#### BrokersTLS

- Not available until the next release <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>

The `BrokersTLS(ctx)` method returns the Kafka brokers of the SSL listener as a string slice, containing the host and the random port defined by Kafka's SSL port (`9095/tcp`). It can only be used when the container was created with the `WithTLS()` option. Returns an error if TLS was not enabled.

#### TLSConfig

- Not available until the next release <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>

The `TLSConfig()` method returns the TLS configuration trusting the CA that signed the broker certificate. It can only be used when the container was created with the `WithTLS()` option. Returns an error if TLS was not enabled.


[Get Kafka TLS brokers and config](../../modules/kafka/kafka_test.go) inside_block:getBrokersTLS

---

### Modules Kurrentdb (`docs/modules/kurrentdb.md`)

# KurrentDB

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

## Introduction

The Testcontainers module for [KurrentDB](https://www.kurrent.io/kurrentdb), an event-native database for storing application state changes as immutable events. KurrentDB is the rebrand of EventStoreDB and uses the `kurrent://` connection string scheme.

## Adding this module to your project dependencies

Please run the following command to add the KurrentDB module to your Go dependencies:

```bash
go get github.com/testcontainers/testcontainers-go/modules/kurrentdb
```

## Usage example


[Creating a KurrentDB container](../../modules/kurrentdb/examples_test.go) inside_block:runKurrentDBContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

The KurrentDB module exposes one entrypoint function to create the KurrentDB container, and this function receives three parameters:

```golang
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(), "kurrentplatform/kurrentdb:latest")`.

### Container Options

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

#### WithInsecure

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

By default, KurrentDB runs in insecure mode (no TLS), which is suitable for local development and testing. The `WithInsecure` option makes this explicit:


[Run with insecure mode](../../modules/kurrentdb/examples_test.go) inside_block:withInsecure


{% include "../features/common_functional_options_list.md" %}

### Container Methods

The KurrentDB container exposes the following methods:

#### ConnectionString

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

The `ConnectionString(ctx)` method returns the connection string to connect to the KurrentDB container using the `kurrent://` scheme.
When the container runs in insecure mode, `?tls=false` is appended.


[Get connection string](../../modules/kurrentdb/examples_test.go) inside_block:connectionString

---

### Modules Localstack (`docs/modules/localstack.md`)

# LocalStack

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.18.0"><span class="tc-version">:material-tag: v0.18.0</span></a>

## Introduction

The Testcontainers module for [LocalStack](http://localstack.cloud/) is _"a fully functional local AWS cloud stack"_, to develop and test your cloud and serverless apps without actually using the cloud.

## Adding this module to your project dependencies

Please run the following command to add the LocalStack module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/localstack
```

## Usage example

Running LocalStack as a stand-in for multiple AWS services during a test:


[Creating a LocalStack container](../../modules/localstack/examples_test.go) inside_block:runLocalstackContainer


Environment variables listed in [Localstack's README](https://github.com/localstack/localstack#configurations) may be used to customize Localstack's configuration. 
Use the `testcontainers.WithEnv` option when creating the `LocalStackContainer` to apply those variables.

## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.32.0"><span class="tc-version">:material-tag: v0.32.0</span></a>

!!!info
    The `RunContainer(ctx, opts...)` function is deprecated and will be removed in the next major release of _Testcontainers for Go_.

The LocalStack module exposes one single function to create the LocalStack container, and this function receives three parameters:

```golang
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*LocalstackContainer, 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(), "localstack:1.4.0")`.

### Container Options

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

{% include "../features/common_functional_options_list.md" %}

## Accessing hostname-sensitive services

Some Localstack APIs, such as SQS, require the container to be aware of the hostname that it is accessible on - for example, for construction of queue URLs in responses.

Testcontainers will inform Localstack of the best hostname automatically, using an environment variable for that:

* for Localstack versions 0.10.0 and above, the `HOSTNAME_EXTERNAL` environment variable will be set to hostname in the container request.
* for Localstack versions 2.0.0 and above, the `LOCALSTACK_HOST` environment variable will be set to the hostname in the container request.

Once the variable is set:

* when running the Localstack container directly without a custom network defined, it is expected that all calls to the container will be from the test host. As such, the container address will be used (typically localhost or the address where the Docker daemon is running).

* when running the Localstack container [with a custom network defined](/features/networking/#advanced-networking), it is expected that all calls to the container will be **from other containers on that network**. `HOSTNAME_EXTERNAL` will be set to the *last* network alias that has been configured for the Localstack container.

    
    [Localstack container running with a custom network](../../modules/localstack/examples_test.go) inside_block:localstackWithNetwork
    

* Other usage scenarios, such as where the Localstack container is used from both the test host and containers on a custom network, are not automatically supported. If you have this use case, you should set `HOSTNAME_EXTERNAL` manually.

## Examples using the AWS SDK for Go

You can use the AWS SDK for Go to create a client for the LocalStack container. The following examples show how to create a client for the S3 service, using both the SDK v1 and v2.

### AWS SDK v1


[AWS SDK v1](../../modules/localstack/v1/s3_test.go) inside_block:awsSDKClientV1


For further reference on the SDK v1, please check out the AWS docs [here](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/setting-up.html).

### AWS SDK v2


[EndpointResolver](../../modules/localstack/v2/s3_test.go) inside_block:awsResolverV2
[AWS SDK v2](../../modules/localstack/v2/s3_test.go) inside_block:awsSDKClientV2


For further reference on the SDK v2, please check out the AWS docs [here](https://aws.github.io/aws-sdk-go-v2/docs/getting-started)

## Testing the module

The module includes unit and integration tests that can be run from its source code. To run the tests please execute the following command:

```
cd modules/localstack
make test
```

!!!info
	At this moment, the tests for the module include tests for the S3 service, only. They live in two different Go packages of the LocalStack module,
    `v1` and `v2`, where it'll be easier to add more examples for the rest of services.

---

### Modules Mailpit (`docs/modules/mailpit.md`)

# Mailpit

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

## Introduction

The Testcontainers module for Mailpit.

[Mailpit](https://mailpit.axllent.org/) is a fast, multi-platform email testing tool. It provides an SMTP server that captures outgoing emails and exposes them through a web UI and REST API, making it ideal for asserting email sending behaviour in integration tests.

## Adding this module to your project dependencies

Please run the following command to add the Mailpit module to your Go dependencies:

```bash
go get github.com/testcontainers/testcontainers-go/modules/mailpit
```

## Usage example


[Creating a Mailpit container](../../modules/mailpit/examples_test.go) inside_block:runMailpitContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

The Mailpit module exposes one entrypoint function to create the Mailpit container, and this function receives three parameters:

```golang
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(), "axllent/mailpit:v1.20")`.

### Container Options

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

#### WithSMTPAuth

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

`WithSMTPAuth` sets the SMTP authentication credentials for the Mailpit container via the `MP_SMTP_AUTH` environment variable (in `user:password` format), and enables plaintext authentication via `MP_SMTP_AUTH_ALLOW_INSECURE`.


[WithSMTPAuth](../../modules/mailpit/mailpit_test.go) inside_block:withSMTPAuth


#### WithMessageLimit

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

`WithMessageLimit` sets the maximum number of messages to store in Mailpit, using the `MP_MAX_MESSAGES` environment variable. When the limit is reached the oldest messages are automatically deleted.


[WithMessageLimit](../../modules/mailpit/mailpit_test.go) inside_block:withMessageLimit


{% include "../features/common_functional_options_list.md" %}

### Container Methods

The Mailpit container exposes the following methods:

#### SMTPEndpoint

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

`SMTPEndpoint` returns the `host:port` connection string for the Mailpit SMTP server, using the `1025` port.


[Get SMTP endpoint](../../modules/mailpit/mailpit_test.go) inside_block:smtpEndpoint


#### HTTPURL

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

`HTTPURL` returns the URL for the Mailpit web interface and REST API, using the `8025` port. The REST API is available at `/api/v1/messages` and other endpoints under `/api/v1/`.


[Get HTTP URL](../../modules/mailpit/mailpit_test.go) inside_block:httpURL

---

### Modules Mariadb (`docs/modules/mariadb.md`)

# MariaDB

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.24.0"><span class="tc-version">:material-tag: v0.24.0</span></a>

## Introduction

The Testcontainers module for MariaDB.

## Adding this module to your project dependencies

Please run the following command to add the MariaDB module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/mariadb
```

## Usage example


[Creating a MariaDB container](../../modules/mariadb/examples_test.go) inside_block:runMariaDBContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.32.0"><span class="tc-version">:material-tag: v0.32.0</span></a>

!!!info
    The `RunContainer(ctx, opts...)` function is deprecated and will be removed in the next major release of _Testcontainers for Go_.

The MariaDB module exposes one entrypoint function to create the MariaDB container, and this function receives three parameters:

```golang
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*MariaDBContainer, 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(), "mariadb:12.3.2")`.

!!!info
    From MariaDB [docs](https://github.com/docker-library/docs/tree/master/mariadb#environment-variables):

    From tag 10.2.38, 10.3.29, 10.4.19, 10.5.10 onwards, and all 10.6 and later tags,
    the `MARIADB_*` equivalent variables are provided. `MARIADB_*` variants will always be
    used in preference to `MYSQL_*` variants.

The MariaDB module will take all the environment variables that start with `MARIADB_` and duplicate them with the `MYSQL_` prefix.

### Container Options

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

!!!tip
    You can find all the available configuration and environment variables for the MariaDB Docker image on [Docker Hub](https://hub.docker.com/_/mariadb).

#### Set username, password and database name

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.24.0"><span class="tc-version">:material-tag: v0.24.0</span></a>

If you need to set a different database, and its credentials, you can use `WithUsername`, `WithPassword`, `WithDatabase`
options.

!!!info
    The default values for the username is `root`, for password is `test` and for the default database name is `test`.

#### WithScripts

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.24.0"><span class="tc-version">:material-tag: v0.24.0</span></a>
If you would like to perform DDL or DML operations in the MariaDB container, add one or more `*.sql`, `*.sql.gz`, or `*.sh`
scripts to the container request, using the `WithScripts(scriptPaths ...string)`. Those files will be copied under `/docker-entrypoint-initdb.d`.


[Example of Init script](../../modules/mariadb/testdata/schema.sql)


#### WithConfigFile

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.24.0"><span class="tc-version">:material-tag: v0.24.0</span></a>

If you need to set a custom configuration, you can use `WithConfigFile` option to pass the path to a custom configuration file.

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The MariaDB container exposes the following methods:

#### ConnectionString

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.24.0"><span class="tc-version">:material-tag: v0.24.0</span></a>

This method returns the connection string to connect to the MariaDB container, using the default `3306` port.
It's possible to pass extra parameters to the connection string, e.g. `tls=false`, in a variadic way.

!!!info
    By default, MariaDB transmits data between the server and clients without encrypting it.


[Get connection string](../../modules/mariadb/mariadb_test.go) inside_block:connectionString


#### MustConnectionString

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.30.0"><span class="tc-version">:material-tag: v0.30.0</span></a>

Same as `ConnectionString`, but panics if an error occurs while getting the connection string.

---

### Modules Meilisearch (`docs/modules/meilisearch.md`)

# Meilisearch

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.34.0"><span class="tc-version">:material-tag: v0.34.0</span></a>

## Introduction

The Testcontainers module for Meilisearch.

## Adding this module to your project dependencies

Please run the following command to add the Meilisearch module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/meilisearch
```

## Usage example


[Creating a Meilisearch container](../../modules/meilisearch/examples_test.go) inside_block:runMeilisearchContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.34.0"><span class="tc-version">:material-tag: v0.34.0</span></a>

The Meilisearch module exposes one entrypoint function to create the Meilisearch container, and this function receives three parameters:

```golang
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*MeilisearchContainer, 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(), "getmeili/meilisearch:v1.10.3")`.

### Container Options

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

#### Master Key

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.34.0"><span class="tc-version">:material-tag: v0.34.0</span></a>

If you need to set a master key, you can use the `WithMasterKey(key string)` option. Otherwise, the default will be used which is `just-a-master-key-for-test`, which is exported on the container fields.

#### Dump Data

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.34.0"><span class="tc-version">:material-tag: v0.34.0</span></a>

If you need to dump data in Meilisearch upon initialization for testing, you can use `WithDumpData(filepath string)` option where `filepath` can be an absolute path or relative path to a `dump` file. Please refer to the official Meilisearch documentation about dump files [here](https://www.meilisearch.com/docs/learn/advanced/snapshots_vs_dumps#dumps).

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The Meilisearch container exposes the following methods:

#### Address

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.34.0"><span class="tc-version">:material-tag: v0.34.0</span></a>

The `Address` method retrieves the address of the Meilisearch container.
It will use http as protocol, as TLS is not supported at the moment.

#### MasterKey

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.34.0"><span class="tc-version">:material-tag: v0.34.0</span></a>

The `MasterKey` method retrieves the master key of the Meilisearch container.

---

### Modules Memcached (`docs/modules/memcached.md`)

# Memcached

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.38.0"><span class="tc-version">:material-tag: v0.38.0</span></a>

## Introduction

The Testcontainers module for Memcached.

## Adding this module to your project dependencies

Please run the following command to add the Memcached module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/memcached
```

## Usage example


[Creating a Memcached container](../../modules/memcached/examples_test.go) inside_block:runMemcachedContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.38.0"><span class="tc-version">:material-tag: v0.38.0</span></a>

The Memcached module exposes one entrypoint function to create the Memcached container, and this function receives three parameters:

```golang
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(), "memcached:1.6-alpine")`.

### Container Options

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

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The Memcached container exposes the following methods:

#### HostPort

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.38.0"><span class="tc-version">:material-tag: v0.38.0</span></a>

The `HostPort` method returns the host and port of the Memcached container, in the format `host:port`. Use this method to connect to the Memcached container from your application.


[Get host:port](../../modules/memcached/examples_test.go) inside_block:hostPort

---

### Modules Milvus (`docs/modules/milvus.md`)

# Milvus

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.29.0"><span class="tc-version">:material-tag: v0.29.0</span></a>

## Introduction

The Testcontainers module for Milvus.

## Adding this module to your project dependencies

Please run the following command to add the Milvus module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/milvus
```

## Usage example


[Creating a Milvus container](../../modules/milvus/examples_test.go) inside_block:runMilvusContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.32.0"><span class="tc-version">:material-tag: v0.32.0</span></a>

!!!info
    The `RunContainer(ctx, opts...)` function is deprecated and will be removed in the next major release of _Testcontainers for Go_.

The Milvus module exposes one entrypoint function to create the Milvus container, and this function receives three parameters:

```golang
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*MilvusContainer, 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(), "milvusdb/milvus:v2.6.3")`.

### Container Options

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

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The Milvus container exposes the following methods:

#### ConnectionString

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.29.0"><span class="tc-version">:material-tag: v0.29.0</span></a>

This method returns the connection string to connect to the Milvus container, using the default `19530` port.


[Get connection string](../../modules/milvus/milvus_test.go) inside_block:connectionString


## Examples

### Creating collections

This example shows the usage of the Milvus module to create and retrieve collections.


[Create collections](../../modules/milvus/examples_test.go) inside_block:createCollections

---

### Modules Minio (`docs/modules/minio.md`)

# Minio

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.28.0"><span class="tc-version">:material-tag: v0.28.0</span></a>

## Introduction

The Testcontainers module for Minio.

## Adding this module to your project dependencies

Please run the following command to add the Minio module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/minio
```

## Usage example


[Creating a Minio container](../../modules/minio/examples_test.go) inside_block:runMinioContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.32.0"><span class="tc-version">:material-tag: v0.32.0</span></a>

!!!info
    The `RunContainer(ctx, opts...)` function is deprecated and will be removed in the next major release of _Testcontainers for Go_.

The Minio module exposes one entrypoint function to create the Minio container, and this function receives three parameters:

```golang
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*MinioContainer, 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(), "quay.io/minio/minio:RELEASE.2024-01-16T16-07-38Z")`.

This Quay image requires registry authentication. Log in to `quay.io` with an account that has access to `minio/minio` before running the example or the module tests, or pass an image you can pull to `Run`. The Minio integration tests are excluded from CI until an accessible image is available.

### Container Options

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

#### Username and Password

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.28.0"><span class="tc-version">:material-tag: v0.28.0</span></a>

If you need to set different credentials, you can use the `WithUsername(user string)` and `WithPassword(pwd string)` options.

{% include "../features/common_functional_options_list.md" %}

### Container Methods

#### ConnectionString

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.28.0"><span class="tc-version">:material-tag: v0.28.0</span></a>

This method returns the connection string to connect to the Minio container, using the default `9000` port.


[Get connection string](../../modules/minio/minio_test.go) inside_block:connectionString

---

### Modules Mockserver (`docs/modules/mockserver.md`)

# MockServer

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.28.0"><span class="tc-version">:material-tag: v0.28.0</span></a>

## Introduction

The Testcontainers module for MockServer. MockServer can be used to mock HTTP services by matching requests against user-defined expectations.

## Adding this module to your project dependencies

Please run the following command to add the MockServer module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/mockserver
```

## Usage example


[Creating a MockServer container](../../modules/mockserver/examples_test.go) inside_block:runMockServerContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.32.0"><span class="tc-version">:material-tag: v0.32.0</span></a>

!!!info
    The `RunContainer(ctx, opts...)` function is deprecated and will be removed in the next major release of _Testcontainers for Go_.

The MockServer module exposes one entrypoint function to create the MockServer container, and this function receives three parameters:

```golang
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*MockServerContainer, 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(), "mockserver/mockserver:5.15.0")`.

### Container Options

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

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The MockServer container exposes the following methods:

#### URL

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.28.0"><span class="tc-version">:material-tag: v0.28.0</span></a>

The `URL` method returns the url string to connect to the MockServer container.
It returns a string with the format `http://<host>:<port>`.

It can be used to configure a MockServer client (`github.com/BraspagDevelopers/mock-server-client`), e.g.:


[Using URL with the MockServer client](../../modules/mockserver/examples_test.go) inside_block:connectToMockServer

---

### Modules Mongodb Atlaslocal (`docs/modules/mongodb-atlaslocal.md`)

# MongoDB Atlas Local

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.39.0"><span class="tc-version">:material-tag: v0.39.0</span></a>

## Introduction

The MongoDB Atlas Local module for Testcontainers lets you spin up a local MongoDB Atlas instance in Docker using
[mongodb/mongodb-atlas-local](https://hub.docker.com/r/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](../../modules/mongodb/atlaslocal/examples_test.go) inside_block:runMongoDBAtlasLocalContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.39.0"><span class="tc-version">:material-tag: v0.39.0</span></a>

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

```golang
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 <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.39.0"><span class="tc-version">:material-tag: v0.39.0</span></a>

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 <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.39.0"><span class="tc-version">:material-tag: v0.39.0</span></a>

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 <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.39.0"><span class="tc-version">:material-tag: v0.39.0</span></a>

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 <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.39.0"><span class="tc-version">:material-tag: v0.39.0</span></a>

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 <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.39.0"><span class="tc-version">:material-tag: v0.39.0</span></a>

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

#### WithInitDatabase

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.39.0"><span class="tc-version">:material-tag: v0.39.0</span></a>

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 <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.39.0"><span class="tc-version">:material-tag: v0.39.0</span></a>

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 <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.39.0"><span class="tc-version">:material-tag: v0.39.0</span></a>

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

#### WithMongotLogToStdout

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.39.0"><span class="tc-version">:material-tag: v0.39.0</span></a>

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

#### WithMongotLogToStderr

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.39.0"><span class="tc-version">:material-tag: v0.39.0</span></a>

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

#### WithRunnerLogFile

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.39.0"><span class="tc-version">:material-tag: v0.39.0</span></a>

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

#### WithRunnerLogToStdout

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.39.0"><span class="tc-version">:material-tag: v0.39.0</span></a>

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

#### WithRunnerLogToStderr

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.39.0"><span class="tc-version">:material-tag: v0.39.0</span></a>

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

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The MongoDB Atlas Local container exposes the following methods:


#### ConnectionString

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.39.0"><span class="tc-version">:material-tag: v0.39.0</span></a>

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](../../modules/mongodb/atlaslocal/examples_test.go) inside_block:connectToMongo


#### ReadMongotLogs

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.39.0"><span class="tc-version">:material-tag: v0.39.0</span></a>

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



[Using ReadMongotLogs with the MongoDB client](../../modules/mongodb/atlaslocal/examples_test.go) inside_block:mongotLogsRead


#### ReadRunnerLogs

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.39.0"><span class="tc-version">:material-tag: v0.39.0</span></a>

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



[Using ReadRunnerLogs with the MongoDB client](../../modules/mongodb/atlaslocal/examples_test.go) inside_block:runnerLogsRead

---

### Modules Mongodb (`docs/modules/mongodb.md`)

# MongoDB

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.23.0"><span class="tc-version">:material-tag: v0.23.0</span></a>

## Introduction

The Testcontainers module for MongoDB.

## Adding this module to your project dependencies

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

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

## Usage example


[Creating a MongoDB container](../../modules/mongodb/examples_test.go) inside_block:runMongoDBContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.32.0"><span class="tc-version">:material-tag: v0.32.0</span></a>

!!!info
    The `RunContainer(ctx, opts...)` function is deprecated and will be removed in the next major release of _Testcontainers for Go_.

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

```golang
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*MongoDBContainer, 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(), "mongo:6")`.

### Container Options

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

#### WithUsername

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.27.0"><span class="tc-version">:material-tag: v0.27.0</span></a>

This functional option sets the initial username to be created when the container starts.
It is used in conjunction with `WithPassword` to set a username and its password, creating the specified user with superuser power.

E.g. `testcontainers.WithUsername("mymongouser")`.

#### WithPassword

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.27.0"><span class="tc-version">:material-tag: v0.27.0</span></a>

This functional option sets the initial password to be created when the container starts.
It is used in conjunction with `WithUsername` to set a username and its password, setting the password for the superuser power.

E.g. `testcontainers.WithPassword("mymongopwd")`.

#### WithReplicaSet

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.31.0"><span class="tc-version">:material-tag: v0.31.0</span></a>

The `WithReplicaSet` functional option configures the container to run a single-node MongoDB replica set named `rs`. The MongoDB container will wait until the replica set is ready.

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The MongoDB container exposes the following methods:

#### ConnectionString

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.23.0"><span class="tc-version">:material-tag: v0.23.0</span></a>

The `ConnectionString` method returns the connection string to connect to the MongoDB container.
It returns a string with the format `mongodb://<host>:<port>`.

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


[Using ConnectionString with the MongoDB client](../../modules/mongodb/examples_test.go) inside_block:connectToMongo

---

### Modules Mosquitto (`docs/modules/mosquitto.md`)

# Mosquitto

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

## Introduction

The Testcontainers module for [Eclipse Mosquitto](https://mosquitto.org/), a lightweight open-source MQTT broker that implements the MQTT protocol versions 5, 3.1.1, and 3.1. Commonly used for IoT and messaging workloads.

## Adding this module to your project dependencies

Please run the following command to add the Mosquitto module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/mosquitto
```

## Usage example


[Creating a Mosquitto container](../../modules/mosquitto/examples_test.go) inside_block:runMosquittoContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

The Mosquitto module exposes one entrypoint function to create the Mosquitto container, and this function receives three parameters:

```golang
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(), "eclipse-mosquitto:2")`.

!!!info
    The `eclipse-mosquitto` image requires a configuration file with at least a `listener 1883` directive to accept connections. The module automatically injects a minimal default configuration that enables anonymous connections on port 1883 when no custom configuration is provided.

### Container Options

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

#### WithConfigFile

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

Mounts a custom `mosquitto.conf` file, replacing the module's default embedded configuration. The provided file must contain at least a `listener 1883` directive.

```golang
mosquittoContainer, err := mosquitto.Run(ctx, "eclipse-mosquitto:2",
    mosquitto.WithConfigFile("/path/to/mosquitto.conf"),
)
```

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The Mosquitto container exposes the following methods:

#### BrokerURL

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

Returns the MQTT broker URL (`mqtt://host:port`) for connecting MQTT clients to the broker.

```golang
brokerURL, err := mosquittoContainer.BrokerURL(ctx)
```

---

### Modules Mssql (`docs/modules/mssql.md`)

# MS SQL Server

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.27.0"><span class="tc-version">:material-tag: v0.27.0</span></a>

## Introduction

The Testcontainers module for MS SQL Server.

## Adding this module to your project dependencies

Please run the following command to add the MS SQL Server module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/mssql
```

!!!info
    To use this module with Go 1.23+, set `GODEBUG=x509negativeserial=1`. See the related issue in the [mssql-docker repository](https://github.com/microsoft/mssql-docker/issues/895) for details.
    
    ```shell
    # append to any existing GODEBUG flags instead of overwriting
    export GODEBUG="${GODEBUG:+$GODEBUG,}x509negativeserial=1"
    ```
This occurs because:
- Go 1.23+ has stricter certificate validation that rejects certificates with negative serial numbers by default
- The `x509negativeserial=1` flag temporarily re‑enables acceptance of such certificates
Note: This stricter check in Go 1.23+ is a security hardening. Prefer using images with fixed certificates (see below). Use the GODEBUG workaround only with affected images and in test environments.

!!!info
    This is fixed in SQL2019 CU32 and SQL2022 CU18 (see [SQL Server 2022 CU18 — KB 3867855](https://learn.microsoft.com/en-us/troubleshoot/sql/releases/sqlserver-2022/cumulativeupdate18#3867855)).
    
    Prefer using container images based on these (or newer) CUs to avoid setting `GODEBUG`.

## Usage example


[Creating an MS SQL Server container](../../modules/mssql/examples_test.go) inside_block:runMSSQLServerContainer


!!! warning "EULA Acceptance"
    Due to licensing restrictions you are required to explicitly accept an End User License Agreement (EULA) for the MS SQL Server container image. This is facilitated through the `WithAcceptEULA` function.

    Please see the [`microsoft-mssql-server` image documentation](https://hub.docker.com/_/microsoft-mssql-server#environment-variables) for a link to the EULA document.

## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.32.0"><span class="tc-version">:material-tag: v0.32.0</span></a>

!!!info
    The `RunContainer(ctx, opts...)` function is deprecated and will be removed in the next major release of _Testcontainers for Go_.

The MS SQL Server module exposes one entrypoint function to create the MS SQL Server container, and this function receives three parameters:

```golang
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*MSSQLServerContainer, 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(), "mcr.microsoft.com/mssql/server:2022-RTM-GDR1-ubuntu-20.04")`.

### Container Options

When starting the MS SQL Server container, you can pass options in a variadic way to configure it.

#### WithInitSQL

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.36.0"><span class="tc-version">:material-tag: v0.36.0</span></a>

If you need to execute SQL files when the container starts, you can use `mssql.WithInitSQL(files
...io.Reader)` with one or more `*.sql` files. The files will be executed in order after the
container is ready.


[Example of SQL script](../../modules/mssql/testdata/seed.sql)


This will:

1. Copy each file into the container.
2. Execute them using `sqlcmd` after the container is ready.

#### WithAcceptEula

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.27.0"><span class="tc-version">:material-tag: v0.27.0</span></a>

Due to licensing restrictions you are required to explicitly accept an EULA for this container image. To do so, you must use the function `mssql.WithAcceptEula()`. Failure to include this will result in the container failing to start.

#### WithPassword

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.27.0"><span class="tc-version">:material-tag: v0.27.0</span></a>

If you need to set a different MS SQL Server password, you can use `mssql.WithPassword` with a valid password for MS SQL Server. E.g. `mssql.WithPassword("SuperStrong@Passw0rd")`.

!!!info
    If you set a custom password string, it must adhere to the MS SQL Server [Password Policy](https://learn.microsoft.com/en-us/sql/relational-databases/security/password-policy?view=sql-server-ver16).

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The MS SQL Server container exposes the following methods:

#### ConnectionString

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.27.0"><span class="tc-version">:material-tag: v0.27.0</span></a>

This method returns the connection string to connect to the Microsoft SQL Server container, using the default `1433` port.
It's possible to pass extra parameters to the connection string, e.g. `encrypt=false` or `TrustServerCertificate=true`, in a variadic way.

```golang
connectionString, err := container.ConnectionString(ctx, "encrypt=false", "TrustServerCertificate=true")
```

---

### Modules Mysql (`docs/modules/mysql.md`)

# MySQL

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>

## Introduction

The Testcontainers module for MySQL.

## Adding this module to your project dependencies

Please run the following command to add the MySQL module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/mysql
```

## Usage example

 
[Creating a MySQL container](../../modules/mysql/examples_test.go) inside_block:runMySQLContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.32.0"><span class="tc-version">:material-tag: v0.32.0</span></a>

!!!info
    The `RunContainer(ctx, opts...)` function is deprecated and will be removed in the next major release of _Testcontainers for Go_.

The MySQL module exposes one entrypoint function to create the container, and this function receives three parameters:

```golang
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*MySQLContainer, 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(), "mysql:8.0.36")`.

### Container Options

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

!!!tip
    You can find all the available configuration and environment variables for the MySQL Docker image on [Docker Hub](https://hub.docker.com/_/mysql).

#### Set username, password and database name

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>

If you need to set a different database, and its credentials, you can use `WithUsername`, `WithPassword`, `WithDatabase`
options.

!!!info
    The default values for the username is `root`, for password is `test` and for the default database name is `test`.

#### WithInitScripts

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>

If you would like to perform DDL or DML operations in the MySQL container, add one or more `*.sql`, `*.sql.gz`, or `*.sh`
scripts to the container request, using the `WithScripts(scriptPaths ...string)`. Those files will be copied under `/docker-entrypoint-initdb.d`.


[Example of Init script](../../modules/mysql/testdata/schema.sql)


#### WithConfigFile

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>

If you need to set a custom configuration, you can use `WithConfigFile` option to pass the path to a custom configuration file.

{% include "../features/common_functional_options_list.md" %}

### Container Methods

#### ConnectionString

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>

This method returns the connection string to connect to the MySQL container, using the default `3306` port.
It's possible to pass extra parameters to the connection string, e.g. `tls=skip-verify` or `application_name=myapp`, in a variadic way.


[Get connection string](../../modules/mysql/mysql_test.go) inside_block:connectionString


#### MustConnectionString

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.30.0"><span class="tc-version">:material-tag: v0.30.0</span></a>

Same as `ConnectionString`, but panics if an error occurs while getting the connection string.

---

### Modules Nats (`docs/modules/nats.md`)

# NATS

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.24.0"><span class="tc-version">:material-tag: v0.24.0</span></a>

## Introduction

The Testcontainers module for NATS.

## Adding this module to your project dependencies

Please run the following command to add the NATS module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/nats
```

## Usage example


[Creating a NATS container](../../modules/nats/examples_test.go) inside_block:runNATSContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.32.0"><span class="tc-version">:material-tag: v0.32.0</span></a>

!!!info
    The `RunContainer(ctx, opts...)` function is deprecated and will be removed in the next major release of _Testcontainers for Go_.

The NATS module exposes one entrypoint function to create the NATS container, and this function receives three parameters:

```golang
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*NATSContainer, 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(), "nats:2.9")`.

### Container Options

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

#### Set username and password

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.24.0"><span class="tc-version">:material-tag: v0.24.0</span></a>

If you need to set different credentials, you can use `WithUsername` and `WithPassword`
options. By default, the username, the password are not set. To establish the connection with the NATS container:


[Connect using the credentials](../../modules/nats/examples_test.go) inside_block:natsConnect


#### Cmd Arguments

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.24.0"><span class="tc-version">:material-tag: v0.24.0</span></a>

It's possible to pass extra arguments to the NATS container using the `testcontainers.WithArgument` option. E.g. `nats.WithArgument("cluster_name", "c1")`.
These arguments are passed to the NATS server when it starts, as part of the command line arguments of the entrypoint.

!!! note
    Arguments do not need to be prefixed with `--`: the NATS container will add them automatically.


[Passing arguments](../../modules/nats/examples_test.go) inside_block:withArguments


#### Custom configuration file

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.35.0"><span class="tc-version">:material-tag: v0.35.0</span></a>

It's possible to pass a custom config file to NATS container using `nats.WithConfigFile(strings.NewReader(config))`. The content of `io.Reader` is passed as a `-config /etc/nats.conf` arguments to an entrypoint. 

!!! note
    Changing the connectivity (listen address or ports) can break the container setup. So configuration must be done with care.

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The NATS container exposes the following methods:

#### ConnectionString

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.24.0"><span class="tc-version">:material-tag: v0.24.0</span></a>

This method returns the connection string to connect to the NATS container, using the default `4222` port.


[Get connection string](../../modules/nats/nats_test.go) inside_block:connectionString


#### MustConnectionString

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.30.0"><span class="tc-version">:material-tag: v0.30.0</span></a>

Exactly like `ConnectionString`, but it panics if an error occurs, returning just a string.

## Examples

### NATS Cluster


[NATS Cluster](../../modules/nats/examples_test.go) inside_block:cluster

---

### Modules Nebulagraph (`docs/modules/nebulagraph.md`)

# NebulaGraph

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.39.0"><span class="tc-version">:material-tag: v0.39.0</span></a>

## Introduction

The Testcontainers module for [NebulaGraph](https://nebula-graph.io/), a distributed, scalable, and lightning-fast graph database. This module manages a complete NebulaGraph cluster including Meta Service, Storage Service, and Graph Service components.

## Adding this module to your project dependencies

Add the NebulaGraph module to your Go dependencies:

```go
go get github.com/testcontainers/testcontainers-go/modules/nebulagraph
```

## Usage example


[Creating a NebulaGraph container](../../modules/nebulagraph/nebulagraph_test.go) inside_block:TestNebulaGraphContainer


## Module Reference

### RunCluster function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.39.0"><span class="tc-version">:material-tag: v0.39.0</span></a>

The NebulaGraph module provides a function to create a complete NebulaGraph cluster within a Docker network:

```golang
func RunCluster(ctx context.Context,
    graphdImg string, graphdCustomizers []testcontainers.ContainerCustomizer,
    storagedImg string, storagedCustomizers []testcontainers.ContainerCustomizer,
    metadImg string, metadCustomizers []testcontainers.ContainerCustomizer,
) (*Cluster, error)
```

This function creates a complete NebulaGraph cluster with customizable settings. It returns a `Cluster` struct that contains references to all four components:
- Meta Service (metad)
- Storage Service (storaged)
- Graph Service (graphd)

### Default Configuration

The module uses the following default configurations:

#### Default Images
  - Graph Service: `vesoft/nebula-graphd:v3.8.0`
  - Meta Service: `vesoft/nebula-metad:v3.8.0`
  - Storage Service: `vesoft/nebula-storaged:v3.8.0`
  
#### Exposed Ports
  - Graph Service: 9669 (TCP), 19669 (HTTP)
  - Meta Service: 9559 (TCP), 19559 (HTTP)
  - Storage Service: 9779 (TCP), 19779 (HTTP)

#### Health Checks

The module implements health checks for all services:

- Meta Service: HTTP health check on `/status` endpoint (port 19559)
- Graph Service: HTTP health check on `/status` endpoint (port 19669)
- Storage Service: Log-based health check for initialization
- Activator Service: Log-based health check and exit status for storage registration

A cluster is considered ready when:

1. Meta service is healthy and accessible
2. Graph service is healthy and accessible
3. Storage service is initialized and running
4. Storage service is successfully registered with the meta service via the activator

### Container Options

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

The module supports customization for each service container (Meta, Storage, Graph, and Activator) through ContainerCustomizer options. Common customizations include:

- Custom images for each service
- Environment variables
- Resource limits
- Network settings
- Volume mounts
- Wait strategies

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The `Cluster` struct provides the following methods:

#### ConnectionString

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.39.0"><span class="tc-version">:material-tag: v0.39.0</span></a>

Returns the host:port string for connecting to the NebulaGraph graph service (graphd).

```golang
func (c *Cluster) ConnectionString(ctx context.Context) (string, error)
```

#### Terminate

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.39.0"><span class="tc-version">:material-tag: v0.39.0</span></a>

Stops and removes all containers in the NebulaGraph cluster (Meta, Storage, Graph, and Activator services) and cleans up the associated Docker network.

```golang
func (c *Cluster) Terminate(ctx context.Context) error
```

---

### Modules Neo4j (`docs/modules/neo4j.md`)

# Neo4j

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>

## Introduction

The Testcontainers module for [Neo4j](https://neo4j.com/), the leading graph platform.

## Adding this module to your project dependencies

Please run the following command to add the Neo4j module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/neo4j
```

## Usage example

Running Neo4j as a single-instance server, with the [APOC plugin](https://neo4j.com/developer/neo4j-apoc/) enabled:


[Creating a Neo4j container](../../modules/neo4j/examples_test.go) inside_block:runNeo4jContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.32.0"><span class="tc-version">:material-tag: v0.32.0</span></a>

!!!info
    The `RunContainer(ctx, opts...)` function is deprecated and will be removed in the next major release of _Testcontainers for Go_.

The Neo4j module exposes one entrypoint function to create the Neo4j container, and this function receives three parameters:

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

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

### Container Ports

These are the ports used by the Neo4j container:


[Container Ports](../../modules/neo4j/neo4j.go) inside_block:containerPorts


#### Image

Use the second argument in the `Run` function to set a valid Docker image.
In example: `Run(context.Background(), "neo4j:4.4")`.

### Container Options

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

#### Logger

- DEPRECATED: Use [testcontainers.WithLogger](/features/creating_container/#withlogger) instead.
- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>

This option sets a custom logger to be used by the container. Consider calling this before other `With` functions as these may generate logs.

!!!info
    The logger must implement the testcontainers-go `log.Logger` interface.


[Including a custom logger](../../modules/neo4j/neo4j_test.go) inside_block:withSettings


#### Authentication

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>

By default, the Neo4j container will be started with authentication disabled. If you need to enable authentication, you can
use the `WithAdminPassword(pwd string)` option.

By default, the container will not use authentication, automatically prepending the `WithoutAuthentication` option to the options list.

#### WithLabsPlugins

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>

By default, the Neo4j container will start without any Labs plugins enabled, but you can enable them using the `WithLabsPlugin` optional function.


[Adding Labs Plugins](../../modules/neo4j/neo4j_test.go) inside_block:withLabsPlugin


The list of available plugins is:


[Labs plugins](../../modules/neo4j/config.go) inside_block:labsPlugins


#### WithNeo4jSettings

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>

It's possible to add Neo4j a single configuration setting to the container.
The setting can be added as in the official Neo4j configuration, the function automatically translates the setting
name (e.g. ``dbms.tx_log.rotation.size`) into the format required by the Neo4j container.
This function can be called multiple times. A warning is emitted if a key is overwritten.

To pass multiple settings at once, the `WithNeo4jSettings` function is provided.


[Adding settings](../../modules/neo4j/neo4j_test.go) inside_block:withSettings


!!!warning
    Credentials must be configured with the `WithAdminPassword` optional function.

{% include "../features/common_functional_options_list.md" %}

### Container Methods

#### Bolt URL

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>

The `BoltURL` method returns the connection string to connect to the Neo4j container instance using the Bolt port.
It returns a string with the format `neo4j://<host>:<port>`.


[Connect to Neo4j](../../modules/neo4j/neo4j_test.go) inside_block:boltURL

---

### Modules Nginx (`docs/modules/nginx.md`)

# Nginx

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

## Introduction

The Testcontainers module for [Nginx](https://nginx.org/), a high-performance web server commonly used as a reverse proxy, load balancer, and HTTP cache.

## Adding this module to your project dependencies

Please run the following command to add the Nginx module to your Go dependencies:

```bash
go get github.com/testcontainers/testcontainers-go/modules/nginx
```

## Usage example


[Creating a Nginx container](../../modules/nginx/examples_test.go) inside_block:runNginxContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

The Nginx module exposes one entrypoint function to create the Nginx container, and this function receives three parameters:

```golang
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(), "nginx:1.25")`.

### Container Options

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

#### WithConfigFile

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

`WithConfigFile` mounts a custom `nginx.conf` file at `/etc/nginx/nginx.conf` in the container, replacing the default Nginx main configuration.
The `hostPath` argument must be an absolute path to the configuration file on the host.

```golang
nginx.Run(ctx, "nginx:1.25", nginx.WithConfigFile("/path/to/nginx.conf"))
```

#### WithCustomConfig

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

`WithCustomConfig` mounts a configuration snippet at `/etc/nginx/conf.d/default.conf` in the container.
Use this option to customise the default virtual-host behaviour (locations, upstreams, proxy settings, etc.) without replacing the entire main configuration.
The `hostPath` argument must be an absolute path to the configuration file on the host.

```golang
nginx.Run(ctx, "nginx:1.25", nginx.WithCustomConfig("/path/to/default.conf"))
```

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The Nginx container exposes the following methods:

#### HTTPEndpoint

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

`HTTPEndpoint` returns the HTTP endpoint of the running Nginx container in the form `http://host:mappedPort`, using the container's mapped port 80.


[Get HTTP endpoint](../../modules/nginx/nginx_test.go) inside_block:httpEndpoint


#### HTTPSEndpoint

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

`HTTPSEndpoint` returns the HTTPS endpoint of the running Nginx container in the form `https://host:mappedPort`, using the container's mapped port 443.

```golang
httpsEndpoint, err := nginxContainer.HTTPSEndpoint(ctx)
```

---

### Modules Ollama (`docs/modules/ollama.md`)

# Ollama

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.29.0"><span class="tc-version">:material-tag: v0.29.0</span></a>

## Introduction

The Testcontainers module for Ollama.

## Adding this module to your project dependencies

Please run the following command to add the Ollama module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/ollama
```

## Usage example

The module allows you to run the Ollama container or the local Ollama binary.


[Creating an Ollama container](../../modules/ollama/examples_test.go) inside_block:runOllamaContainer
[Running the local Ollama binary](../../modules/ollama/examples_test.go) inside_block:localOllama


If the local Ollama binary fails to execute, the module will fall back to the container version of Ollama.

## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.32.0"><span class="tc-version">:material-tag: v0.32.0</span></a>

!!!info
    The `RunContainer(ctx, opts...)` function is deprecated and will be removed in the next major release of _Testcontainers for Go_.

The Ollama module exposes one entrypoint function to create the Ollama container, and this function receives three parameters:

```golang
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*OllamaContainer, 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(), "ollama/ollama:0.5.7")`.

### Container Options

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

#### Use Local

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.35.0"><span class="tc-version">:material-tag: v0.35.0</span></a>

!!!warning
    Please make sure the local Ollama binary is not running when using the local version of the module:
    Ollama can be started as a system service, or as part of the Ollama application,
    and interacting with the logs of a running Ollama process not managed by the module is not supported.

If you need to run the local Ollama binary, you can set the `UseLocal` option in the `Run` function.
This option accepts a list of environment variables as a string, that will be applied to the Ollama binary when executing commands.

E.g. `Run(context.Background(), "ollama/ollama:0.5.7", WithUseLocal("OLLAMA_DEBUG=true"))`.

All the container methods are available when using the local Ollama binary, but will be executed locally instead of inside the container.
Please consider the following differences when using the local Ollama binary:

- The local Ollama binary will create a log file in the current working directory, identified by the session ID. E.g. `local-ollama-<session-id>.log`. It's possible to set the log file name using the `OLLAMA_LOGFILE` environment variable. So if you're running Ollama yourself, from the Ollama app, or the standalone binary, you could use this environment variable to set the same log file name.
  - For the Ollama app, the default log file resides in the `$HOME/.ollama/logs/server.log`.
  - For the standalone binary, you should start it redirecting the logs to a file. E.g. `ollama serve > /tmp/ollama.log 2>&1`.
- `ConnectionString` returns the connection string to connect to the local Ollama binary started by the module instead of the container.
- `ContainerIP` returns the bound host IP `127.0.0.1` by default.
- `ContainerIPs` returns the bound host IP `["127.0.0.1"]` by default.
- `CopyToContainer`, `CopyDirToContainer`, `CopyFileToContainer` and `CopyFileFromContainer` return an error if called.
- `GetLogProductionErrorChannel` returns a nil channel.
- `Endpoint` returns the endpoint to connect to the local Ollama binary started by the module instead of the container.
- `Exec` passes the command to the local Ollama binary started by the module instead of inside the container. First argument is the command to execute, and the second argument is the list of arguments, else, an error is returned.
- `GetContainerID` returns the container ID of the local Ollama binary started by the module instead of the container, which maps to `local-ollama-<session-id>`.
- `Host` returns the bound host IP `127.0.0.1` by default.
- `Inspect` returns a ContainerJSON with the state of the local Ollama binary started by the module.
- `IsRunning` returns true if the local Ollama binary process started by the module is running.
- `Logs` returns the logs from the local Ollama binary started by the module instead of the container.
- `MappedPort` returns the port mapping for the local Ollama binary started by the module instead of the container.
- `Start` starts the local Ollama binary process.
- `State` returns the current state of the local Ollama binary process, `stopped` or `running`.
- `Stop` stops the local Ollama binary process.
- `Terminate` calls the `Stop` method and then removes the log file.

The local Ollama binary will create a log file in the current working directory, and it will be available in the container's `Logs` method.

!!!info
    The local Ollama binary will use the `OLLAMA_HOST` environment variable to set the host and port to listen on.
    If the environment variable is not set, it will default to `localhost:0`
    which bind to a loopback address on an ephemeral port to avoid port conflicts.

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The Ollama container exposes the following methods:

#### ConnectionString

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.29.0"><span class="tc-version">:material-tag: v0.29.0</span></a>

This method returns the connection string to connect to the Ollama container, using the default `11434` port.


[Get connection string](../../modules/ollama/ollama_test.go) inside_block:connectionString


#### Commit

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.29.0"><span class="tc-version">:material-tag: v0.29.0</span></a>

This method commits the container to a new image, returning the new image ID.
It should be used after a model has been pulled and loaded into the container in order to create a new image with the model,
and eventually use it as the base image for a new container. That will speed up the execution of the following containers.


[Commit Ollama image](../../modules/ollama/ollama_test.go) inside_block:commitOllamaContainer


## Examples

### Loading Models

It's possible to initialise the Ollama container with a specific model passed as parameter. The supported models are described in the Ollama project: [https://github.com/ollama/ollama?tab=readme-ov-file](https://github.com/ollama/ollama?tab=readme-ov-file) and [https://ollama.com/library](https://ollama.com/library).

!!!warning
    At the moment you use one of those models, the Ollama image will load the model and could take longer to start because of that.

The following examples use the `llama2` model to connect to the Ollama container using HTTP and Langchain.


[Using HTTP](../../modules/ollama/examples_test.go) inside_block:withHTTPModelLlama2
[Using Langchaingo](../../modules/ollama/examples_test.go) inside_block:withLangchainModelLlama2

---

### Modules Openfga (`docs/modules/openfga.md`)

# OpenFGA

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.30.0"><span class="tc-version">:material-tag: v0.30.0</span></a>

## Introduction

The Testcontainers module for OpenFGA.

## Adding this module to your project dependencies

Please run the following command to add the OpenFGA module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/openfga
```

## Usage example


[Creating a OpenFGA container](../../modules/openfga/examples_test.go) inside_block:runOpenFGAContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.32.0"><span class="tc-version">:material-tag: v0.32.0</span></a>

!!!info
    The `RunContainer(ctx, opts...)` function is deprecated and will be removed in the next major release of _Testcontainers for Go_.

The OpenFGA module exposes one entrypoint function to create the OpenFGA container, and this function receives three parameters:

```golang
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*OpenFGAContainer, 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(), "openfga/openfga:v1.5.0")`.

### Container Options

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

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The OpenFGA container exposes the following methods:

#### HttpEndpoint

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.30.0"><span class="tc-version">:material-tag: v0.30.0</span></a>

This method returns the HTTP endpoint to connect to the OpenFGA container, using the `8080` port.


[Get HTTP endpoint](../../modules/openfga/examples_test.go) inside_block:httpEndpoint


#### GrpcEndpoint

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.30.0"><span class="tc-version">:material-tag: v0.30.0</span></a>

This method returns the gRPC endpoint to connect to the OpenFGA container, using the `8081` port.

#### Playground URL

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.30.0"><span class="tc-version">:material-tag: v0.30.0</span></a>

In case you want to interact with the openfga playground, please use the `PlaygroundEndpoint` method, using the `3000` port.
(Playground is disabled by default in newer OpenFGA versions, refer the example [How to enable playground](#running-openfga-with-playground-enabled) to run it with PlayGround enabled)


[Get Playground endpoint](../../modules/openfga/examples_test.go) inside_block:playgroundEndpoint


## Examples

### Writing an OpenFGA model

The following example shows how to write an OpenFGA model using the OpenFGA container.


[Write a Model](../../modules/openfga/examples_test.go) inside_block:openFGAwriteModel


### Running OpenFGA with Playground enabled

The Playground is disabled by default in OpenFGA now. This following code snippet shows how to run OpenFGA with Playground enabled


[Enable Playground](../../modules/openfga/examples_test.go) inside_block:enablePlayground

---

### Modules Openldap (`docs/modules/openldap.md`)

# OpenLDAP

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.28.0"><span class="tc-version">:material-tag: v0.28.0</span></a>

## Introduction

The Testcontainers module for OpenLDAP.

## Adding this module to your project dependencies

Please run the following command to add the OpenLDAP module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/openldap
```

## Usage example


[Creating a OpenLDAP container](../../modules/openldap/examples_test.go) inside_block:runOpenLDAPContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.32.0"><span class="tc-version">:material-tag: v0.32.0</span></a>

!!!info
    The `RunContainer(ctx, opts...)` function is deprecated and will be removed in the next major release of _Testcontainers for Go_.

The OpenLDAP module exposes one entrypoint function to create the OpenLDAP container, and this function receives three parameters:

```golang
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*OpenLDAPContainer, 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(), "bitnamilegacy/openldap:2.6.6")`.

### Container Options

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

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The OpenLDAP container exposes the following methods:

#### ConnectionString

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.28.0"><span class="tc-version">:material-tag: v0.28.0</span></a>

This method returns the connection string to connect to the OpenLDAP container, using the `1389` port.


[Get connection string](../../modules/openldap/openldap_test.go) inside_block:connectionString


#### LoadLdif

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.28.0"><span class="tc-version">:material-tag: v0.28.0</span></a>

This method loads an ldif file in the OpenLDAP server.
It returns and error if there is any problem with the ldif file loading process.


[Load ldif](../../modules/openldap/openldap_test.go) inside_block:loadLdif


#### Initial Ldif

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.28.0"><span class="tc-version">:material-tag: v0.28.0</span></a>

If you would like to load an ldif at the initialization of the openldap container, you can use `WithInitialLdif` function.
The file will be copied after the container is started and loaded in openldap.

---

### Modules Opensearch (`docs/modules/opensearch.md`)

# OpenSearch

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.29.0"><span class="tc-version">:material-tag: v0.29.0</span></a>

## Introduction

The Testcontainers module for OpenSearch.

## Adding this module to your project dependencies

Please run the following command to add the OpenSearch module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/opensearch
```

## Usage example


[Creating a OpenSearch container](../../modules/opensearch/examples_test.go) inside_block:runOpenSearchContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.32.0"><span class="tc-version">:material-tag: v0.32.0</span></a>

!!!info
    The `RunContainer(ctx, opts...)` function is deprecated and will be removed in the next major release of _Testcontainers for Go_.

The OpenSearch module exposes one entrypoint function to create the OpenSearch container, and this function receives three parameters:

```golang
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*OpenSearchContainer, 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(), "opensearchproject/opensearch:2.11.1")`.

### Container Options

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

#### User and password

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.29.0"><span class="tc-version">:material-tag: v0.29.0</span></a>

If you need to set a different password to request authorization when performing HTTP requests to the container, you can use the `WithUsername` and `WithPassword` options. By default, the username is set to `admin`, and the password is set to `admin`.


[Custom Credentials](../../modules/opensearch/examples_test.go) inside_block:runOpenSearchContainer


{% include "../features/common_functional_options_list.md" %}

### Container Methods

The OpenSearch container exposes the following methods:

#### Address

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.29.0"><span class="tc-version">:material-tag: v0.29.0</span></a>

The `Address` method returns the location where the OpenSearch container is listening.
It returns a string with the format `http://<host>:<port>`.

!!!warning
    TLS is not supported at the moment.


[Connecting using HTTP](../../modules/opensearch/opensearch_test.go) inside_block:httpConnection

---

### Modules Orientdb (`docs/modules/orientdb.md`)

# OrientDB

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

## Introduction

The Testcontainers module for [OrientDB](https://orientdb.org/), an open-source multi-model NoSQL database that combines graph, document, key/value, and object models in a single engine.

## Adding this module to your project dependencies

Please run the following command to add the OrientDB module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/orientdb
```

## Usage example


[Creating a OrientDB container](../../modules/orientdb/examples_test.go) inside_block:ExampleRun


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

The OrientDB module exposes one entrypoint function to create the OrientDB container, and this function receives three parameters:

```golang
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(), "orientdb:3.2")`.

### Container Options

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

#### WithRootPassword

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

Sets the root password for the OrientDB instance by setting the `ORIENTDB_ROOT_PASSWORD` environment variable. The default password is `rootpwd`.

```golang
orientdb.WithRootPassword("mysecret")
```

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The OrientDB container exposes the following methods:

#### ServerURL

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

The `ServerURL` method returns the connection string for Java/JDBC clients using the OrientDB binary remote protocol, in the format `remote:<host>:<port>`.

```golang
serverURL, err := orientdbContainer.ServerURL(ctx)
// serverURL = "remote:localhost:2424"
```

#### StudioURL

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

The `StudioURL` method returns the URL for the OrientDB Studio web UI, in the format `http://<host>:<port>`.

```golang
studioURL, err := orientdbContainer.StudioURL(ctx)
// studioURL = "http://localhost:2480"
```

---

### Modules Papercutsmtp (`docs/modules/papercutsmtp.md`)

# PapercutSMTP

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

## Introduction

The Testcontainers module for [Papercut SMTP](https://github.com/ChangemakerStudios/Papercut-SMTP), a lightweight SMTP server with a built-in web UI for capturing and inspecting outbound emails during testing. No messages are relayed to real recipients — all sent mail is held in memory and viewable through the web interface.

## Adding this module to your project dependencies

Please run the following command to add the PapercutSMTP module to your Go dependencies:

```shell
go get github.com/testcontainers/testcontainers-go/modules/papercutsmtp
```

## Usage example


[Creating a PapercutSMTP container](../../modules/papercutsmtp/examples_test.go) inside_block:runPapercutSMTPContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

The PapercutSMTP module exposes one entrypoint function to create the PapercutSMTP container, and this function receives three parameters:

```golang
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(), "changemakerstudiosus/papercut-smtp:latest")`.

### Container Options

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

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The PapercutSMTP container exposes the following methods:

#### SMTPEndpoint

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

This method returns the `host:port` endpoint to connect to the SMTP server on port `2525`.


[Get SMTP endpoint](../../modules/papercutsmtp/papercutsmtp_test.go) inside_block:smtpEndpoint


#### HTTPURL

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

This method returns the URL for the Papercut SMTP web UI on port `8080`, where captured emails can be inspected.


[Get HTTP URL](../../modules/papercutsmtp/papercutsmtp_test.go) inside_block:httpURL

---

### Modules Pinecone (`docs/modules/pinecone.md`)

# Pinecone

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.36.0"><span class="tc-version">:material-tag: v0.36.0</span></a>

## Introduction

The Testcontainers module for Pinecone.

## Adding this module to your project dependencies

Please run the following command to add the Pinecone module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/pinecone
```

## Usage example


[Creating a Pinecone container](../../modules/pinecone/examples_test.go) inside_block:ExampleRun


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.36.0"><span class="tc-version">:material-tag: v0.36.0</span></a>

!!!info
    The `RunContainer(ctx, opts...)` function is deprecated and will be removed in the next major release of _Testcontainers for Go_.

The Pinecone module exposes one entrypoint function to create the Pinecone container, and this function receives three parameters:

```golang
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(), "ghcr.io/pinecone-io/pinecone-local:latest")`.

### Container Options

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

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The Pinecone container exposes the following methods:

#### HttpEndpoint

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.36.0"><span class="tc-version">:material-tag: v0.36.0</span></a>

The `HttpEndpoint` method returns the location where the Pinecone container is listening.
It returns a string with the format `http://<host>:<port>`.


[Connecting using HTTP](../../modules/pinecone/examples_test.go) inside_block:httpConnection

---

### Modules Podman (`docs/modules/podman.md`)

# Podman

Not available until the next release <a href="https://github.com/testcontainers/testcontainers-go"><span class="tc-version">:material-tag: main</span></a>

The Podman module registers Podman as a runtime provider for Testcontainers for Go.
It uses Podman's Docker-compatible API and its `podman` default bridge network.
Podman must already be running; the module does not start or install it.

## Adding this module to your project dependencies

```shell
go get github.com/testcontainers/testcontainers-go/modules/podman
```

Import the module in your test package to register the provider:

```go
import _ "github.com/testcontainers/testcontainers-go/modules/podman"
```

Adding the dependency to `go.mod` alone does not register it. Importing the package
registers the provider without connecting to Podman.

## Selecting Podman

Set the provider before running your tests:

```shell
TESTCONTAINERS_PROVIDER=podman go test ./...
```

Alternatively, set `provider=podman` in `~/.testcontainers.properties`.
An explicit provider in code takes precedence over the environment variable,
which takes precedence over the properties file.

The module retains standard Testcontainers endpoint and socket discovery.
See [Using Podman instead of Docker](../system_requirements/using_podman.md)
for socket activation, `DOCKER_HOST`, and platform-specific Ryuk requirements.

## Migrating existing tests

Existing `ProviderPodman` calls and automatic Podman detection continue to work
through the built-in compatibility path. You do not have to import the module
immediately. `ProviderPodman` is deprecated, with removal deferred to a future
breaking release.

To migrate, import this module and select Podman through configuration before any
Testcontainers operation. Per-container provider options are then unnecessary
for tests using that configured runtime.

## Testing the provider

The main CI pipeline runs the core Go module against native rootful Podman on
Ubuntu 24.04, with Ryuk enabled, for changes to core or `modules/podman`.
This job does not run the database modules or examples. It runs the core suite
with the Podman module imported through a temporary Go workspace, and separate
smoke tests without that import for automatic detection and `ProviderPodman`.
An orphan-cleanup test verifies that Ryuk deletes stopped containers, networks
and explicitly labelled volumes after the test process exits.

To run the same tests locally, configure a rootful Podman socket and Ryuk as
described in the system requirements, then run
`./.github/scripts/test-core-podman.sh` from the repository root.
The script temporarily adds provider imports to the core test binaries and
removes them when it exits. It does not modify core's module dependencies.

---

### Modules Postgres (`docs/modules/postgres.md`)

# Postgres

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>

## Introduction

The Testcontainers module for Postgres.

## Adding this module to your project dependencies

Please run the following command to add the Postgres module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/postgres
```

## Usage example


[Creating a Postgres container](../../modules/postgres/examples_test.go) inside_block:runPostgresContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.32.0"><span class="tc-version">:material-tag: v0.32.0</span></a>

!!!info
    The `RunContainer(ctx, opts...)` function is deprecated and will be removed in the next major release of _Testcontainers for Go_.

The Postgres module exposes one entrypoint function to create the Postgres container, and this function receives three parameters:

```golang
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*PostgresContainer, 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(), "postgres:16-alpine")`.

### Container Options

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

!!!tip
    You can find all the available configuration and environment variables for the Postgres Docker image on [Docker Hub](https://hub.docker.com/_/postgres).

#### Initial Database

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>

If you need to set a different database, and its credentials, you can use the `WithDatabase(db string)`, `WithUsername(user string)` and `WithPassword(pwd string)` options.

#### WithInitScripts

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>

If you would like to do additional initialization in the Postgres container, add one or more `*.sql`, `*.sql.gz`, or `*.sh` scripts to the container request with the `WithInitScripts` function.
Those files will be copied after the container is created but before it's started under `/docker-entrypoint-initdb.d`. According to Postgres Docker image,
it will run any `*.sql` files, run any executable `*.sh` scripts, and source any non-executable `*.sh` scripts found in that directory to do further
initialization before starting the service.

An example of a `*.sh` script that creates a user and database is shown below:


[Init script content](../../modules/postgres/testdata/init-user-db.sh)


#### Ordered Init Scripts

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

If you would like to run the init scripts in a specific order, you can use the `WithOrderedInitScripts` function, which copies the given scripts in the order they are provided to the container, prefixed with the order number so that Postgres executes them in the correct order.


[Ordered init scripts](../../modules/postgres/postgres_test.go) inside_block:orderedInitScripts


#### WithConfigFile

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>

In the case you have a custom config file for Postgres, it's possible to copy that file into the container before it's started, using the `WithConfigFile(cfgPath string)` function.

This function can be used `WithSSLSettings` but requires your configuration correctly sets the SSL properties. See the below section for more information.

!!!tip
    For information on what is available to configure, see the [PostgreSQL docs](https://www.postgresql.org/docs/14/runtime-config.html) for the specific version of PostgreSQL that you are running.

#### SSL Configuration

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.35.0"><span class="tc-version">:material-tag: v0.35.0</span></a>

If you would like to use SSL with the container you can use the `WithSSLSettings`. This function accepts a `SSLSettings` which has the required secret material, namely the ca-certificate, server certificate and key. The container will copy this material to `/tmp/testcontainers-go/postgres/ca_cert.pem`, `/tmp/testcontainers-go/postgres/server.cert` and `/tmp/testcontainers-go/postgres/server.key`

This function requires a custom postgres configuration file that enables SSL and correctly sets the paths on the key material.

If you use this function by itself or in conjunction with `WithConfigFile` your custom conf must set the required ssl fields. The configuration must correctly align the key material provided via `SSLSettings` with the server configuration, namely the paths. Your configuration will need to contain the following:

```
ssl = on
ssl_ca_file = '/tmp/testcontainers-go/postgres/ca_cert.pem'
ssl_cert_file = '/tmp/testcontainers-go/postgres/server.cert'
ssl_key_file = '/tmp/testcontainers-go/postgres/server.key'
```

!!!warning
    This function assumes the postgres user in the container is `postgres`

    There is no current support for mutual authentication.

    The `SSLSettings` function will modify the container `entrypoint`. This is done so that key material copied over to the container is chowned by `postgres`. All other container arguments will be passed through to the original container entrypoint.

#### Snapshot/Restore with custom driver

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.32.0"><span class="tc-version">:material-tag: v0.32.0</span></a>

You can tell the module to use the database driver you have imported in your test package by setting `postgres.WithSQLDriver("name")` to your driver name.

{% include "../features/common_functional_options_list.md" %}

### Container Methods

#### ConnectionString

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>

This method returns the connection string to connect to the Postgres container, using the default `5432` port.
It's possible to pass extra parameters to the connection string, e.g. `sslmode=disable` or `application_name=myapp`, in a variadic way.


[Get connection string](../../modules/postgres/postgres_test.go) inside_block:connectionString


### Postgres variants

It's possible to use the Postgres container with PGVector, Timescale or Postgis, to name a few. You simply need to update the image name and the wait strategy.


[Image for PGVector](../../modules/postgres/postgres_test.go) inside_block:pgvector
[Image for Timescale](../../modules/postgres/postgres_test.go) inside_block:timescale
[Image for Postgis](../../modules/postgres/postgres_test.go) inside_block:postgis


## Examples

### Wait Strategies

The postgres module works best with these wait strategies.
No default is supplied, so you need to set it explicitly.


[Example Wait Strategies](../../modules/postgres/wait_strategies.go) inside_block:waitStrategy


### Using Snapshots

This example shows the usage of the postgres module's Snapshot feature to give each test a clean database without having
to recreate the database container on every test or run heavy scripts to clean your database. This makes the individual
tests very modular, since they always run on a brand-new database.

!!!tip
    You should never pass the `"postgres"` system database as the container database name if you want to use snapshots. 
    The Snapshot logic requires dropping the connected database and using the system database to run commands, which will
    not work if the database for the container is set to `"postgres"`.


[Test with a reusable Postgres container](../../modules/postgres/postgres_test.go) inside_block:snapshotAndReset


### Snapshot/Restore with custom driver

The snapshot/restore feature tries to use the `postgres` driver with go's included `sql.DB` package to perform database operations.
If the `postgres` driver is not installed, it will fall back to using `docker exec`, which works, but is slower.

You can tell the module to use the database driver you have imported in your test package by setting `postgres.WithSQLDriver("name")` to your driver name.

For example, if you use pgx, see the example below.

```go
package my_test

import (
	"testing"

	_ "github.com/jackc/pgx/v5/stdlib"

	"github.com/testcontainers/testcontainers-go/modules/postgres"
)
```

The above code snippet is importing the `pgx` driver and the _Testcontainers for Go_ Postgres module.


[Snapshot/Restore with custom driver](../../modules/postgres/postgres_test.go) inside_block:snapshotAndReset

---

### Modules Presto (`docs/modules/presto.md`)

# Presto

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

## Introduction

The Testcontainers module for [Presto](https://prestodb.io/), a distributed SQL query engine for big data.
Presto is designed to run interactive analytic queries against data sources of all sizes, from gigabytes to petabytes.

## Adding this module to your project dependencies

Please run the following command to add the Presto module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/presto
```

## Usage example


[Creating a Presto container](../../modules/presto/examples_test.go) inside_block:runPrestoContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

The Presto module exposes one entrypoint function to create the Presto container, and this function receives three parameters:

```golang
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(), "prestodb/presto:0.286")`.

### Wait Strategy

The module waits for the Presto coordinator to finish starting up by polling
the `/v1/info` HTTP endpoint on port `8080/tcp` until the `starting` field in
the JSON response is `false`. A startup timeout of 2 minutes is applied.

### Container Ports

Here you can find the list with the default ports used by the Presto container.


[Container Ports](../../modules/presto/presto.go) inside_block:containerPorts


### Container Options

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

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The Presto container exposes the following methods:

#### ConnectionString

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

This method returns the HTTP connection string for the Presto coordinator, e.g. `http://localhost:8080`.

```golang
connStr, err := prestoContainer.ConnectionString(ctx)
```

---

### Modules Pulsar (`docs/modules/pulsar.md`)

# Apache Pulsar

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.19.0"><span class="tc-version">:material-tag: v0.19.0</span></a>

## Introduction

The Testcontainers module for Apache Pulsar.

Testcontainers can be used to automatically create [Apache Pulsar](https://pulsar.apache.org) containers without external services.

It's based on the official Apache Pulsar docker image, so it is recommended to read the [official guide](https://pulsar.apache.org/docs/next/getting-started-docker/).

## Adding this module to your project dependencies

Please run the following command to add the Apache Pulsar module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/pulsar
```

## Usage example

Create a `Pulsar` container to use it in your tests:


[Creating a Pulsar container](../../modules/pulsar/examples_test.go) inside_block:runPulsarContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.32.0"><span class="tc-version">:material-tag: v0.32.0</span></a>

!!!info
    The `RunContainer(ctx, opts...)` function is deprecated and will be removed in the next major release of _Testcontainers for Go_.

The Pulsar module exposes one entrypoint function to create the container, and this function receives three parameters:

```golang
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(), "apachepulsar/pulsar:4.0.9")`.

### Container Options

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

#### WithPulsarEnv

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.19.0"><span class="tc-version">:material-tag: v0.19.0</span></a>

If you need to set Pulsar configuration variables you can use the `WithPulsarEnv` to set Pulsar environment variables: the `PULSAR_PREFIX_` prefix will be automatically added for you.

For example, if you want to enable `brokerDeduplicationEnabled`:


[Set configuration variables](../../modules/pulsar/pulsar_test.go) inside_block:addPulsarEnv


It will result in the `PULSAR_PREFIX_brokerDeduplicationEnabled=true` environment variable being set in the container request.

#### WithFunctionsWorker

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.19.0"><span class="tc-version">:material-tag: v0.19.0</span></a>

If you need to test Pulsar IO framework you can enable the Pulsar Functions Worker with the `WithFunctionsWorker` option:


[Create a Pulsar container with functions worker](../../modules/pulsar/pulsar_test.go) inside_block:withFunctionsWorker


#### WithTransactions

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.19.0"><span class="tc-version">:material-tag: v0.19.0</span></a>

If you need to test Pulsar Transactions you can enable the transactions feature:


[Create a Pulsar container with transactions](../../modules/pulsar/pulsar_test.go) inside_block:withTransactions


{% include "../features/common_functional_options_list.md" %}

### Container methods

Once you have a Pulsar container, then you can retrieve the broker and the admin url:

#### Admin URL

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.19.0"><span class="tc-version">:material-tag: v0.19.0</span></a>


[Get admin url](../../modules/pulsar/pulsar_test.go) inside_block:getAdminURL


#### Broker URL

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.19.0"><span class="tc-version">:material-tag: v0.19.0</span></a>


[Get broker url](../../modules/pulsar/pulsar_test.go) inside_block:getBrokerURL

---

### Modules Qdrant (`docs/modules/qdrant.md`)

# Qdrant

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.29.0"><span class="tc-version">:material-tag: v0.29.0</span></a>

## Introduction

The Testcontainers module for Qdrant.

## Adding this module to your project dependencies

Please run the following command to add the Qdrant module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/qdrant
```

## Usage example


[Creating a Qdrant container](../../modules/qdrant/examples_test.go) inside_block:runQdrantContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.32.0"><span class="tc-version">:material-tag: v0.32.0</span></a>

!!!info
    The `RunContainer(ctx, opts...)` function is deprecated and will be removed in the next major release of _Testcontainers for Go_.

The Qdrant module exposes one entrypoint function to create the Qdrant container, and this function receives three parameters:

```golang
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*QdrantContainer, 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(), "qdrant/qdrant:v1.7.4")`.

### Container Options

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

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The Qdrant container exposes the following methods:

#### REST Endpoint

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.29.0"><span class="tc-version">:material-tag: v0.29.0</span></a>

This method returns the REST endpoint of the Qdrant container, using the default `6333` port.


[Get REST endpoint](../../modules/qdrant/qdrant_test.go) inside_block:restEndpoint


#### Web UI Endpoint

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.29.0"><span class="tc-version">:material-tag: v0.29.0</span></a>

This method returns the Web UI endpoint of the Qdrant container (`/dashboard`), using the default `6333` port.


[Get Web UI endpoint](../../modules/qdrant/qdrant_test.go) inside_block:webUIEndpoint


#### gRPC Endpoint

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.29.0"><span class="tc-version">:material-tag: v0.29.0</span></a>

This method returns the gRPC endpoint of the Qdrant container, using the default `6334` port.


[Get gRPC endpoint](../../modules/qdrant/qdrant_test.go) inside_block:gRPCEndpoint


### Full Example

Here you can find a full example on how to use the qdrant-go module to perform operations with Qdrant, as seen in the [examples provided by the module](https://github.com/qdrant/go-client/blob/76db566382ed656a920fa273db1a58eec2417dcd/examples/main.go#L1) itself:


[Full Example](../../modules/qdrant/examples_test.go) inside_block:fullExample

---

### Modules Questdb (`docs/modules/questdb.md`)

# QuestDB

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

## Introduction

QuestDB is an open-source time-series database designed for high-throughput ingestion and fast SQL queries. It supports the InfluxDB line protocol for fast writes, a PostgreSQL wire protocol for SQL queries, and a REST API with a built-in web console.

## Adding this module to your project dependencies

Please run the following command to add the QuestDB module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/questdb
```

## Usage example


[Creating a QuestDB container](../../modules/questdb/examples_test.go) inside_block:runQuestDBContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

The QuestDB module exposes one entrypoint function to create the QuestDB container, and this function receives three parameters:

```golang
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(), "questdb/questdb:7.4")`.

### Container Options

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

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The QuestDB container exposes the following methods:

#### HTTPEndpoint

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

Returns the URL of the QuestDB HTTP web console and REST API, using the `9000/tcp` port.


[HTTPEndpoint](../../modules/questdb/examples_test.go) inside_block:httpEndpoint


The returned URL has the format `http://host:port`.

#### PGEndpoint

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

Returns the PostgreSQL wire protocol connection string for the QuestDB container, using the `8812/tcp` port and the built-in default credentials (`admin`/`quest`).


[PGEndpoint](../../modules/questdb/examples_test.go) inside_block:pgEndpoint


The returned URL has the format `postgres://admin:[REDACTED]@host:port/qdb`.

#### InfluxDBEndpoint

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

Returns the InfluxDB line protocol endpoint address of the QuestDB container, using the `9009/tcp` port. This endpoint is used for high-throughput time-series data ingestion.


[InfluxDBEndpoint](../../modules/questdb/examples_test.go) inside_block:influxDBEndpoint


The returned address has the format `host:port`.

---

### Modules Rabbitmq (`docs/modules/rabbitmq.md`)

# RabbitMQ

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.25.0"><span class="tc-version">:material-tag: v0.25.0</span></a>

## Introduction

The Testcontainers module for RabbitMQ.

## Adding this module to your project dependencies

Please run the following command to add the RabbitMQ module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/rabbitmq
```

## Usage example


[Creating a RabbitMQ container](../../modules/rabbitmq/examples_test.go) inside_block:runRabbitMQContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.32.0"><span class="tc-version">:material-tag: v0.32.0</span></a>

!!!info
    The `RunContainer(ctx, opts...)` function is deprecated and will be removed in the next major release of _Testcontainers for Go_.

The RabbitMQ module exposes one entrypoint function to create the RabbitMQ container, and this function receives three parameters:

```golang
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*RabbitMQContainer, 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(), "rabbitmq:3.7.25-management-alpine")`.

!!!warning
    From [https://hub.docker.com/_/rabbitmq](https://hub.docker.com/_/rabbitmq): "As of RabbitMQ 3.9, all of the docker-specific variables listed below are deprecated and no longer used. Please use a configuration file instead; visit [rabbitmq.com/configure](https://rabbitmq.com/configure) to learn more about the configuration file. For a starting point, the 3.8 images will print out the config file it generated from supplied environment variables."

    - RABBITMQ_DEFAULT_PASS_FILE
    - RABBITMQ_DEFAULT_USER_FILE
    - RABBITMQ_MANAGEMENT_SSL_CACERTFILE
    - RABBITMQ_MANAGEMENT_SSL_CERTFILE
    - RABBITMQ_MANAGEMENT_SSL_DEPTH
    - RABBITMQ_MANAGEMENT_SSL_FAIL_IF_NO_PEER_CERT
    - RABBITMQ_MANAGEMENT_SSL_KEYFILE
    - RABBITMQ_MANAGEMENT_SSL_VERIFY
    - RABBITMQ_SSL_CACERTFILE
    - RABBITMQ_SSL_CERTFILE
    - RABBITMQ_SSL_DEPTH
    - RABBITMQ_SSL_FAIL_IF_NO_PEER_CERT
    - RABBITMQ_SSL_KEYFILE
    - RABBITMQ_SSL_VERIFY
    - RABBITMQ_VM_MEMORY_HIGH_WATERMARK

### Container Options

When starting the RabbitMQ container, you can pass options in a variadic way to configure it. All these options will be automatically rendered into the RabbitMQ's custom configuration file, located at `/etc/rabbitmq/rabbitmq-custom.conf`.

#### Default Admin

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.25.0"><span class="tc-version">:material-tag: v0.25.0</span></a>
If you need to set the username and/or password for the admin user, you can use the `WithAdminUsername(username string)` and `WithAdminPassword(pwd string)` options.

!!!info
    By default, the admin username is `guest` and the password is `guest`.

#### SSL settings

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.25.0"><span class="tc-version">:material-tag: v0.25.0</span></a>

In the case you need to enable SSL, you can use the `WithSSL(settings SSLSettings)` option. This option will enable SSL with the passed settings:


[Enabling SSL](../../modules/rabbitmq/examples_test.go) inside_block:enableSSL


You'll find a log entry similar to this one in the container logs:

```
2023-09-13 13:05:10.213 [info] <0.548.0> started TLS (SSL) listener on [::]:5671
```

#### Startup Commands

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.25.0"><span class="tc-version">:material-tag: v0.25.0</span></a>

The RabbitMQ module includes several test implementations of the `testcontainers.Executable` interface: Binding, Exchange, OperatorPolicy, Parameter, Permission, Plugin, Policy, Queue, User, VirtualHost and VirtualHostLimit. You could use them as reference to understand how the startup commands are generated, but please consider this test implementation could not be complete for your use case.

You could use this feature to run a custom script, or to run a command that is not supported by the module. RabbitMQ examples of this could be:

- Enable plugins
- Add virtual hosts and virtual hosts limits
- Add exchanges
- Add queues
- Add bindings
- Add policies
- Add operator policies
- Add parameters
- Add permissions
- Add users

Please refer to the RabbitMQ documentation to build your own commands.


[Add Virtual Hosts](../../modules/rabbitmq/rabbitmq_test.go) inside_block:addVirtualHosts
[Add Exchanges](../../modules/rabbitmq/rabbitmq_test.go) inside_block:addExchanges
[Add Queues](../../modules/rabbitmq/rabbitmq_test.go) inside_block:addQueues
[Add Bindings](../../modules/rabbitmq/rabbitmq_test.go) inside_block:addBindings
[Add Policies](../../modules/rabbitmq/rabbitmq_test.go) inside_block:addPolicies
[Add Permissions](../../modules/rabbitmq/rabbitmq_test.go) inside_block:addPermissions
[Add Users](../../modules/rabbitmq/rabbitmq_test.go) inside_block:addUsers
[Enabling Plugins](../../modules/rabbitmq/rabbitmq_test.go) inside_block:enablePlugins


{% include "../features/common_functional_options_list.md" %}

### Container Methods

The RabbitMQ container exposes the following methods:

#### AMQP URLs

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.25.0"><span class="tc-version">:material-tag: v0.25.0</span></a>

The RabbitMQ container exposes two methods to retrieve the AMQP URLs in order to connect to the RabbitMQ instance using AMQP clients:

- `AmqpURL()`, returns the AMQP URL.
- `AmqpsURL()`, returns the AMQPS URL.

#### HTTP management URLs

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.25.0"><span class="tc-version">:material-tag: v0.25.0</span></a>

The RabbitMQ container exposes two methods to retrieve the HTTP URLs for management:

- `HttpURL()`, returns the management URL over HTTP.
- `HttpsURL()`, returns the management URL over HTTPS.

---

### Modules Ravendb (`docs/modules/ravendb.md`)

# RavenDB

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

## Introduction

The Testcontainers module for RavenDB, an open-source NoSQL document database with multi-document ACID transactions. It is designed for web-scale, high-performance applications and provides a built-in Studio web UI for management and exploration.

## Adding this module to your project dependencies

Please run the following command to add the RavenDB module to your Go dependencies:

```sh
go get github.com/testcontainers/testcontainers-go/modules/ravendb
```

## Usage example


[Creating a RavenDB container](../../modules/ravendb/examples_test.go) inside_block:runRavenDBContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

The RavenDB module exposes one entrypoint function to create the RavenDB container, and this function receives three parameters:

```golang
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(), "ravendb/ravendb:6.0-ubuntu-latest")`.

The module automatically sets the required environment variables for running RavenDB in unsecured development mode:

- `RAVEN_Setup_Mode=None`
- `RAVEN_License_Eula_Accepted=true`
- `RAVEN_Security_UnsecuredAccessAllowed=PublicNetwork`
- `RAVEN_Logs_Mode=None`

### Container Options

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

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The RavenDB container exposes the following methods:

#### ManagementURL

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

The `ManagementURL` method returns the URL of the RavenDB management interface (Studio UI and REST API).
It returns a string with the format `http://<host>:<port>`.

It can be used to configure a RavenDB client or to access the Studio UI in a browser, e.g.:


[Using ManagementURL](../../modules/ravendb/examples_test.go) inside_block:ExampleRun_managementURL


#### TCPEndpoint

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

The `TCPEndpoint` method returns the `host:port` endpoint for RavenDB's TCP port (`38888`),
used for subscriptions and cluster/replication communication.

---

### Modules Redis (`docs/modules/redis.md`)

# Redis

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>

## Introduction

The Testcontainers module for Redis.

## Adding this module to your project dependencies

Please run the following command to add the Redis module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/redis
```

## Usage example


[Creating a Redis container](../../modules/redis/examples_test.go) inside_block:runRedisContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.32.0"><span class="tc-version">:material-tag: v0.32.0</span></a>

!!!info
    The `RunContainer(ctx, opts...)` function is deprecated and will be removed in the next major release of _Testcontainers for Go_.

The Redis module exposes one entrypoint function to create the container, and this function receives three parameters:

```golang
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*RedisContainer, 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(), "redis:7")`.

### Container Options

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

!!!tip
    You can find all the available configuration and environment variables for the Redis Docker image on [Docker Hub](https://hub.docker.com/_/redis).

#### WithSnapshotting

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>

By default Redis saves snapshots of the dataset on disk, in a binary file called dump.rdb. You can configure Redis to have it save the dataset every `N` seconds if there are at least `M` changes in the dataset. E.g. `WithSnapshotting(10, 1)`.

!!!tip
    Please check [Redis docs on persistence](https://redis.io/docs/management/persistence/#snapshotting) for more information.

#### WithLogLevel

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>

By default Redis produces a log message to the standard Redis log, the format accepts printf-alike specifiers, while level is a string describing the log level to use when emitting the log, and must be one of the following: `LogLevelDebug`, `LogLevelVerbose`, `LogLevelNotice`, `LogLevelWarning`. E.g. `WithLogLevel(LogLevelDebug)`. If the specified log level is invalid, verbose is used by default.

!!!tip
    Please check [Redis docs on logging](https://redis.io/docs/reference/modules/modules-api-ref/#redismodule_log) for more information.

#### WithConfigFile

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>

In the case you have a custom config file for Redis, it's possible to copy that file into the container before it's started. E.g. `WithConfigFile(filepath.Join("testdata", "redis7.conf"))`.

#### WithTLS

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

In the case you want to enable TLS for the Redis container, you can use the `WithTLS()` option. This options enables TLS on the `6379/tcp` port and uses a secure URL (e.g. `rediss://host:port`).

!!!info
    In case you want to use Non-mutual TLS (i.e. client authentication is not required), you can customize the CMD arguments by using the `WithCmdArgs` option. E.g. `WithCmdArgs("--tls-auth-clients", "no")`.

The module automatically generates three certificates, a CA certificate, a client certificate and a Redis certificate. Please use the `TLSConfig()` container method to get the TLS configuration and use it to configure the Redis client. See more details in the [TLSConfig](#tlsconfig) section.

{% include "../features/common_functional_options_list.md" %}

### Container Methods

#### ConnectionString

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>

This method returns the connection string to connect to the Redis container, using the default `6379` port, and `redis` schema.


[Get connection string](../../modules/redis/redis_test.go) inside_block:connectionString


If the container is started with TLS enabled, the connection string is `rediss://host:port`, using the `rediss` schema.

#### TLSConfig

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.37.0"><span class="tc-version">:material-tag: v0.37.0</span></a>

This method returns the TLS configuration for the Redis container, nil if TLS is not enabled.


[Get TLS config](../../modules/redis/redis_test.go) inside_block:tlsConfig


In the above example, the options are used to configure a Redis client with TLS enabled.

---

### Modules Redpanda (`docs/modules/redpanda.md`)

# Redpanda

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>

## Introduction

Redpanda is a streaming data platform for developers. Kafka API compatible. 10x faster. No ZooKeeper. No JVM!
This Testcontainers module provides the following APIs:

- Kafka API
- Schema Registry API
- Redpanda Admin API
- HTTP Proxy API (PandaProxy)

## Adding this module to your project dependencies

Please run the following command to add the Redpanda module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/redpanda
```

## Usage example


[Creating a Redpanda container](../../modules/redpanda/examples_test.go) inside_block:runRedpandaContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.32.0"><span class="tc-version">:material-tag: v0.32.0</span></a>

!!!info
    The `RunContainer(ctx, opts...)` function is deprecated and will be removed in the next major release of _Testcontainers for Go_.

The Redpanda module exposes one entrypoint function to create the Redpanda container, and this function receives three parameters:

```golang
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*RedpandaContainer, 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(), "docker.redpanda.com/redpandadata/redpanda:v23.1.7")`.

### Container Options

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

#### TLS Encryption

If you need to enable TLS use `WithTLS` with a valid PEM encoded certificate and key.

#### Additional Listener

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.28.0"><span class="tc-version">:material-tag: v0.28.0</span></a>

There are scenarios where additional listeners are needed, for example if you
want to consume/from another container in the same network

You can use the `WithListener` option to add a listener to the Redpanda container.

[Register additional listener](../../modules/redpanda/redpanda_test.go) inside_block:withListenerRP


Container defined in the same network

[Start Kcat container](../../modules/redpanda/redpanda_test.go) inside_block:withListenerKcat


Produce messages using the new registered listener

[Produce/consume via registered listener](../../modules/redpanda/redpanda_test.go) inside_block:withListenerExec


#### Adding Service Accounts

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>

It's possible to add service accounts to the Redpanda container using the `WithNewServiceAccount` option, setting the service account name and its password.
E.g. `WithNewServiceAccount("service-account", "password")`.

#### Adding Super Users

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>

When a super user is needed, you can use the `WithSuperusers` option, passing a variadic list of super users.
E.g. `WithSuperusers("superuser-1", "superuser-2")`.

#### Enabling SASL

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>

The `WithEnableSASL()` option enables SASL scram sha 256 authentication. By default, no authentication (plaintext) is used.
When setting an authentication method, make sure to add users as well and authorize them using the `WithSuperusers()` option.

#### WithEnableKafkaAuthorization

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>

The `WithEnableKafkaAuthorization` enables authorization for connections on the Kafka API.

#### WithEnableWasmTransform

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.28.0"><span class="tc-version">:material-tag: v0.28.0</span></a>

The `WithEnableWasmTransform` enables wasm transform.

!!!warning
    Should not be used with RP versions before 23.3

#### WithEnableSchemaRegistryHTTPBasicAuth

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>

The `WithEnableSchemaRegistryHTTPBasicAuth` enables HTTP basic authentication for the Schema Registry.

#### WithHTTPProxyAuthMethod

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.39.0"><span class="tc-version">:material-tag: v0.39.0</span></a>

The `WithHTTPProxyAuthMethod` sets the authentication method for the HTTP Proxy API (PandaProxy). For HTTP Proxy to have BasicAuth, SASL must be enabled. See `WithEnableSASL()`.

#### WithAutoCreateTopics

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.22.0"><span class="tc-version">:material-tag: v0.22.0</span></a>

The `WithAutoCreateTopics` option enables the auto-creation of topics.

#### WithTLS

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.24.0"><span class="tc-version">:material-tag: v0.24.0</span></a>

The `WithTLS` option enables TLS encryption. It requires a valid PEM encoded certificate and key, passed as byte slices.
E.g. `WithTLS([]byte(cert), []byte(key))`.

#### WithBootstrapConfig

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.33.0"><span class="tc-version">:material-tag: v0.33.0</span></a>

`WithBootstrapConfig` adds an arbitrary config key-value pair to the Redpanda container. Per the name, this config will be interpolated into the generated bootstrap
config file, which is particularly useful for configs requiring a restart when otherwise applied to a running Redpanda instance.
E.g. `WithBootstrapConfig("config_key", config_value)`, where `config_value` is of type `any`.

#### WithAdminAPIAuthentication

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.36.0"><span class="tc-version">:material-tag: v0.36.0</span></a>

Enables Admin API Authentication by setting [`admin_api_require_auth`](https://docs.redpanda.com/current/reference/properties/cluster-properties/#admin_api_require_auth) cluster configuration property to `true`. 
It also configures a bootstrap superuser account via [`RP_BOOTSTRAP_USER`](https://docs.redpanda.com/current/deploy/deployment-option/self-hosted/manual/production/production-deployment/#bootstrap-a-user-account) environment variable.

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The Redpanda container exposes the following methods:

#### KafkaSeedBroker

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>

KafkaSeedBroker returns the seed broker that should be used for connecting
to the Kafka API with your Kafka client. It'll be returned in the format:
"host:port" - for example: "localhost:55687".


[Get Kafka seed broker](../../modules/redpanda/redpanda_test.go) inside_block:kafkaSeedBroker


#### SchemaRegistryAddress

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>

SchemaRegistryAddress returns the address to the schema registry API. This
is an HTTP-based API and thus the returned format will be: http://host:port.


[Get schema registry address](../../modules/redpanda/redpanda_test.go) inside_block:schemaRegistryAddress



#### AdminAPIAddress

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.20.0"><span class="tc-version">:material-tag: v0.20.0</span></a>

AdminAPIAddress returns the address to the Redpanda Admin API. This
is an HTTP-based API and thus the returned format will be: http://host:port.


[Get admin API address](../../modules/redpanda/redpanda_test.go) inside_block:adminAPIAddress


#### HTTPProxyAddress

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.39.0"><span class="tc-version">:material-tag: v0.39.0</span></a>

HTTPProxyAddress returns the address to the HTTP Proxy API (PandaProxy). This
is an HTTP-based API and thus the returned format will be: http://host:port.


[Get HTTP Proxy address](../../modules/redpanda/redpanda_test.go) inside_block:httpProxyAddress

---

### Modules Registry (`docs/modules/registry.md`)

# Registry

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.30.0"><span class="tc-version">:material-tag: v0.30.0</span></a>

## Introduction

The Testcontainers module for Registry.

## Adding this module to your project dependencies

Please run the following command to add the Registry module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/registry
```

## Usage example


[Creating a Registry container](../../modules/registry/examples_test.go) inside_block:runRegistryContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.32.0"><span class="tc-version">:material-tag: v0.32.0</span></a>

!!!info
    The `RunContainer(ctx, opts...)` function is deprecated and will be removed in the next major release of _Testcontainers for Go_.

The Registry module exposes one entrypoint function to create the Registry container, and this function receives three parameters:

```golang
func Run(ctx context.Context, img string, opts ...testcontainers.ContainerCustomizer) (*RegistryContainer, 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(), "registry:2.8.3")`.

### Docker Auth Config

The module exposes a way to set the Docker Auth Config for the Registry container, thanks to the `SetDockerAuthConfig` function.
This is useful when you need to pull images from a private registry. It basically sets the `DOCKER_AUTH_CONFIG` environment variable
with authentication for the given host, username and password sets. It returns a function to reset the environment back to the previous state,
which is helpful when you need to reset the environment after a test.

On the same hand, the module also exposes a way to build a Docker Auth Config for the Registry container, thanks to the `DockerAuthConfig` helper function.
This function returns a map of `AuthConfigs` including base64 encoded Auth field for the provided details.
It also accepts additional host, username and password triples to add more auth configurations.

### Container Options

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

#### With Authentication

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.30.0"><span class="tc-version">:material-tag: v0.30.0</span></a>

It's possible to enable authentication for the Registry container. By default, it is disabled, but you can enable it in two ways:

- You can use `WithHtpasswd` to enable authentication with a string representing the contents of a `htpasswd` file.
A temporary file will be created with the contents of the string and copied to the container.
- You can use `WithHtpasswdFile` to copy a `htpasswd` file from your local filesystem to the container.

In both cases, the `htpasswd` file will be copied into the `/auth` directory inside the container.


[Htpasswd string](../../modules/registry/registry_test.go) inside_block:htpasswdString
[Htpasswd file](../../modules/registry/examples_test.go) inside_block:htpasswdFile


#### WithData

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.30.0"><span class="tc-version">:material-tag: v0.30.0</span></a>

In the case you want to initialise the Registry with your own images, you can use `WithData` to copy a directory from your local filesystem to the container.
The directory will be copied into the `/data` directory inside the container.
The format of the directory should be the same as the one used by the Registry to store images.
Otherwise, the Registry will start but you won't be able to read any images from it.


[Including data](../../modules/registry/examples_test.go) inside_block:htpasswdFile


{% include "../features/common_functional_options_list.md" %}

### Container Methods

The Registry container exposes the following methods:

#### HostAddress

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.33.0"><span class="tc-version">:material-tag: v0.33.0</span></a>

This method returns the host address including port of the Distribution Registry.
E.g. `localhost:32878`.

#### Address

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.30.0"><span class="tc-version">:material-tag: v0.30.0</span></a>

This method returns the HTTP address string to connect to the Distribution Registry, so that you can use to connect to the Registry.
E.g. `http://localhost:32878`.


[HTTP Address](../../modules/registry/registry_test.go) inside_block:httpAddress


#### ImageExists

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.30.0"><span class="tc-version">:material-tag: v0.30.0</span></a>

The `ImageExists` method allows to check if an image exists in the Registry. It receives the Go context and the image reference as parameters.

!!! info
    The image reference should be in the format `my-registry:port/image:tag` in order to be pushed to the Registry.

#### PushImage

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.30.0"><span class="tc-version">:material-tag: v0.30.0</span></a>

The `PushImage` method allows to push an image to the Registry. It receives the Go context and the image reference as parameters.

!!! info
    The image reference should be in the format `my-registry:port/image:tag` in order to be pushed to the Registry.


[Pushing images to the registry](../../modules/registry/examples_test.go) inside_block:pushingImage


If the push operation is successful, the method will internally wait for the image to be available in the Registry, querying the Registry API, returning an error in case of any failure (e.g. pushing or waiting for the image).

#### PullImage

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.39.0"><span class="tc-version">:material-tag: v0.39.0</span></a>

The `PullImage` method allows to pull an image to local Docker daemon.
This method downloads (copies) the specified image reference so it becomes available locally for further operations such as tagging or pushing.
It receives the Go context and the image reference as parameters, pulling the image with the same platform as the registry container's image.

!!! info
    The image reference should be in the format `my-registry:port/image:tag` in order to be pulled from the Registry.


[Pulling images](../../modules/registry/examples_test.go) inside_block:pullingImage


#### TagImage

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.39.0"><span class="tc-version">:material-tag: v0.39.0</span></a>

The `TagImage` method allows to tag an image from the local Registry. It receives the Go context, the image reference and the name of the new tag as parameters.

!!! info
    The image reference should be in the format `my-registry:port/image:tag` in order to be tagged properly.


[Tagging images](../../modules/registry/examples_test.go) inside_block:taggingImage


#### DeleteImage

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.30.0"><span class="tc-version">:material-tag: v0.30.0</span></a>

The `DeleteImage` method allows to delete an image from the Registry. It receives the Go context and the image reference as parameters.

!!! info
    The image reference should be in the format `image:tag` in order to be deleted from the Registry.


[Deleting images from the registry](../../modules/registry/examples_test.go) inside_block:deletingImage

---

### Modules S3mock (`docs/modules/s3mock.md`)

# S3Mock

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

## Introduction

The Testcontainers module for [S3Mock](https://github.com/adobe/S3Mock) — a popular open-source library by Adobe that mocks the AWS S3 API for use in tests. S3Mock runs as a lightweight Docker container and fully implements the S3 API, allowing tests to interact with S3 buckets and objects without real AWS credentials or network access.

## Adding this module to your project dependencies

Please run the following command to add the S3Mock module to your Go dependencies:

```bash
go get github.com/testcontainers/testcontainers-go/modules/s3mock
```

## Usage example


[Creating a S3Mock container](../../modules/s3mock/examples_test.go) inside_block:runS3MockContainer


### Configuring the AWS SDK v2

S3Mock fully implements the AWS S3 API. Point the AWS SDK v2 at the container's `EndpointURL` to use it in tests — no real credentials are required.

First implement a custom `EndpointResolverV2` that routes all S3 calls to the container:


[Endpoint resolver](../../modules/s3mock/s3mock_test.go) inside_block:endpointResolver


Then create the S3 client:


[AWS SDK v2 client setup](../../modules/s3mock/examples_test.go) inside_block:awsClientSetup


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

The S3Mock module exposes one entrypoint function to create the S3Mock container, and this function receives three parameters:

```golang
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(), "adobe/s3mock:3.9")`.

### Container Options

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

#### WithInitialBuckets

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

Use `WithInitialBuckets` to pre-create one or more S3 buckets when the container starts:


[WithInitialBuckets](../../modules/s3mock/s3mock_test.go) inside_block:withInitialBuckets


{% include "../features/common_functional_options_list.md" %}

### Container Methods

#### EndpointURL

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

Returns the HTTP endpoint URL for the S3Mock container (mapped from container port 9090). Use this URL as the base endpoint when configuring the AWS SDK.


[Get HTTP endpoint URL](../../modules/s3mock/s3mock_test.go) inside_block:endpointURL


#### HTTPSEndpointURL

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

Returns the HTTPS endpoint URL for the S3Mock container (mapped from container port 9191).


[Get HTTPS endpoint URL](../../modules/s3mock/s3mock_test.go) inside_block:httpsEndpointURL

---

### Modules Scylladb (`docs/modules/scylladb.md`)

# ScyllaDB

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.36.0"><span class="tc-version">:material-tag: v0.36.0</span></a>

## Introduction

The Testcontainers module for ScyllaDB, a NoSQL database fully compatible with Apache Cassandra and DynamoDB, allows you
to create a ScyllaDB container for testing purposes.

## Adding this module to your project dependencies

Please run the following command to add the ScyllaDB module to your Go dependencies:

```shell
go get github.com/testcontainers/testcontainers-go/modules/scylladb
```

## Usage example


[Creating a ScyllaDB container](../../modules/scylladb/examples_test.go) inside_block:ExampleRun


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.36.0"><span class="tc-version">:material-tag: v0.36.0</span></a>

The ScyllaDB module exposes one entrypoint function to create the ScyllaDB container, and this function receives three parameters:

```golang
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.

!!! info
    By default, we add the `--developer-mode=1` flag to the ScyllaDB container to disable the various checks Scylla
    performs.
    Also in scenarios in which static partitioning is not desired - like mostly-idle cluster without hard latency
    requirements, the `--overprovisioned` command-line option is recommended. This enables certain optimizations for ScyllaDB
    to run efficiently in an overprovisioned environment. You can change it by using the `WithCustomCommand` function.

#### Image

Use the second argument in the `Run` function to set a valid Docker image.
In example:

```golang
scylladb.Run(context.Background(), "scylladb/scylla:6.2.1")
// OR
scylladb.Run(context.Background(), "scylladb/scylla:5.6")
```

### Container Options

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

#### With Database Configuration File (scylla.yaml)

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.36.0"><span class="tc-version">:material-tag: v0.36.0</span></a>

In the case you have a custom config file for ScyllaDB, it's possible to copy that file into the container before it's
started, using the `WithConfig(r io.Reader)` function.


[With Config YAML](../../modules/scylladb/examples_test.go) inside_block:runScyllaDBContainerWithConfig

!!!warning
    You should provide a valid ScyllaDB configuration file as an `io.Reader` when using the function, otherwise the container will fail to
    start. The configuration file should be a valid YAML file and follows
    the [ScyllaDB configuration file](https://github.com/scylladb/scylladb/blob/master/conf/scylla.yaml).

#### With Shard Awareness

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.36.0"><span class="tc-version">:material-tag: v0.36.0</span></a>

If you want to test ScyllaDB with shard awareness, you can use the `WithShardAwareness` function. This function will
configure the ScyllaDB container to use the `19042` port and ask the container to wait until the port is ready.


[With Shard Awareness](../../modules/scylladb/examples_test.go) inside_block:runScyllaDBContainerWithShardAwareness


#### With Alternator (DynamoDB Compatible API)

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.36.0"><span class="tc-version">:material-tag: v0.36.0</span></a>

If you want to test ScyllaDB with the Alternator API, you can use the `WithAlternator` function. This function will
configure the ScyllaDB container to use the port any port you want and ask the container to wait until the port is
ready.
By default, you can choose the port `8000`.


[With Alternator API](../../modules/scylladb/examples_test.go) inside_block:runScyllaDBContainerWithAlternator


#### With Custom Commands

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.36.0"><span class="tc-version">:material-tag: v0.36.0</span></a>

If you need to pass any flag to the ScyllaDB container, you can use the `WithCustomCommand` function. This also rewrites
predefined commands like `--developer-mode=1`. You can check
the [ScyllaDB Docker Best Practices](https://opensource.docs.scylladb.com/stable/operating-scylla/procedures/tips/best-practices-scylla-on-docker.html) for more information.


[With Custom Commands](../../modules/scylladb/examples_test.go) inside_block:runScyllaDBContainerWithCustomCommands


{% include "../features/common_functional_options_list.md" %}

### Container Methods

The ScyllaDB container exposes the following methods:

#### ConnectionHost methods

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.36.0"><span class="tc-version">:material-tag: v0.36.0</span></a>

There exist three methods to get the host and port of the ScyllaDB container, depending on the feature you want.

If you just want to test it with a single node and a single core, you can use the `NonShardAwareConnectionHost` method. However, if you're planning
to use more than one core, you should use the `ShardAwareConnectionHost` method, which uses the **shard-awareness** `19042` port.

Else, if you're planning to use the **Alternator** API, you should use the `AlternatorConnectionHost` method,
which uses the default port `8000`.


[Non-shard-aware connection host](../../modules/scylladb/examples_test.go) inside_block:scyllaDbNonShardAwareConnectionHost
[Shard-aware connection host](../../modules/scylladb/examples_test.go) inside_block:scyllaDbShardAwareConnectionHost
[Alternator host](../../modules/scylladb/examples_test.go) inside_block:scyllaDbAlternatorConnectionHost

---

### Modules Sftp (`docs/modules/sftp.md`)

# SFTP

Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

## Introduction

The Testcontainers module for [SFTP](https://github.com/atmoz/sftp) provides an easy-to-use SFTP server built on OpenSSH. It is ideal for testing file-transfer workflows without connecting to a real remote server.

## Adding this module to your project dependencies

Please run the following command to add the SFTP module to your Go dependencies:

```
go get github.com/testcontainers/testcontainers-go/modules/sftp
```

## Usage example


[Creating a SFTP container](../../modules/sftp/examples_test.go) inside_block:runSFTPContainer


## Module Reference

### Run function

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

!!!info
    The `Run` function requires at least one user to be configured via `WithUser`, otherwise it returns an error.

The SFTP module exposes one entrypoint function to create the SFTP container, and this function receives three parameters:

```golang
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(), "atmoz/sftp:latest", sftp.WithUser("alice", "secret"))`.

### Container Options

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

#### WithUser

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

`WithUser(username, password string)` adds an SFTP user. At least one user is required. Multiple calls accumulate users.

```golang
sftpContainer, err := sftp.Run(ctx, "atmoz/sftp:latest",
    sftp.WithUser("alice", "secret"),
    sftp.WithUser("bob", "password"),
)
```

{% include "../features/common_functional_options_list.md" %}

### Container Methods

The SFTP container exposes the following methods:

#### Address

- Since <a href="https://github.com/testcontainers/testcontainers-go/releases/tag/v0.44.0"><span class="tc-version">:material-tag: v0.44.0</span></a>

`Address(ctx context.Context) (string, error)` returns the `host:port` address of the SFTP server. Use this value directly with an SSH or SFTP client dial call.

```golang
addr, err := sftpContainer.Address(ctx)
// addr is e.g. "localhost:49160"
```

---

--- METRICS ---
- Files Extracted: 104
- Estimated Token Budget: ~125299 tokens
- Canonical Reference: https://codewiki.google/github.com/testcontainers/testcontainers-go