Bollard leverages the latest Hyper and Tokio improvements for an asynchronous API containing futures, streams and the async/await paradigm.
The library also features Windows support through Named Pipes and HTTPS support through optional SSL bindings or a native TLS implementation.
Add the following to your Cargo.toml file
nocompile
[dependencies]
bollard = "0.4"
The Docker API is pegged at version 1.40
Connect to the docker server according to your architecture and security remit.
The client will connect to the standard unix socket location /var/run/docker.sock. Use the
Docker::connect_with_unix method API to parameterise the
interface.
```rust use bollard::Docker;
Docker::connectwithunix_defaults(); ```
The client will connect to the standard windows pipe location \\.\pipe\docker_engine. Use the
Docker::connect_with_name_pipe method API
to parameterise the interface.
```rust use bollard::Docker;
Docker::connectwithnamedpipedefaults(); ```
The client will connect to the OS specific handler it is compiled for.
This is a convenience for localhost environment that should run on multiple
operating systems.
Use the Docker::connect_with_local method API to parameterise the interface.
rust
use bollard::Docker;
Docker::connect_with_local_defaults();
The client will connect to the location pointed to by DOCKER_HOST environment variable, or
localhost:2375 if missing. Use the
Docker::connect_with_http method API to
parameterise the interface.
rust
use bollard::Docker;
Docker::connect_with_http_defaults();
Openssl is switched off by default, and can be enabled through the ssl cargo feature.
The client will connect to the location pointed to by DOCKER_HOST environment variable, or
localhost:2375 if missing.
The location pointed to by the DOCKER_CERT_PATH environment variable is searched for
certificates - key.pem for the private key, cert.pem for the server certificate and
ca.pem for the certificate authority chain.
Use the Docker::connect_with_ssl method API
to parameterise the interface.
```rust use bollard::Docker;
Docker::connectwithssl_defaults(); ```
Native TLS allows you to avoid the SSL bindings.
The client will connect to the location pointed to by DOCKER_HOST environment variable, or
localhost:2375 if missing.
The location pointed to by the DOCKER_CERT_PATH environment variable is searched for
certificates - identity.pfx for the PKCS #12 archive and ca.pem for the certificate
authority chain.
Use the Docker::connect_with_ssl method API
to parameterise the interface.
```rust use bollard::Docker;
Docker::connectwithtls_defaults(); ```
Note: all these examples need a Tokio Runtime. A small example about how to use Tokio is further below.
First, check that the API is working with your server:
```rust, no_run use bollard::Docker;
use futures_util::future::FutureExt;
// Use a connection function described above // let docker = Docker::connect_...;
async move { let version = docker.version().await.unwrap(); println!("{:?}", version); }; ```rust
To list docker images available on the Docker server:
```rust,no_run use bollard::Docker; use bollard::image::ListImagesOptions;
use futures_util::future::FutureExt;
use std::default::Default;
// Use a connection function described above // let docker = Docker::connect_...;
async move {
let images = &docker.list_images(Some(ListImagesOptions::
for image in images {
println!("-> {:?}", image);
}
}; ```
To receive a stream of stats for a running container.
```rust use bollard::Docker; use bollard::container::StatsOptions;
use futuresutil::trystream::TryStreamExt;
use std::default::Default;
// Use a connection function described above // let docker = Docker::connect_...;
async move {
let stats = &docker.stats("postgres", Some(StatsOptions {
stream: true,
..Default::default()
})).try_collect::
for stat in stats {
println!("{} - mem total: {:?} | mem usage: {:?}",
stat.name,
stat.memory_stats.max_usage,
stat.memory_stats.usage);
}
}; ```
Further examples are available in the examples folder, or the integration/unit tests.
In order to use the API effectively, you will need to be familiar with the Tokio Runtime.
Create a Tokio Runtime:
```rust use tokio::runtime::Runtime;
let rt = Runtime::new().unwrap(); ```
Subsequently, use the docker API:
rust
// Use a connection function described above
// let docker = Docker::connect_...;
let future = async move {
&docker.list_images(None::<ListImagesOptions<String>>).await;
};
Execute the future aynchronously:
rust
rt.spawn(future);
Or, to execute and receive the result:
rust
let result = rt.block_on(future);
Finally, to shut down the executor:
rust
rt.shutdown_now();
This library stems from the boondock rust library, which in turn originates from the rust-docker library, but most parts were rewritten to adobt the new functionality provided by tokio. Many thanks to the original authors for the initial code and inspiration.
Running the integration tests by default requires a running docker registry, with images tagged
and pushed there. To disable this behaviour, set the DISABLE_REGISTRY environment variable.
bash
docker run -d --restart always --name registry -p 5000:5000 registry:2
docker pull hello-world:linux
docker pull fnichol/uhttpd
docker pull alpine
docker tag hello-world:linux localhost:5000/hello-world:linux
docker tag fnichol/uhttpd localhost:5000/fnichol/uhttpd
docker tag alpine localhost:5000/alpine
docker push localhost:5000/hello-world:linux
docker push localhost:5000/fnichol/uhttpd
docker push localhost:5000/alpine
REGISTRY_HTTP_ADDR=localhost:5000 cargo test -- --test-threads 1
License: Apache-2.0