Crate docker_wrapper 

docker-wrapper

A type-safe Docker CLI wrapper for Rust.

This crate provides an idiomatic Rust interface to the Docker command-line tool. All commands use a builder pattern and async execution via Tokio.

Quick Start

use docker_wrapper::{DockerCommand, RunCommand, StopCommand, RmCommand};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Run a container
    let container = RunCommand::new("nginx:alpine")
        .name("my-nginx")
        .port(8080, 80)
        .detach()
        .execute()
        .await?;

    println!("Started: {}", container.short());

    // Stop and remove
    StopCommand::new("my-nginx").execute().await?;
    RmCommand::new("my-nginx").execute().await?;

    Ok(())
}

Core Concepts

The DockerCommand Trait

All commands implement DockerCommand, which provides the execute() method. You must import this trait to call .execute():

use docker_wrapper::DockerCommand; // Required for .execute()

Builder Pattern

Commands are configured using method chaining:

RunCommand::new("alpine")
    .name("my-container")
    .env("DATABASE_URL", "postgres://localhost/db")
    .volume("/data", "/app/data")
    .port(3000, 3000)
    .memory("512m")
    .cpus("0.5")
    .detach()
    .rm()  // Auto-remove when stopped
    .execute()
    .await?;

Error Handling

All commands return Result<T, docker_wrapper::Error>:

match RunCommand::new("nginx").detach().execute().await {
    Ok(id) => println!("Started: {}", id.short()),
    Err(Error::CommandFailed { stderr, .. }) => {
        eprintln!("Docker error: {}", stderr);
    }
    Err(e) => eprintln!("Error: {}", e),
}

Command Categories

Container Lifecycle

use docker_wrapper::{
    DockerCommand,
    RunCommand,      // docker run
    CreateCommand,   // docker create
    StartCommand,    // docker start
    StopCommand,     // docker stop
    RestartCommand,  // docker restart
    KillCommand,     // docker kill
    RmCommand,       // docker rm
    PauseCommand,    // docker pause
    UnpauseCommand,  // docker unpause
};

Container Inspection

use docker_wrapper::{
    DockerCommand,
    PsCommand,       // docker ps
    LogsCommand,     // docker logs
    InspectCommand,  // docker inspect
    TopCommand,      // docker top
    StatsCommand,    // docker stats
    PortCommand,     // docker port
    DiffCommand,     // docker diff
};

Container Operations

use docker_wrapper::{
    DockerCommand,
    ExecCommand,     // docker exec
    AttachCommand,   // docker attach
    CpCommand,       // docker cp
    WaitCommand,     // docker wait
    RenameCommand,   // docker rename
    UpdateCommand,   // docker update
    CommitCommand,   // docker commit
    ExportCommand,   // docker export
};

Images

use docker_wrapper::{
    DockerCommand,
    ImagesCommand,   // docker images
    PullCommand,     // docker pull
    PushCommand,     // docker push
    BuildCommand,    // docker build
    TagCommand,      // docker tag
    RmiCommand,      // docker rmi
    SaveCommand,     // docker save
    LoadCommand,     // docker load
    ImportCommand,   // docker import
    HistoryCommand,  // docker history
    SearchCommand,   // docker search
};

Networks and Volumes

use docker_wrapper::{
    DockerCommand,
    NetworkCreateCommand, NetworkLsCommand, NetworkRmCommand,
    VolumeCreateCommand, VolumeLsCommand, VolumeRmCommand,
};

System

use docker_wrapper::{
    DockerCommand,
    VersionCommand,  // docker version
    InfoCommand,     // docker info
    EventsCommand,   // docker events
    LoginCommand,    // docker login
    LogoutCommand,   // docker logout
    SystemDfCommand, // docker system df
    SystemPruneCommand, // docker system prune
};

Feature Flags

compose - Docker Compose Support

docker-wrapper = { version = "0.10", features = ["compose"] }

use docker_wrapper::{DockerCommand, compose::{ComposeUpCommand, ComposeDownCommand, ComposeCommand}};

// Start services
ComposeUpCommand::new()
    .file("docker-compose.yml")
    .detach()
    .execute()
    .await?;

// Stop and clean up
ComposeDownCommand::new()
    .volumes()
    .execute()
    .await?;

templates - Pre-configured Containers

docker-wrapper = { version = "0.10", features = ["templates"] }

Templates provide ready-to-use configurations for common services:

use docker_wrapper::{RedisTemplate, Template};

let redis = RedisTemplate::new("my-redis")
    .port(6379)
    .password("secret")
    .with_persistence("redis-data");

let id = redis.start().await?;
// ... use Redis ...
redis.stop().await?;

Available templates:

• RedisTemplate, RedisSentinelTemplate, RedisClusterTemplate
• PostgresTemplate, MysqlTemplate, MongodbTemplate
• NginxTemplate

