shiplift

To use shiplift in your Rust project, add it to your Cargo.toml dependencies. This provides a Rust interface for maneuvering Docker containers.

[dependencies]
shiplift = "0.7"

Operations that involve long-running processes like build, pull, or import return a stream of ImageBuildChunk items. These chunks represent the progress or status of the operation.

Variants of ImageBuildChunk:

• Update { stream: String }: A line of text from the process output.
• Error { error: String, error_detail: ErrorDetail }: An error occurred during the operation.
• Digest { aux: Aux }: The operation completed successfully, providing the image ID.
• PullStatus { status: String, id: Option<String>, progress: Option<String>, progress_detail: Option<ProgressDetail }: Status updates for pull operations.

The HostConfig struct defines the resource constraints and host-level settings for a container.

Key configuration areas:

• Resources: cpu_shares, memory, nano_cpus, pids_limit, and memory_swappiness.
• Networking: network_mode, port_bindings (via PortMap), and dns settings.
• Storage: binds, mounts, volumes_from, and tmpfs.
• Security: privileged, cap_add, cap_drop, security_opt, and user.
• Lifecycle: restart_policy and auto_remove.

The Services struct provides an interface to interact with the collection of services on a Docker host. You can use it to list all services or retrieve a handle to a specific named service using .get(name).

To use it, initialize it with a reference to a Docker instance.

let services = Services::new(&docker);

// List all services
let list = services.list(&ServiceListOptions::builder().build()).await?;

// Get a handle to a specific service
let service = services.get("my-service-name");

To start using Shiplift, create a new Docker instance using Docker::new(). This instance serves as the entry point for interacting with the Docker daemon via various sub-modules like images(), containers(), networks(), etc. Most operations are asynchronous and return a Result.

# async {
let docker = shiplift::Docker::new();

match docker.images().list(&Default::default()).await {
    Ok(images) => {
        for image in images {
            println!("{:?}", image.repo_tags);
        }
    },
    Err(e) => eprintln!("Something bad happened! {}", e),
}
# };

Once you have a Network instance (obtained via Networks::get(id) or from NetworkCreateInfo), you can manipulate that specific network:

• inspect(): Returns NetworkDetails for the network.
• delete(): Removes the network.
• connect(&ContainerConnectionOptions): Attaches a container to the network.
• disconnect(&ContainerConnectionOptions): Detaches a container from the network.

let network = networks.get("network-id");

// Inspect details
let details = network.inspect().await?;

// Connect a container
let conn_opts = ContainerConnectionOptions::builder("container-id")
    .aliases(vec!["web-server"])
    .build();
network.connect(&conn_opts).await?;

// Delete the network
network.delete().await?;

Use TagOptions::builder() to configure how an existing image is tagged.

Available configuration methods:

• repo(r): The repository name to tag the image with.
• tag(t): The tag to apply.

let opts = TagOptions::builder()
    .repo("my-org/my-image")
    .tag("v1.2.3")
    .build();

image.tag(&opts).await?;

Use NetworkCreateOptions::builder(name) to configure a new network before creation. The builder pattern allows you to specify the driver and labels.

Available builder methods:

• driver(name: &str): Sets the network driver (e.g., "bridge", "overlay").
• label(labels: HashMap<String, String>): Sets metadata labels for the network.
• build(): Finalizes the options.

let mut labels = HashMap::new();
labels.insert("environment".to_string(), "production".to_string());

let opts = NetworkCreateOptions::builder("prod-net")
    .driver("bridge")
    .label(labels)
    .build();