Struct Container

pub struct Container<'a> { /* private fields */ }

A Docker container

Implementations

impl<'a> Container<'a>

pub fn new<T>(connection: &'a Docker, image: T) -> Self

where T: Into<String>,

Create a new Container

Examples

use gadget_sdk::docker::{connect_to_docker, Container};

#[tokio::main]
async fn main() -> Result<(), gadget_sdk::Error> {
    let connection = connect_to_docker(None).await?;
    let mut container = Container::new(&connection, "rustlang/rust");

    // We can now start our container
    container.start(true).await?;
    Ok(())
}

pub async fn from_id<T>(connection: &'a Docker, id: T) -> Result<Self, Error>

where T: AsRef<str>,

Attempt to fetch an existing container by its ID

Errors

• Docker inspect fails
• The container isn’t found

Examples

use gadget_sdk::docker::{connect_to_docker, Container};

#[tokio::main]
async fn main() -> Result<(), gadget_sdk::Error> {
    let connection = connect_to_docker(None).await?;
    let mut container = Container::new(&connection, "rustlang/rust");

    // We can now start our container and grab its id
    container.start(false).await?;

    let id = container.id().unwrap();

    let container2 = Container::from_id(&connection, id).await?;

    assert_eq!(container.id(), container2.id());
    Ok(())
}

pub fn env( &mut self, env: impl IntoIterator<Item = impl Into<String>>, ) -> &mut Self

Set the environment variables for the container

NOTE: This will override any existing variables.

Examples

use gadget_sdk::docker::{connect_to_docker, Container};

#[tokio::main]
async fn main() -> Result<(), gadget_sdk::Error> {
    let connection = connect_to_docker(None).await?;
    let mut container = Container::new(&connection, "rustlang/rust");

    container.env(["FOO=BAR", "BAZ=QUX"]);

    // We can now start our container, and the "FOO" and "BAZ" env vars will be set
    container.start(true).await?;
    Ok(())
}

pub fn cmd( &mut self, cmd: impl IntoIterator<Item = impl Into<String>>, ) -> &mut Self

Set the command to run

The command is provided as a list of strings.

NOTE: This will override any existing command

Examples

use gadget_sdk::docker::{connect_to_docker, Container};

#[tokio::main]
async fn main() -> Result<(), gadget_sdk::Error> {
    let connection = connect_to_docker(None).await?;
    let mut container = Container::new(&connection, "rustlang/rust");

    container.cmd(["echo", "Hello!"]);

    // We can now start our container, and the command "echo Hello!" will run
    container.start(true).await?;
    Ok(())
}

pub fn binds( &mut self, binds: impl IntoIterator<Item = impl Into<String>>, ) -> &mut Self

Set a list of volume binds

These binds are in the standard host:dest[:options] format. For more information, see the Docker documentation.

Examples

use gadget_sdk::docker::{connect_to_docker, Container};

#[tokio::main]
async fn main() -> Result<(), gadget_sdk::Error> {
    let connection = connect_to_docker(None).await?;
    let mut container = Container::new(&connection, "rustlang/rust");

    // Mount './my-host-dir' at '/some/container/dir' and make it read-only
    container.binds(["./my-host-dir:/some/container/dir:ro"]);

    // We can now start our container
    container.start(true).await?;
    Ok(())
}

pub fn id(&self) -> Option<&str>

Get the container ID if it has been created

This will only have a value if Container::create or Container::start has been called prior.

pub async fn create(&mut self) -> Result<(), Error>

Attempt to create the container

This will take the following into account:

• Container::env
• Container::cmd
• Container::binds

Be sure to set these before calling this!

Examples

use gadget_sdk::docker::{connect_to_docker, Container};

#[tokio::main]
async fn main() -> Result<(), gadget_sdk::Error> {
    let connection = connect_to_docker(None).await?;
    let mut container = Container::new(&connection, "rustlang/rust");

    container.env(["FOO=BAR", "BAZ=QUX"]);
    container.cmd(["echo", "Hello!"]);
    container.binds(["./host-data:/container-data"]);

    // The container is created using the above settings
    container.create().await?;

    // Now it can be started
    container.start(true).await?;
    Ok(())
}

pub async fn start(&mut self, wait_for_exit: bool) -> Result<(), Error>

Attempt to start the container

NOTE: If the container has not yet been created, this will attempt to call Container::create first.

wait_for_exit will wait for the container to exit before returning.

Examples

use gadget_sdk::docker::{connect_to_docker, Container};

#[tokio::main]
async fn main() -> Result<(), gadget_sdk::Error> {
    let connection = connect_to_docker(None).await?;
    let mut container = Container::new(&connection, "rustlang/rust");

    container.cmd(["echo", "Hello!"]);

    // We can now start our container, and the command "echo Hello!" will run.
    let wait_for_exit = true;
    container.start(wait_for_exit).await?;

    // Since we waited for the container to exit, we don't have to stop it.
    // It can now just be removed.
    container.remove(None).await?;
    Ok(())
}

pub async fn status(&self) -> Result<Option<ContainerStatus>, Error>

Checks if the container has not exited and is marked as healthy

NOTE: If the container has not yet been created, this will immediately return None.

Examples

use gadget_sdk::docker::{connect_to_docker, Container};
use std::time::Duration;
use tokio::time;

#[tokio::main]
async fn main() -> Result<(), gadget_sdk::Error> {
    let connection = connect_to_docker(None).await?;
    let mut container = Container::new(&connection, "rustlang/rust");

    container.cmd(["echo", "Hello!"]);

    let wait_for_exit = false;
    container.start(wait_for_exit).await?;

    loop {
        let status = container.status().await?.unwrap();
        if status.is_active() {
            time::sleep(Duration::from_secs(5)).await;
            continue;
        }

        println!("Container exited!");
        break;
    }

    Ok(())
}

pub async fn stop(&mut self) -> Result<(), Error>

Stop a running container

NOTE: It is not an error to call this on a container that has not been started, it will simply do nothing.

Examples

use gadget_sdk::docker::{connect_to_docker, Container};

#[tokio::main]
async fn main() -> Result<(), gadget_sdk::Error> {
    let connection = connect_to_docker(None).await?;

    let mut container = Container::new(&connection, "rustlang/rust");

    // Does nothing, the container isn't started
    container.stop().await?;

    // Stops the running container
    container.start(false).await?;
    container.stop().await?;
    Ok(())
}

pub async fn remove( self, options: Option<RemoveContainerOptions>, ) -> Result<(), Error>

Remove a container

NOTE: To remove a running container, a [RemoveContainerOptions] must be provided with the force flag set.

See also: bollard::container::RemoveContainerOptions

Examples

use gadget_sdk::docker::{bollard, connect_to_docker, Container};

#[tokio::main]
async fn main() -> Result<(), gadget_sdk::Error> {
    let connection = connect_to_docker(None).await?;

    let mut container = Container::new(&connection, "rustlang/rust");

    // Start our container
    container.start(false).await?;

    let remove_container_options = bollard::container::RemoveContainerOptions {
        force: true,
        ..Default::default()
    };

    // Kills the container and removes it
    container.remove(Some(remove_container_options)).await?;
    Ok(())
}

pub async fn wait(&self) -> Result<(), Error>

Wait for a container to exit

NOTE: It is not an error to call this on a container that has not been started, it will simply do nothing.

Examples

use gadget_sdk::docker::{bollard, connect_to_docker, Container};

#[tokio::main]
async fn main() -> Result<(), gadget_sdk::Error> {
    let connection = connect_to_docker(None).await?;

    let mut container = Container::new(&connection, "rustlang/rust");

    // Start our container
    container.start(false).await?;

    // Once this returns, we know that the container has exited.
    container.wait().await?;
    Ok(())
}

pub async fn logs( &self, logs_options: Option<LogsOptions<String>>, ) -> Option<impl Stream<Item = Result<LogOutput, Error>>>

Fetch the container log stream

NOTE: It is not an error to call this on a container that has not been started, it will simply do nothing and return None.

See also:

• bollard::container::LogsOptions
• bollard::container::LogOutput

Examples

use futures::StreamExt;
use gadget_sdk::docker::{bollard, connect_to_docker, Container};

#[tokio::main]
async fn main() -> Result<(), gadget_sdk::Error> {
    let connection = connect_to_docker(None).await?;
    let mut container = Container::new(&connection, "rustlang/rust");

    // Start our container and wait for it to exit
    container.start(true).await?;

    // We want to collect logs from stderr
    let logs_options = bollard::container::LogsOptions {
        stderr: true,
        follow: true,
        ..Default::default()
    };

    // Get our log stream
    let mut logs = container
        .logs(Some(logs_options))
        .await
        .expect("logs should be present");

    // Now we want to print anything from stderr
    while let Some(Ok(out)) = logs.next().await {
        if let bollard::container::LogOutput::StdErr { message } = out {
            eprintln!("Uh oh! Something was written to stderr: {:?}", message);
        }
    }
    Ok(())
}

Trait Implementations

impl<'a> Debug for Container<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.