{"id":13439918,"url":"https://github.com/fussybeaver/bollard","last_synced_at":"2026-04-09T13:02:05.390Z","repository":{"id":38310659,"uuid":"137915065","full_name":"fussybeaver/bollard","owner":"fussybeaver","description":"Docker daemon API in Rust","archived":false,"fork":false,"pushed_at":"2025-03-11T08:12:20.000Z","size":2098,"stargazers_count":994,"open_issues_count":42,"forks_count":143,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-11T09:23:24.096Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fussybeaver.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-06-19T16:05:31.000Z","updated_at":"2025-03-11T08:10:28.000Z","dependencies_parsed_at":"2023-02-12T10:46:06.154Z","dependency_job_id":"6d624807-44d5-4af3-982c-05ca41df2b8b","html_url":"https://github.com/fussybeaver/bollard","commit_stats":{"total_commits":588,"total_committers":67,"mean_commits":8.776119402985074,"dds":0.6479591836734694,"last_synced_commit":"03c481a5d8594c1f9132f224879479ef43aa8e2a"},"previous_names":[],"tags_count":45,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fussybeaver%2Fbollard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fussybeaver%2Fbollard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fussybeaver%2Fbollard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fussybeaver%2Fbollard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fussybeaver","download_url":"https://codeload.github.com/fussybeaver/bollard/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244585687,"owners_count":20476778,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T03:01:18.165Z","updated_at":"2026-04-09T13:02:05.379Z","avatar_url":"https://github.com/fussybeaver.png","language":"Rust","funding_links":[],"categories":["Libraries","Rust","库 Libraries","库"],"sub_categories":["Network programming","网络编程 Network programming","网络编程"],"readme":"[![crates.io](https://img.shields.io/crates/v/bollard.svg)](https://crates.io/crates/bollard)\n[![license](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![circle-ci](https://circleci.com/gh/fussybeaver/bollard/tree/master.svg?style=svg)](https://circleci.com/gh/fussybeaver/bollard/tree/master)\n[![appveyor](https://ci.appveyor.com/api/projects/status/n5khebyfae0u1sbv/branch/master?svg=true)](https://ci.appveyor.com/project/fussybeaver/boondock)\n[![docs](https://docs.rs/bollard/badge.svg)](https://docs.rs/bollard/)\n\n## Bollard: an asynchronous rust client library for the Docker/Podman API\n\nBollard leverages the latest [Hyper](https://github.com/hyperium/hyper) and\n[Tokio](https://github.com/tokio-rs/tokio) improvements for an asynchronous API containing\nfutures, streams and the async/await paradigm.\n\nThis library supports both [Docker](https://github.com/moby/moby) and\n[Podman](https://github.com/containers/podman) as first-class container runtimes, with\nautomatic socket discovery for rootless Podman. It features Windows support through [Named\nPipes](https://learn.microsoft.com/en-us/windows/win32/ipc/named-pipes) and HTTPS support through optional\n[Rustls](https://github.com/rustls/rustls) bindings. Serialization types for interfacing with\n[Docker](https://github.com/moby/moby) and [Buildkit](https://github.com/moby/buildkit) are generated through OpenAPI,\nprotobuf and upstream documentation.\n\n## Install\n\nAdd the following to your `Cargo.toml` file\n\n```nocompile\n[dependencies]\nbollard = \"*\"\n```\n\n## API\n### Documentation\n\n[API docs](https://docs.rs/bollard/).\n\n### Feature flags\n\n#### Quick Start\n\n| Use Case | Cargo.toml |\n|----------|------------|\n| Local Docker (Unix/Windows) | `bollard = \"*\"` _(defaults work)_ |\n| Remote Docker over HTTPS | `bollard = { version = \"*\", features = [\"ssl\"] }` |\n| SSH tunnel to remote Docker | `bollard = { version = \"*\", features = [\"ssh\"] }` |\n| BuildKit image builds | `bollard = { version = \"*\", features = [\"buildkit\", \"chrono\"] }` |\n| WebSocket container attach | `bollard = { version = \"*\", features = [\"websocket\"] }` |\n| Minimal binary size | `bollard = { version = \"*\", default-features = false, features = [\"pipe\"] }` |\n\n#### Default Features\n\nEnabled by default:\n- `http` - TCP connections to remote Docker/Podman (`DOCKER_HOST=tcp://...`)\n- `pipe` - Unix sockets and Windows named pipes\n\n#### Transport Features\n\n| Feature | Description |\n|---------|-------------|\n| `http` | HTTP/TCP connector for remote Docker/Podman |\n| `pipe` | Unix socket / Windows named pipe for local Docker/Podman |\n| `ssh` | SSH tunnel connector |\n\n#### TLS/SSL Features\n\nChoose **one** crypto provider:\n\n| Feature | Description |\n|---------|-------------|\n| `ssl` | [Rustls](https://github.com/rustls/rustls) with [ring](https://github.com/briansmith/ring) provider (recommended) |\n| `aws-lc-rs` | [Rustls](https://github.com/rustls/rustls) with [aws-lc-rs](https://github.com/aws/aws-lc-rs) provider (FIPS-compliant) |\n| `ssl_providerless` | [Rustls](https://github.com/rustls/rustls) without crypto provider (bring your own [CryptoProvider](https://docs.rs/rustls/latest/rustls/crypto/struct.CryptoProvider.html)) |\n| `webpki` | Use Mozilla's root certificates instead of OS native certs |\n\n#### DateTime Features\n\nFor timestamp support in events and logs, choose **one**:\n\n| Feature | Description |\n|---------|-------------|\n| `chrono` | [Chrono](https://github.com/chronotope/chrono) date/time types |\n| `time` | [Time 0.3](https://github.com/time-rs/time) date/time types |\n\n**Note:** `chrono` and `time` are mutually exclusive.\n\n#### BuildKit Features\n\n| Feature | Description |\n|---------|-------------|\n| `buildkit` | Full [BuildKit](https://github.com/moby/buildkit) support (includes `ssl`) |\n| `buildkit_providerless` | BuildKit without bundled crypto provider |\n\n**Note:** BuildKit requires either `chrono` or `time` feature to be enabled for timestamp handling. Example:\n```toml\nbollard = { version = \"*\", features = [\"buildkit\", \"chrono\"] }\n```\n\n#### WebSocket Features\n\n| Feature | Description |\n|---------|-------------|\n| `websocket` | WebSocket support for container attach using [tokio-tungstenite](https://github.com/snapview/tokio-tungstenite) |\n\n#### Development Features\n\n| Feature | Description |\n|---------|-------------|\n| `json_data_content` | Include raw JSON payload in deserialization errors |\n\n### Version\n\nThe [Docker API](https://docs.docker.com/reference/api/engine/version/v1.52/) used by Bollard is using the latest\n`1.52` documentation schema published by the [moby](https://github.com/moby/moby) project to\ngenerate its serialization interface.\n\nThis library also supports [version\nnegotiation](https://docs.rs/bollard/latest/bollard/struct.Docker.html#method.negotiate_version),\nto allow downgrading to an older API version.\n\n## Usage\n\n### Connecting with the container runtime\n\nConnect to Docker or Podman according to your architecture and security remit.\n\n#### Local (recommended)\n\nAuto-detect the best available socket on the local machine.\n\n```rust\nuse bollard::Docker;\nDocker::connect_with_local_defaults();\n```\n\nUse the `Docker::connect_with_local` method API to parameterise this interface.\n\n#### Podman\n\nExplicitly connect to Podman with automatic rootless/system socket discovery\n(Unix only).\n\n**Socket discovery order:**\n1. `$DOCKER_HOST` (if set and `unix://`)\n2. `$XDG_RUNTIME_DIR/podman/podman.sock` (rootless)\n3. `/run/user/$UID/podman/podman.sock` (rootless fallback)\n4. `/run/podman/podman.sock` (system/rootful)\n5. `/var/run/docker.sock` (Docker fallback)\n\n```rust\nuse bollard::Docker;\nDocker::connect_with_podman_defaults();\n```\n\n#### Socket\n\nThe client will connect to the standard unix socket location `/var/run/docker.sock` or Windows\nnamed pipe location `//./pipe/docker_engine`.\n\n```rust\nuse bollard::Docker;\n#[cfg(unix)]\nDocker::connect_with_socket_defaults();\n```\n\nUse the `Docker::connect_with_socket` method API to parameterise this interface.\n\n#### HTTP\n\nThe client will connect to the location pointed to by `DOCKER_HOST` environment variable, or\n`localhost:2375` if missing.\n\n```rust\nuse bollard::Docker;\nDocker::connect_with_http_defaults();\n```\n\nUse the `Docker::connect_with_http` method API to parameterise the interface.\n\n#### SSL via Rustls\n\nThe client will connect to the location pointed to by `DOCKER_HOST` environment variable, or\n`localhost:2375` if missing.\n\nThe location pointed to by the `DOCKER_CERT_PATH` environment variable is searched for\ncertificates - `key.pem` for the private key, `cert.pem` for the server certificate and\n`ca.pem` for the certificate authority chain.\n\n```rust\nuse bollard::Docker;\n#[cfg(feature = \"ssl\")]\nDocker::connect_with_ssl_defaults();\n```\n\nUse the `Docker::connect_with_ssl` method API to parameterise the interface.\n\n### Examples\n\nNote: all these examples need a [Tokio\nRuntime](https://tokio.rs/).\n\n#### Version\n\nFirst, check that the API is working with your server:\n\n```rust\nuse bollard::Docker;\n\nuse futures_util::future::FutureExt;\n\n// Use a connection function described above\n// let docker = Docker::connect_...;\n\nasync move {\n    let version = docker.version().await.unwrap();\n    println!(\"{:?}\", version);\n};\n```\n\n#### Listing images\n\nTo list docker images available on the Docker server:\n\n```rust\nuse bollard::Docker;\nuse bollard::image::ListImagesOptions;\n\nuse futures_util::future::FutureExt;\n\nuse std::default::Default;\n\n// Use a connection function described above\n// let docker = Docker::connect_...;\n\nasync move {\n    let images = \u0026docker.list_images(Some(ListImagesOptions::\u003cString\u003e {\n        all: true,\n        ..Default::default()\n    })).await.unwrap();\n\n    for image in images {\n        println!(\"-\u003e {:?}\", image);\n    }\n};\n```\n\n### Streaming Stats\n\nTo receive a stream of stats for a running container.\n\n```rust\nuse bollard::Docker;\nuse bollard::query_parameters::StatsOptionsBuilder;\n\nuse futures_util::stream::TryStreamExt;\n\nuse std::default::Default;\n\n// Use a connection function described above\n// let docker = Docker::connect_...;\n\nasync move {\n    let stats = \u0026docker.stats(\"postgres\", Some(\n      StatsOptionsBuilder::default().stream(true).build()\n    )).try_collect::\u003cVec\u003c_\u003e\u003e().await.unwrap();\n\n    for stat in stats {\n        println!(\"{} - mem total: {:?} | mem usage: {:?}\",\n            stat.name.as_ref().unwrap(),\n            stat.memory_stats.as_ref().unwrap().max_usage,\n            stat.memory_stats.as_ref().unwrap().usage);\n    }\n};\n```\n\n## Examples\n\nFurther examples are available in the [examples\nfolder](https://github.com/fussybeaver/bollard/tree/master/examples), or the [integration/unit\ntests](https://github.com/fussybeaver/bollard/tree/master/tests).\n\n## Development\n\nContributions are welcome, please observe the following.\n\n### Building the proto models\n\nSerialization models for the buildkit feature are generated through the [Tonic\nlibrary](https://github.com/hyperium/tonic/). To generate these files, use the\nfollowing in the `codegen/proto` folder:\n\n```bash\ncargo run --bin gen --features build\n```\n\n### Building the swagger models\n\nSerialization models are generated through the [Swagger\nlibrary](https://github.com/swagger-api/swagger-codegen/). To generate these files, use the\nfollowing in the `codegen/swagger` folder:\n\n```bash\nmvn -D org.slf4j.simpleLogger.defaultLogLevel=error compiler:compile generate-resources\n```\n\n## Integration tests\n\nRunning the integration tests by default requires a running docker registry, with images tagged\nand pushed there. To disable this behaviour, set the `DISABLE_REGISTRY` environment variable.\n\n```bash\ndocker run -d --restart always --name registry -p 5000:5000 registry:2\ndocker pull hello-world:linux\ndocker pull fussybeaver/uhttpd\ndocker pull alpine\ndocker tag hello-world:linux localhost:5000/hello-world:linux\ndocker tag fussybeaver/uhttpd localhost:5000/fussybeaver/uhttpd\ndocker tag alpine localhost:5000/alpine\ndocker push localhost:5000/hello-world:linux\ndocker push localhost:5000/fussybeaver/uhttpd\ndocker push localhost:5000/alpine\ndocker swarm init\nREGISTRY_HTTP_ADDR=localhost:5000 cargo test -- --test-threads 1\n```\n\nLicense: Apache-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffussybeaver%2Fbollard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffussybeaver%2Fbollard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffussybeaver%2Fbollard/lists"}