swarm - Docker Swarm Commands

docker-wrapper = { version = "0.10", features = ["swarm"] }

manifest - Multi-arch Manifest Commands

docker-wrapper = { version = "0.10", features = ["manifest"] }

Tracing and Debugging

docker-wrapper integrates with the tracing ecosystem to provide comprehensive observability into Docker command execution.

Enabling Tracing

Add tracing dependencies to your project:

[dependencies]
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }

Initialize a subscriber in your application:

use tracing_subscriber::EnvFilter;

tracing_subscriber::fmt()
    .with_env_filter(EnvFilter::from_default_env())
    .init();

// Your application code...

Log Levels

Control verbosity with the RUST_LOG environment variable:

# Show all docker-wrapper traces
RUST_LOG=docker_wrapper=trace cargo run

# Show only command execution info
RUST_LOG=docker_wrapper::command=debug cargo run

# Show template lifecycle events
RUST_LOG=docker_wrapper::template=debug cargo run

# Show retry/debug executor activity
RUST_LOG=docker_wrapper::debug=trace cargo run

What Gets Traced

The library instruments key operations at various levels:

• trace: Command arguments, stdout/stderr output, retry delays
• debug: Command start/completion, health check attempts, retry attempts
• info: Container lifecycle events (start, stop, ready)
• warn: Health check failures, retry exhaustion warnings
• error: Command failures, timeout errors

Instrumented Operations

Command Execution

All Docker commands are traced with:

• Command name and runtime (docker/podman)
• Timeout configuration
• Exit status and duration
• Stdout/stderr output (at trace level)

Template Lifecycle

Template operations include:

• Container start with image and configuration
• Health check polling with attempt counts
• Ready state transitions
• Stop and remove operations

Retry Logic

The debug executor traces:

• Retry policy configuration
• Individual retry attempts with delays
• Backoff calculations
• Final success or exhaustion

Example Output

With RUST_LOG=docker_wrapper=debug:

DEBUG docker.command{command="run" runtime="docker"}: starting command
DEBUG docker.command{command="run"}: command completed exit_code=0
INFO  template.start{name="my-redis" image="redis:7-alpine"}: container started
DEBUG template.wait{name="my-redis"}: health check attempt=1 elapsed_ms=50
INFO  template.wait{name="my-redis"}: container ready after 1 attempts

Streaming Output

For long-running commands, stream output in real-time:

use docker_wrapper::{BuildCommand, StreamHandler, StreamableCommand};

let result = BuildCommand::new(".")
    .tag("my-app:latest")
    .stream(StreamHandler::print())
    .await?;

if result.is_success() {
    println!("Build complete!");
}

Checking Docker Availability

use docker_wrapper::ensure_docker;

let info = ensure_docker().await?;
println!("Docker {}.{}.{}", info.version.major, info.version.minor, info.version.patch);

Why docker-wrapper?

This crate wraps the Docker CLI rather than calling the Docker API directly (like bollard).

docker-wrapper advantages:

• Just needs docker in PATH (no socket access required)
• Native docker compose support
• Works with Docker, Podman, Colima, and other Docker-compatible CLIs
• Familiar mental model if you know Docker CLI

bollard advantages:

• Direct API calls (no process spawn overhead)
• Lower latency for high-frequency operations
• No external binary dependency

Choose docker-wrapper for CLI tools, dev tooling, Compose workflows, or when working with Docker alternatives.

Choose bollard for high-performance services with many Docker operations.

Re-exports

pub use stream::OutputLine;

pub use stream::StreamHandler;

pub use stream::StreamResult;

pub use stream::StreamableCommand;

pub use command::attach::AttachCommand;

pub use command::attach::AttachResult;

pub use command::bake::BakeCommand;

pub use command::build::BuildCommand;

pub use command::build::BuildOutput;

pub use command::builder::BuilderBuildCommand;

pub use command::builder::BuilderInfo;

pub use command::builder::BuilderPruneCommand;

pub use command::builder::BuilderPruneResult;

pub use command::builder::BuildxCreateCommand;

pub use command::builder::BuildxCreateResult;

pub use command::builder::BuildxInspectCommand;

pub use command::builder::BuildxInspectResult;

pub use command::builder::BuildxLsCommand;

pub use command::builder::BuildxLsResult;

pub use command::builder::BuildxRmCommand;

pub use command::builder::BuildxRmResult;

pub use command::builder::BuildxStopCommand;

pub use command::builder::BuildxStopResult;

pub use command::builder::BuildxUseCommand;

pub use command::builder::BuildxUseResult;

pub use command::commit::CommitCommand;

pub use command::commit::CommitResult;

pub use command::container_prune::ContainerPruneCommand;

pub use command::container_prune::ContainerPruneResult;

pub use command::context::ContextCreateCommand;

