testcontainers::modules::MinIOImage Class Reference

A reusable, copyable description of a MinIO object-storage server — an S3-compatible endpoint for tests: pinned image, S3 + console ports, root credentials, buckets to pre-create, and an HTTP readiness probe. More...

#include <testcontainers/modules/MinIO.hpp>

Public Member Functions
	MinIOImage ()
	A config ready to start(): pinned image, ports 9000 + 9001 exposed, command server /data --console-address :9001, credentials minioadmin/minioadmin, readiness = HTTP 200 from /minio/health/cluster.
MinIOImage &	with_image (const std::string &reference)
	Override the pinned image with a full reference "name[:tag]" (tag defaults to "latest").
MinIOImage &	with_access_key (std::string access_key)
	The root access key (MINIO_ROOT_USER) — what S3 clients send as the access key ID.
MinIOImage &	with_secret_key (std::string secret_key)
	The root secret key (MINIO_ROOT_PASSWORD).
MinIOImage &	with_bucket (std::string name)
	Create a bucket once the server is ready, via the in-image mc client (mc mb --ignore-existing, so a pre-seeded store — say, a custom image with data baked in — is fine).
MinIOImage &	with_env (std::string key, std::string value)
	Set an extra environment variable — the server's MINIO_* knobs (MINIO_REGION, MINIO_BROWSER=off, MINIO_DOMAIN, ...).
MinIOImage &	with_label (std::string key, std::string value)
	Attach a metadata label.
MinIOImage &	with_network (std::string network)
	Join a user-defined network; peers resolve this container by name/alias at http://<alias>:9000 (kS3Port, not the mapped host port), with the same credentials.
MinIOImage &	with_network (const Network &network)
MinIOImage &	with_network_alias (std::string alias)
MinIOImage &	with_reuse (bool reuse=true)
	Enable container reuse (effective only when reuse is also enabled globally — see GenericImage::with_reuse).
