testcontainers-build 0.1.0

Build Testcontainers images from folders, remote contexts, and pluggable Git providers
Documentation

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 testcontainers::runners::AsyncRunner;
use testcontainers_build::{FolderSource, ImageBuilder};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut image = ImageBuilder::default()
        .with_source(FolderSource::new("./service"))
        .with_build_argument("VERSION", "1.0")
        .build()
        .await?;

    let result = async {
        let container = image.container_request().start().await?;
        // Use the container here. Add service checks with cleanup on error paths.
        container.rm().await
    }
    .await;

    // Attempt image cleanup even when the container operation failed.
    let cleanup = image.remove().await;
    result?;
    cleanup?;
    Ok(())
}

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.