testcontainers-build
Build local Docker images from folders, HTTP(S) contexts, or Git repositories. Use fluent requests and native Testcontainers containers.
Run an example
Docker CLI with buildx and a running Linux container engine are required. Git
sources also need Git on PATH. Use the same daemon for Docker CLI and Testcontainers.
cargo run -p testcontainers-build --example local
cargo run -p testcontainers-build --example remote
cargo run -p testcontainers-build --example git-source
The examples build an image, start a container, wait for readiness, check files, and remove resources. They use a nested Dockerfile, build arguments, a target stage, and a timeout. The local example disables the layer cache. The remote example serves a filtered tar archive from a temporary HTTP container. The Git example builds a pinned commit and selects a checkout subdirectory.
The shared context is in examples/context. Set
TESTCONTAINERS_BUILD_HTTP_HOST when the builder needs another address to reach
the temporary HTTP server. Pass an archive URI after --example remote --, or a
repository, revision, and optional subdirectory after --example git-source --.
External inputs must follow the sample contract; adapt its checks for your service.
Fluent API
Add this library, testcontainers = "0.28", and Tokio to your application.
Replace ./service with your Docker build context:
use AsyncRunner;
use ;
async
Configuration methods consume and return the request. Use with_dockerfile,
with_build_argument, with_target, with_platform, with_no_cache, and
with_timeout to set individual options. with_options replaces all options.
Validation runs before source resolution. The default timeout is ten minutes
and includes the build. The direct ImageBuilder::build(&source, &options) API
accepts borrowed inputs.
Use RemoteUriSource::new(uri)? for HTTP(S), or
GitSource::new(GitRequest::new(repository).with_revision(commit)) for Git.
Add with_subdirectory to select a checkout folder. Use a full commit ID for
repeatable builds.
Ownership and source behavior
Remove containers before their image, and call image.remove().await on success
and error paths. Drop does not remove images. Testcontainers can attempt a
registry pull if the local image is missing. See
examples/common/image.rs for full checks and cleanup.
Folder and Git contexts use Docker's ignore rules. HTTP(S) contexts must be tar
archives or plain Dockerfiles. Docker downloads them from the builder's network.
Filter archives before creation: Docker does not apply their .dockerignore.
ZIP is not supported. A plain remote Dockerfile has no local files for COPY.
The default Git provider does not explicitly initialize submodules or manage Git LFS. Use a custom provider for those steps. Dropping a process future requests termination; it does not guarantee all descendants stop.
Extension points and layout
Implement BuildContextProvider to add a source, GitProvider to change checkout
behavior, or ImageBuildBackend to change image build execution.
BuildContext::with_owner holds temporary resources until the build ends.
The package uses Cargo's src, tests, and examples conventions. Targets with
support modules use name/main.rs. It inherits the workspace's Rust, Clippy,
and rustdoc lints. Check all targets with:
cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace
cargo doc --workspace --no-deps
cargo test --workspace --test docker -- --ignored
The last command requires Docker. Repository integration tests use shared workspace fixtures and are not included in the package archive. The runnable examples and their context are included.
License
This crate uses the MIT license.