pub use command::context::ContextInfo;

pub use command::context::ContextInspectCommand;

pub use command::context::ContextLsCommand;

pub use command::context::ContextRmCommand;

pub use command::context::ContextUpdateCommand;

pub use command::context::ContextUseCommand;

pub use command::cp::CpCommand;

pub use command::cp::CpResult;

pub use command::create::CreateCommand;

pub use command::create::CreateResult;

pub use command::diff::DiffCommand;

pub use command::diff::DiffResult;

pub use command::diff::FilesystemChange;

pub use command::diff::FilesystemChangeType;

pub use command::events::DockerEvent;

pub use command::events::EventActor;

pub use command::events::EventsCommand;

pub use command::events::EventsResult;

pub use command::exec::ExecCommand;

pub use command::exec::ExecOutput;

pub use command::export::ExportCommand;

pub use command::export::ExportResult;

pub use command::generic::GenericCommand;

pub use command::history::HistoryCommand;

pub use command::history::HistoryResult;

pub use command::history::ImageLayer;

pub use command::image_prune::DeletedImage;

pub use command::image_prune::ImagePruneCommand;

pub use command::image_prune::ImagePruneResult;

pub use command::images::ImageInfo;

pub use command::images::ImagesCommand;

pub use command::images::ImagesOutput;

pub use command::import::ImportCommand;

pub use command::import::ImportResult;

pub use command::info::DockerInfo as SystemDockerInfo;

pub use command::info::InfoCommand;

pub use command::info::InfoOutput;

pub use command::info::SystemInfo;

pub use command::init::InitCommand;

pub use command::init::InitOutput;

pub use command::init::InitTemplate;

pub use command::inspect::InspectCommand;

pub use command::inspect::InspectOutput;

pub use command::kill::KillCommand;

pub use command::kill::KillResult;

pub use command::load::LoadCommand;

pub use command::load::LoadResult;

pub use command::login::LoginCommand;

pub use command::login::LoginOutput;

pub use command::logout::LogoutCommand;

pub use command::logout::LogoutOutput;

pub use command::logs::LogsCommand;

pub use command::network::NetworkConnectCommand;

pub use command::network::NetworkConnectResult;

pub use command::network::NetworkCreateCommand;

pub use command::network::NetworkCreateResult;

pub use command::network::NetworkDisconnectCommand;

pub use command::network::NetworkDisconnectResult;

pub use command::network::NetworkInfo;

pub use command::network::NetworkInspectCommand;

pub use command::network::NetworkInspectOutput;

pub use command::network::NetworkLsCommand;

pub use command::network::NetworkLsOutput;

pub use command::network::NetworkPruneCommand;

pub use command::network::NetworkPruneResult;

pub use command::network::NetworkRmCommand;

pub use command::network::NetworkRmResult;

pub use command::pause::PauseCommand;

pub use command::pause::PauseResult;

pub use command::port::PortCommand;

pub use command::port::PortMapping as PortMappingInfo;

pub use command::port::PortResult;

pub use command::ps::ContainerInfo;

pub use command::ps::PsCommand;

pub use command::ps::PsFormat;

pub use command::ps::PsOutput;

pub use command::pull::PullCommand;

pub use command::push::PushCommand;

pub use command::rename::RenameCommand;

pub use command::rename::RenameResult;

pub use command::restart::RestartCommand;

pub use command::restart::RestartResult;

pub use command::rm::RmCommand;

pub use command::rm::RmResult;

pub use command::rmi::RmiCommand;

pub use command::rmi::RmiResult;

pub use command::run::ContainerId;

pub use command::run::MountType;

pub use command::run::RunCommand;

pub use command::run::VolumeMount;

pub use command::save::SaveCommand;

pub use command::save::SaveResult;

pub use command::search::RepositoryInfo;

pub use command::search::SearchCommand;

pub use command::search::SearchOutput;

pub use command::start::StartCommand;

pub use command::start::StartResult;

pub use command::stats::ContainerStats;

pub use command::stats::StatsCommand;

pub use command::stats::StatsResult;

pub use command::stop::StopCommand;

pub use command::stop::StopResult;

pub use command::system::BuildCacheInfo;

pub use command::system::BuildCacheUsage;

pub use command::system::ContainerInfo as SystemContainerInfo;

pub use command::system::ContainerUsage;

pub use command::system::DiskUsage;

pub use command::system::ImageInfo as SystemImageInfo;

pub use command::system::ImageUsage;

pub use command::system::PruneResult;

pub use command::system::SystemDfCommand;

pub use command::system::SystemPruneCommand;

pub use command::system::VolumeInfo as SystemVolumeInfo;

pub use command::system::VolumeUsage;

pub use command::tag::TagCommand;

pub use command::tag::TagResult;

pub use command::top::ContainerProcess;

pub use command::top::TopCommand;

