testcontainers::Volume Class Reference

A RAII handle to a named Docker volume. More...

#include <testcontainers/Volume.hpp>

Classes
class	Builder
	A copyable builder for a richer named volume: driver, driver options, and labels. More...

Public Member Functions
	Volume (const Volume &)=delete
Volume &	operator= (const Volume &)=delete
	Volume (Volume &&other) noexcept
Volume &	operator= (Volume &&other) noexcept
	~Volume ()
	Removes the volume unless it was already explicitly removed or moved-from.
const std::string &	name () const noexcept
	The volume's name (used to mount it into a container).
void	remove ()
	Explicitly remove the volume now.
VolumeInspect	inspect () const
	GET /volumes/{name} — the volume's current driver, mountpoint, scope, labels, and options.
void	populate (const std::vector< CopyToContainer > &sources, const std::string &mount_path={}, const std::string &helper_image={}) const
	Seed data into the volume by copying sources into it via a throwaway helper container that has this volume mounted at mount_path.

Static Public Member Functions
static Builder	builder ()
	Start a builder for a richer volume (driver, driver options, labels).
static Volume	create (std::string name)
	Create a volume with the given name.
static Volume	create ()
	Create a volume with a generated unique name (tc-<random hex>).

Detailed Description

A RAII handle to a named Docker volume.

Move-only: it owns a real external resource and removes the volume on destruction (best-effort, exceptions swallowed). Copying is deleted so the removal happens exactly once. Mount it into a container with Mount::volume(v.name(), target), or seed it with populate().

Constructor & Destructor Documentation

Volume() [1/2]

testcontainers::Volume::Volume ( const Volume & )

delete

Volume() [2/2]

testcontainers::Volume::Volume ( Volume && other )

inlinenoexcept

~Volume()

testcontainers::Volume::~Volume ( )

inline

Removes the volume unless it was already explicitly removed or moved-from.

Never throws.

Member Function Documentation

builder()

Builder testcontainers::Volume::builder ( )

inlinestatic

Start a builder for a richer volume (driver, driver options, labels).

operator=() [1/2]

Volume & testcontainers::Volume::operator= ( const Volume & )

delete

operator=() [2/2]

Volume & testcontainers::Volume::operator= ( Volume && other )

inlinenoexcept

create() [1/2]

Volume testcontainers::Volume::create ( std::string name )

static

Create a volume with the given name.

create() [2/2]

Volume testcontainers::Volume::create ( )

static

Create a volume with a generated unique name (tc-<random hex>).

name()

const std::string & testcontainers::Volume::name ( ) const

inlinenoexcept

The volume's name (used to mount it into a container).

remove()

void testcontainers::Volume::remove

(

)

Explicitly remove the volume now.

Idempotent; after this the destructor does nothing.

inspect()

VolumeInspect testcontainers::Volume::inspect

(

)

const

GET /volumes/{name} — the volume's current driver, mountpoint, scope, labels, and options.

Throws DockerError if the volume is gone.

populate()

void testcontainers::Volume::populate	(	const std::vector< CopyToContainer > &	sources,
		const std::string &	mount_path = {},
		const std::string &	helper_image = {} ) const

Seed data into the volume by copying sources into it via a throwaway helper container that has this volume mounted at mount_path.

Each source's target (absolute POSIX-style "/x", also toward Windows daemons — anything else throws) is rebased so it lands at that path within the volume: a source targeting "/seed.txt" is readable as "seed.txt" right under wherever the volume is mounted next. The helper carries the testcontainers session labels (so it is reaped if we crash mid-seed) and is always force-removed afterwards; the volume persists.

Empty mount_path / helper_image resolve per daemon OS: Linux "/__tc_seed" + "alpine:3.20", Windows "C:/__tc_seed" + "mcr.microsoft.com/windows/nanoserver:ltsc2022".

Linux daemons copy straight through the mount. A Windows daemon extracts archive uploads into the container's LAYER, never through mounts (docker cp shares the blind spot), so there the seed is staged into the created (not yet started) helper's layer and an in-container xcopy (run as ContainerAdministrator — the volume directory's ACL denies nanoserver's default user) moves it onto the volume; file-source MODES apply on Linux only. Windows helpers run under the daemon's default isolation — pass a build-matched helper_image (e.g. nanoserver:ltsc2025 on a 26100 host) where that default is process isolation.