Bollard leverages the latest Hyper and Tokio improvements for an asynchronous API containing futures, streams and the async/await paradigm.
This library features Windows support through Named Pipes and HTTPS support through optional Rustls bindings. Serialization types for interfacing with Docker and Buildkit are generated through OpenAPI, protobuf and upstream documentation.
Add the following to your Cargo.toml file
nocompile
[dependencies]
bollard = "*"
Version 0.14 enables a buildkit feature for builds using public images (check the
buildkit example
for details on how to configure).
ssl: enable SSL support through Rustlschrono: enable Chrono for DateTime types.time: enable Time 0.3 for DateTime types.buildkit: use Buildkit instead of
Docker when building images.json_data_content: Add JSON to errors on serialization failures.ct_logs: Certificate transparency
verification (requires ssl).The Docker API used by Bollard is using the latest
1.41 documentation schema published by the moby project to
generate its serialization interface.
This library also supports version negotiation, to allow downgrading to an older API version.
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 or Windows
named pipe location //./pipe/docker_engine.
```rust use bollard_next::Docker;
Docker::connectwithsocket_defaults(); ```
Use the Docker::connect_with_socket method API to parameterise this interface.
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.
rust
use bollard_next::Docker;
Docker::connect_with_local_defaults();
Use the Docker::connect_with_local method API to parameterise this interface.
The client will connect to the location pointed to by DOCKER_HOST environment variable, or
localhost:2375 if missing.
rust
use bollard_next::Docker;
Docker::connect_with_http_defaults();
Use the Docker::connect_with_http method API to parameterise the interface.
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.
```rust use bollard_next::Docker;
Docker::connectwithssl_defaults(); ```
Use the Docker::connect_with_ssl method API to parameterise the interface.
Note: all these examples need a Tokio Runtime.
First, check that the API is working with your server:
```rust use bollard_next::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); }; ```
To list docker images available on the Docker server:
```rust use bollardnext::Docker; use bollardnext::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 bollardnext::Docker; use bollardnext::container::StatsOptions;
use futures_util::stream::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.
Contributions are welcome, please observe the following.
Serialization models for the buildkit feature are generated through the Tonic
library. To generate these files, use the
following in the codegen/proto folder:
bash
cargo run --bin gen --features build
Serialization models are generated through the Swagger
library. To generate these files, use the
following in the codegen/swagger folder:
bash
mvn -D org.slf4j.simpleLogger.defaultLogLevel=error compiler:compile generate-resources
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 fussybeaver/uhttpd
docker pull alpine
docker tag hello-world:linux localhost:5000/hello-world:linux
docker tag fussybeaver/uhttpd localhost:5000/fussybeaver/uhttpd
docker tag alpine localhost:5000/alpine
docker push localhost:5000/hello-world:linux
docker push localhost:5000/fussybeaver/uhttpd
docker push localhost:5000/alpine
docker swarm init
REGISTRY_HTTP_ADDR=localhost:5000 cargo test -- --test-threads 1
License: Apache-2.0