MinIOImage &	with_wait (WaitFor wait)
	REPLACE the default readiness probe with a custom strategy (the first call drops the module's /minio/health/cluster probe; repeatable — further waits run in order under the same timeout).
MinIOImage &	with_startup_timeout (std::chrono::milliseconds timeout)
	Budget for the readiness phase (default: 60s; observed cold boots are a few seconds).
MinIOImage &	with_startup_attempts (int n)
	Retry the whole create→start→wait sequence up to n times.
MinIOImage &	with_customizer (std::function< void(GenericImage &)> customize)
	Register a callback that customizes the underlying GenericImage — the channel for options this module does not surface (mounts, pull policy, extra server flags via with_cmd, ...).
const std::string &	access_key () const noexcept
const std::string &	secret_key () const noexcept
const std::vector< std::string > &	buckets () const noexcept
	Buckets queued for creation, in registration order.
GenericImage	to_generic () const
	Render the full configuration — command, credential env, readiness probe, bucket hook + label, customizers — into a plain GenericImage: the drop-down escape hatch when you need a raw core Container instead of a MinIOContainer.
MinIOContainer	start () const
	Create, start, wait until the S3 API reports itself writable, then create any with_bucket buckets.

Static Public Attributes
static constexpr std::string_view	kDefaultImage = "minio/minio:RELEASE.2025-09-07T16-13-09Z"
	The pinned default image — the final community release published to Docker Hub (upstream stopped publishing images in late 2025, so the tag is frozen; a -cpuv1 twin exists for old x86-64 CPUs).
static constexpr std::uint16_t	kS3Port = 9000
	The S3 API port INSIDE the container: peers on a shared docker network use http://<alias-or-name>:kS3Port; the test process itself uses MinIOContainer::s3_url() (the mapped host port) instead.
static constexpr std::uint16_t	kConsolePort = 9001
	The web-console port INSIDE the container — fixed by the module's --console-address :9001 (the server would otherwise pick a random port every boot, which could not be exposed).

Detailed Description

A reusable, copyable description of a MinIO object-storage server — an S3-compatible endpoint for tests: pinned image, S3 + console ports, root credentials, buckets to pre-create, and an HTTP readiness probe.

start() runs it and returns a MinIOContainer whose getters hand an S3 client everything it needs (endpoint URL, access/secret key); no client SDK is required or linked.

The with_* builders mutate in place and return *this, so a named config can be configured incrementally and started many times. Core options the module does not surface are reached through with_customizer; to_generic() drops down to a plain GenericImage entirely.

Constructor & Destructor Documentation

MinIOImage()

testcontainers::modules::MinIOImage::MinIOImage

(

)

A config ready to start(): pinned image, ports 9000 + 9001 exposed, command server /data --console-address :9001, credentials minioadmin/minioadmin, readiness = HTTP 200 from /minio/health/cluster.

Member Function Documentation

with_image()

MinIOImage & testcontainers::modules::MinIOImage::with_image

(

const std::string &

reference

)

Override the pinned image with a full reference "name[:tag]" (tag defaults to "latest").

The module keeps its command, so the image must understand server /data --console-address :9001.

with_access_key()

MinIOImage & testcontainers::modules::MinIOImage::with_access_key

(

std::string

access_key

)

The root access key (MINIO_ROOT_USER) — what S3 clients send as the access key ID.

Default "minioadmin" (the image default). The server requires at least 3 characters — shorter throws at start(), before any daemon contact (the server's own failure mode is a fatal exit followed by the full startup timeout). Test credentials only: the value is visible via inspect.

with_secret_key()

MinIOImage & testcontainers::modules::MinIOImage::with_secret_key

(

std::string

secret_key

)

The root secret key (MINIO_ROOT_PASSWORD).

Default "minioadmin". The server requires at least 8 characters — shorter throws at start().

with_bucket()

MinIOImage & testcontainers::modules::MinIOImage::with_bucket

(

std::string

name

)

Create a bucket once the server is ready, via the in-image mc client (mc mb --ignore-existing, so a pre-seeded store — say, a custom image with data baked in — is fine).

Repeatable; an empty name throws at start(); a failed creation fails start(). The hook first points the container's own mc config at the server under the alias tc — execs against container() can use paths like tc/<bucket> afterwards. The bucket list also renders into a label, so container reuse sees it: a changed list builds a fresh container (hooks do not re-run on an adopted one).

with_env()

MinIOImage & testcontainers::modules::MinIOImage::with_env	(	std::string	key,
		std::string	value )

Set an extra environment variable — the server's MINIO_* knobs (MINIO_REGION, MINIO_BROWSER=off, MINIO_DOMAIN, ...).

The credential pair belongs to with_access_key/with_secret_key: the module appends those env keys last, so they win over raw duplicates set here. The legacy MINIO_ACCESS_KEY / MINIO_SECRET_KEY spellings are ignored by the pinned server — use the typed setters.

with_label()

MinIOImage & testcontainers::modules::MinIOImage::with_label	(	std::string	key,
		std::string	value )

Attach a metadata label.

The module's reuse-visibility label (org.testcontainers.minio.buckets) is applied after these, so it wins on a duplicate key.

with_network() [1/2]

MinIOImage & testcontainers::modules::MinIOImage::with_network

(

std::string

network

)

Join a user-defined network; peers resolve this container by name/alias at http://<alias>:9000 (kS3Port, not the mapped host port), with the same credentials.

Mind that presigned URLs embed the endpoint they were generated against — generate them against the address their consumer will dial.

with_network() [2/2]

MinIOImage & testcontainers::modules::MinIOImage::with_network

(

const Network &

network

)

with_network_alias()

MinIOImage & testcontainers::modules::MinIOImage::with_network_alias

(

std::string

alias

)

with_reuse()

MinIOImage & testcontainers::modules::MinIOImage::with_reuse

(

bool

reuse = true

)

Enable container reuse (effective only when reuse is also enabled globally — see GenericImage::with_reuse).

An adopted server keeps its object store; the with_bucket list participates in the reuse match via the label, so a changed list builds a fresh container.

with_wait()

MinIOImage & testcontainers::modules::MinIOImage::with_wait

(

WaitFor

wait

)

REPLACE the default readiness probe with a custom strategy (the first call drops the module's /minio/health/cluster probe; repeatable — further waits run in order under the same timeout).

The escape for TLS setups: the default probe speaks plain HTTP only.

with_startup_timeout()

MinIOImage & testcontainers::modules::MinIOImage::with_startup_timeout

(

std::chrono::milliseconds

timeout

)

Budget for the readiness phase (default: 60s; observed cold boots are a few seconds).

Image pull time does not count against it.

with_startup_attempts()

MinIOImage & testcontainers::modules::MinIOImage::with_startup_attempts

(

int

n

)

Retry the whole create→start→wait sequence up to n times.

with_customizer()

MinIOImage & testcontainers::modules::MinIOImage::with_customizer

(

std::function< void(GenericImage &)>

customize

)

Register a callback that customizes the underlying GenericImage — the channel for options this module does not surface (mounts, pull policy, extra server flags via with_cmd, ...).

Customizers run when the config is rendered (start() / to_generic()), in registration order, AFTER the module's own rendering — what they set wins. A wait added here runs IN ADDITION to the default probe (unlike with_wait, which replaces it). Two caveats: replacing the command drops the fixed console address (console_url() then points at nothing), and setting the MINIO_ROOT_* env here desyncs the credential getters and the bucket hook — use the typed setters instead.

access_key()

const std::string & testcontainers::modules::MinIOImage::access_key ( ) const

inlinenoexcept

secret_key()

const std::string & testcontainers::modules::MinIOImage::secret_key ( ) const

inlinenoexcept

buckets()

const std::vector< std::string > & testcontainers::modules::MinIOImage::buckets ( ) const

inlinenoexcept

Buckets queued for creation, in registration order.

to_generic()

GenericImage testcontainers::modules::MinIOImage::to_generic

(

)

const

Render the full configuration — command, credential env, readiness probe, bucket hook + label, customizers — into a plain GenericImage: the drop-down escape hatch when you need a raw core Container instead of a MinIOContainer.

Throws Error on an invalid config (access key shorter than 3 characters, secret key shorter than 8, an empty bucket name) before any daemon contact.

start()

MinIOContainer testcontainers::modules::MinIOImage::start

(

)

const

Create, start, wait until the S3 API reports itself writable, then create any with_bucket buckets.

Throws Error on config errors before touching the daemon; DockerError / StartupTimeoutError from the run itself, like GenericImage::start().

Member Data Documentation

kDefaultImage

std::string_view testcontainers::modules::MinIOImage::kDefaultImage = "minio/minio:RELEASE.2025-09-07T16-13-09Z"

staticconstexpr

The pinned default image — the final community release published to Docker Hub (upstream stopped publishing images in late 2025, so the tag is frozen; a -cpuv1 twin exists for old x86-64 CPUs).

Override with with_image; any image that keeps the MinIO contract (MINIO_ROOT_* env, the server command, mc on PATH for with_bucket) works.

kS3Port

std::uint16_t testcontainers::modules::MinIOImage::kS3Port = 9000

staticconstexpr

The S3 API port INSIDE the container: peers on a shared docker network use http://<alias-or-name>:kS3Port; the test process itself uses MinIOContainer::s3_url() (the mapped host port) instead.

kConsolePort

std::uint16_t testcontainers::modules::MinIOImage::kConsolePort = 9001

staticconstexpr

The web-console port INSIDE the container — fixed by the module's --console-address :9001 (the server would otherwise pick a random port every boot, which could not be exposed).