# 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.
```text
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](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:
```rust,no_run
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](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:
```text
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](https://github.com/napbat/testcontainers-build/blob/main/LICENSE).