pub use command::top::TopResult;

pub use command::unpause::UnpauseCommand;

pub use command::unpause::UnpauseResult;

pub use command::update::UpdateCommand;

pub use command::update::UpdateResult;

pub use command::version::ClientVersion;

pub use command::version::ServerVersion;

pub use command::version::VersionCommand;

pub use command::version::VersionInfo;

pub use command::version::VersionOutput;

pub use command::volume::VolumeCreateCommand;

pub use command::volume::VolumeCreateResult;

pub use command::volume::VolumeInfo;

pub use command::volume::VolumeInspectCommand;

pub use command::volume::VolumeInspectOutput;

pub use command::volume::VolumeLsCommand;

pub use command::volume::VolumeLsOutput;

pub use command::volume::VolumePruneCommand;

pub use command::volume::VolumePruneResult;

pub use command::volume::VolumeRmCommand;

pub use command::volume::VolumeRmResult;

pub use command::wait::WaitCommand;

pub use command::wait::WaitResult;

pub use command::CommandExecutor;

pub use command::CommandOutput;

pub use command::DockerCommand;

pub use command::EnvironmentBuilder;

pub use command::PortBuilder;

pub use command::PortMapping;

pub use command::Protocol;

pub use command::DEFAULT_COMMAND_TIMEOUT;

pub use debug::BackoffStrategy;

pub use debug::DebugConfig;

pub use debug::DebugExecutor;

pub use debug::DryRunPreview;

pub use debug::RetryPolicy;

pub use error::Error;

pub use error::Result;

pub use platform::Platform;

pub use platform::PlatformInfo;

pub use platform::Runtime;

pub use command::swarm::SwarmCaCommand;

pub use command::swarm::SwarmCaResult;

pub use command::swarm::SwarmInitCommand;

pub use command::swarm::SwarmInitResult;

pub use command::swarm::SwarmJoinCommand;

pub use command::swarm::SwarmJoinResult;

pub use command::swarm::SwarmJoinTokenCommand;

pub use command::swarm::SwarmJoinTokenResult;

pub use command::swarm::SwarmLeaveCommand;

pub use command::swarm::SwarmLeaveResult;

pub use command::swarm::SwarmNodeRole;

pub use command::swarm::SwarmUnlockCommand;

pub use command::swarm::SwarmUnlockKeyCommand;

pub use command::swarm::SwarmUnlockKeyResult;

pub use command::swarm::SwarmUnlockResult;

pub use command::swarm::SwarmUpdateCommand;

pub use command::swarm::SwarmUpdateResult;

pub use command::manifest::ManifestAnnotateCommand;

pub use command::manifest::ManifestAnnotateResult;

pub use command::manifest::ManifestCreateCommand;

pub use command::manifest::ManifestCreateResult;

pub use command::manifest::ManifestInfo;

pub use command::manifest::ManifestInspectCommand;

pub use command::manifest::ManifestPlatform;

pub use command::manifest::ManifestPushCommand;

pub use command::manifest::ManifestPushResult;

pub use command::manifest::ManifestRmCommand;

pub use command::manifest::ManifestRmResult;

pub use prerequisites::ensure_docker;

pub use prerequisites::ensure_docker_with_timeout;

pub use prerequisites::DockerInfo;

pub use prerequisites::DockerPrerequisites;

pub use prerequisites::DEFAULT_PREREQ_TIMEOUT;

pub use template::Template;

pub use template::TemplateBuilder;

pub use template::TemplateConfig;

pub use template::TemplateError;

pub use template::redis::RedisInsightTemplate;

pub use template::redis::RedisTemplate;

pub use template::redis::RedisSentinelTemplate;

pub use template::redis::SentinelConnectionInfo;

pub use template::redis::SentinelInfo;

pub use template::redis::ClusterInfo;

pub use template::redis::NodeInfo;

pub use template::redis::NodeRole;

pub use template::redis::RedisClusterConnection;

pub use template::redis::RedisClusterTemplate;

pub use template::redis::RedisEnterpriseConnectionInfo;

pub use template::redis::RedisEnterpriseTemplate;

pub use template::database::PostgresConnectionString;

pub use template::database::PostgresTemplate;

pub use template::database::MysqlConnectionString;

pub use template::database::MysqlTemplate;

pub use template::database::MongodbConnectionString;

pub use template::database::MongodbTemplate;

pub use template::web::NginxTemplate;

Modules

command

Docker command implementations.

compose

Docker Compose command implementations.

debug

Debugging and reliability features for Docker commands.

error

Error types for docker-wrapper.

platform

Platform detection and runtime abstraction for Docker environments.

prerequisites

Prerequisites module for Docker detection and validation.

stream

Streaming support for Docker command output.

template

Container templates module

testing

Testing Utilities

Constants

VERSION

The version of this crate