testcontainers::modules::RustFSImage Class Reference

A reusable, copyable description of a RustFS server — an S3-compatible object store — for tests: pinned image, S3 + console ports, managed access/secret credentials, and an HTTP readiness probe. More...

#include <testcontainers/modules/RustFS.hpp>

Public Member Functions
	RustFSImage ()
	A config ready to start(): pinned image, ports 9000 + 9001 exposed, credentials rustfsadmin/rustfsadmin, readiness = HTTP 200 from /health on the S3 port.
RustFSImage &	with_image (const std::string &reference)
	Override the pinned image with a full reference "name[:tag]" (tag defaults to "latest").
RustFSImage &	with_access_key (std::string access_key)
	The S3 access key (RUSTFS_ACCESS_KEY) — what S3 clients send as the access key ID.
RustFSImage &	with_secret_key (std::string secret_key)
	The matching secret key (RUSTFS_SECRET_KEY).
RustFSImage &	with_env (std::string key, std::string value)
	Set an extra environment variable — the image's own knobs (RUSTFS_CONSOLE_ENABLE, RUSTFS_OBS_LOGGER_LEVEL, ...).
RustFSImage &	with_label (std::string key, std::string value)
RustFSImage &	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 and path-style bucket addressing.
RustFSImage &	with_network (const Network &network)
RustFSImage &	with_network_alias (std::string alias)
RustFSImage &	with_reuse (bool reuse=true)
	Enable container reuse (effective only when reuse is also enabled globally — see GenericImage::with_reuse).
RustFSImage &	with_wait (WaitFor wait)
	REPLACE the default readiness probe with a custom strategy (the first call drops the module's /health probe; repeatable — further waits run in order under the same timeout).
RustFSImage &	with_startup_timeout (std::chrono::milliseconds timeout)
	Budget for the readiness phase (default: 60s; cold boots take a few seconds).
RustFSImage &	with_startup_attempts (int n)
	Retry the whole create→start→wait sequence up to n times.
RustFSImage &	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 rustfs flags via with_cmd, ...).
const std::string &	access_key () const noexcept
const std::string &	secret_key () const noexcept
GenericImage	to_generic () const
	Render the full configuration — credential env, readiness probe, customizers — into a plain GenericImage: the drop-down escape hatch when you need a raw core Container instead of a RustFSContainer.
RustFSContainer	start () const
	Create, start, and wait until /health answers 200 on the S3 port.

Static Public Attributes
static constexpr std::string_view	kDefaultImage = "rustfs/rustfs:1.0.0-beta.8"
	The pinned default image.
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 RustFSContainer::s3_url() (the mapped host port) instead.
static constexpr std::uint16_t	kConsolePort = 9001
	The embedded web-console port INSIDE the container (the console is enabled by default; the UI lives under /rustfs/console/).

Detailed Description

A reusable, copyable description of a RustFS server — an S3-compatible object store — for tests: pinned image, S3 + console ports, managed access/secret credentials, and an HTTP readiness probe.

start() runs it and returns a RustFSContainer whose getters hand an S3 client everything it needs; 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

RustFSImage()

testcontainers::modules::RustFSImage::RustFSImage

(

)

A config ready to start(): pinned image, ports 9000 + 9001 exposed, credentials rustfsadmin/rustfsadmin, readiness = HTTP 200 from /health on the S3 port.

The image boots commandless — its entrypoint stores objects in the image-declared /data volume.

Member Function Documentation

with_image()

RustFSImage & testcontainers::modules::RustFSImage::with_image

(

const std::string &

reference

)

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

with_access_key()

RustFSImage & testcontainers::modules::RustFSImage::with_access_key

(

std::string

access_key

)

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

Default "rustfsadmin" (the image default). Empty throws at start(), before any daemon contact; the server itself imposes no documented length rules. Test credentials only: visible via inspect.

with_secret_key()

RustFSImage & testcontainers::modules::RustFSImage::with_secret_key

(

std::string

secret_key

)

The matching secret key (RUSTFS_SECRET_KEY).

Default "rustfsadmin". Empty throws at start().

with_env()

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

Set an extra environment variable — the image's own knobs (RUSTFS_CONSOLE_ENABLE, RUSTFS_OBS_LOGGER_LEVEL, ...).

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.

with_label()

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

with_network() [1/2]

RustFSImage & testcontainers::modules::RustFSImage::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 and path-style bucket addressing.

with_network() [2/2]

RustFSImage & testcontainers::modules::RustFSImage::with_network

(

const Network &

network

)

with_network_alias()

RustFSImage & testcontainers::modules::RustFSImage::with_network_alias

(

std::string

alias

)

with_reuse()

RustFSImage & testcontainers::modules::RustFSImage::with_reuse

(

bool

reuse = true

)

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

An adopted server keeps the buckets and objects in its /data volume.

with_wait()

RustFSImage & testcontainers::modules::RustFSImage::with_wait

(

WaitFor

wait

)

REPLACE the default readiness probe with a custom strategy (the first call drops the module's /health 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()

RustFSImage & testcontainers::modules::RustFSImage::with_startup_timeout

(

std::chrono::milliseconds

timeout

)

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

Image pull time does not count against it.

with_startup_attempts()

RustFSImage & testcontainers::modules::RustFSImage::with_startup_attempts

(

int

n

)

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

with_customizer()

RustFSImage & testcontainers::modules::RustFSImage::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 rustfs 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). Do not set the RUSTFS_* credential env here — it would desync the credential getters; use the typed setters instead.

access_key()

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

inlinenoexcept

secret_key()

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

inlinenoexcept

to_generic()

GenericImage testcontainers::modules::RustFSImage::to_generic

(

)

const

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

Throws Error on an invalid config (an empty access or secret key) before any daemon contact.

start()

RustFSContainer testcontainers::modules::RustFSImage::start

(

)

const

Create, start, and wait until /health answers 200 on the S3 port.

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::RustFSImage::kDefaultImage = "rustfs/rustfs:1.0.0-beta.8"

staticconstexpr

The pinned default image.

RustFS has no stable release line yet, so this is the newest upstream beta — expect the pin to move with upstream until 1.0.0 lands. Override with with_image: another release tag, a -glibc variant, or a mirror; the image must keep the official contract (RUSTFS_* env, /health on the S3 port).

kS3Port

std::uint16_t testcontainers::modules::RustFSImage::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 RustFSContainer::s3_url() (the mapped host port) instead.

kConsolePort

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

staticconstexpr

The embedded web-console port INSIDE the container (the console is enabled by default; the UI lives under /rustfs/console/).