Management commands for working with docker containers

Methods for working with docker containers. This object is $container within a docker_client object.

Details

Below is reference documentation for all methods for version '1.29' of the docker API - other versions are available. This documentation is automatically generated from docker's API schema, and so inaccuracies may exist between it and stevedore's interface (especially references to JSON objects). Please report any documentation that might be improved at https://github.com/richfitz/stevedore/issues

Methods

container_create

Create a container. Similar to the cli command docker create or docker container create.

Usage:

  container_create(image, cmd = NULL, hostname = NULL,
      domainname = NULL, user = NULL, attach_stdin = NULL,
      attach_stdout = NULL, attach_stderr = NULL, ports = NULL,
      tty = NULL, open_stdin = NULL, stdin_once = NULL,
      env = NULL, health_check = NULL, args_escaped = NULL,
      volumes = NULL, working_dir = NULL, entrypoint = NULL,
      network_disabled = NULL, mac_address = NULL,
      on_build = NULL, labels = NULL, stop_signal = NULL,
      stop_timeout = NULL, shell = NULL, host_config = NULL,
      network = NULL, name = NULL)

Arguments:

• image: The name of the image to use when creating the container

• cmd: Command to run specified as a string or an array of strings.

• hostname: The hostname to use for the container, as a valid RFC 1123 hostname.

• domainname: The domain name to use for the container.

• user: The user that commands are run as inside the container.

• attach_stdin: Whether to attach to stdin.

• attach_stdout: Whether to attach to stdout.

• attach_stderr: Whether to attach to stderr.

• ports: A character vector of port mappings between the container and host, in (1) the form <host>:<container> (e.g., 10080:80 to map the container's port 80 to the host's port 10080), <ip>:<host>:<container> to bind a specific host interface as well as a port (e.g., you can use localhost or 127.0.0.1 for the first element), (3) form <port> to map the containers port to a random available port on the host s shorthand for <port>:<port>, or (3) a single logical value TRUE indicating to map all container ports to random available ports on the host. You can use the $ports() method in the docker_container object to query the port mapping of a running container. Multiple values can be provided to map multiple ports to the host (e.g., c("80", "443:443").

• tty: Attach standard streams to a TTY, including stdin if it is not closed.

• open_stdin: Open stdin

• stdin_once: Close stdin after one attached client disconnects

• env: A list of environment variables to set inside the container in the form ["VAR=value", ...]. A variable without = is removed from the environment, rather than to have an empty value.

• health_check: A test to perform to check that the container is healthy. Construct with $types$health_config()

• args_escaped: Command is already escaped (Windows only)

• volumes: A character vector of mappings of mount points on the host (or in volumes) to paths on the container. Each element must be of the form <path_host>:<path_container>, possibly followed by :ro for read-only mappings (i.e., the same syntax as the docker command line client). docker_volume objects have a $map method to help with generating these paths for volume mappings.

• working_dir: The working directory for commands to run in.

• entrypoint: The entry point for the container as a string or an array of strings.

  If the array consists of exactly one empty string ([""]) then the entry point is reset to system default (i.e., the entry point used by docker when there is no ENTRYPOINT instruction in the Dockerfile).

• network_disabled: Disable networking for the container.

• mac_address: MAC address of the container.

• on_build: ONBUILD metadata that were defined in the image's Dockerfile.

• labels: User-defined key/value metadata.

• stop_signal: Signal to stop a container as a string or unsigned integer.

• stop_timeout: Timeout to stop a container in seconds.

• shell: Shell for when RUN, CMD, and ENTRYPOINT uses a shell.

• host_config: Container configuration that depends on the host we are running on

• network: This container's networking configuration.

• name: Assign the specified name to the container. Must match /?[a-zA-Z0-9_-]+.

get

Get a container by name or id

Usage:

  get(id)

Arguments:

• id: A scalar character with the container's name or id (abbreviations of the id are allowed and will be resolved by the docker daemon).

help

Display help for this object

Usage:

  help(help_type = getOption("help_type"))

Arguments:

• help_type: Passed to utils::help, can be one of "text", "html" or "pdf" (or an abbreviation). By default it uses the value getOption("help_type") and should follow the same behaviour as other R help (e.g., using "?")

container_list

List containers. Similar to the cli command docker ps or docker container ls.

Usage:

  container_list(all = NULL, limit = NULL, size = NULL,
      filters = NULL)

Arguments:

• all: Return all containers. By default, only running containers are shown

• limit: Return this number of most recently created containers, including non-running ones.

• size: Return the size of container as fields SizeRw and SizeRootFs.

• filters: Filters to process on the container list, as a named character vector. For example c(status = "paused") will only return paused containers. Available filters:

  • ancestor=(<image-name>[:<tag>], <image id>, or <image@digest>)

  • before=(<container id> or <container name>)

  • expose=(<port>[/<proto>]|<startport-endport>/[<proto>])

  • exited=<int> containers with exit code of <int>

  • health=(starting|healthy|unhealthy|none)

  • id=<ID> a container's ID

  • isolation=(default|process|hyperv) (Windows daemon only)

  • is-task=(true|false)

  • label=key or label="key=value" of a container label

  • name=<name> a container's name

  • network=(<network id> or <network name>)

  • publish=(<port>[/<proto>]|<startport-endport>/[<proto>])

  • since=(<container id> or <container name>)

  • status=(created|restarting|running|removing|paused|exited|dead)

  • volume=(<volume name> or <mount point destination>)

container_prune

Delete stopped containers. Similar to the cli command docker container prune.

Usage:

  container_prune(filters = NULL)

Arguments:

• filters: Filters to process on the prune list, as a named character vector.

  • until=<timestamp> Prune containers created before this timestamp. The <timestamp> can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. 10m, 1h30m) computed relative to the daemon machine's time.

container_delete

Remove a container. Similar to the cli command docker rm or docker container rm.

Usage:

  container_delete(id, delete_volumes = NULL, force = NULL,
      link = NULL)

Arguments:

• id: ID or name of the container

• delete_volumes: Remove the volumes associated with the container.

• force: If the container is running, kill it before removing it.

• link: Remove the specified link associated with the container.

run

Run a command in a new container. This method does rather a lot, and wraps several other methods. It aims to mimic the behaviour of docker run in the command line tool. It will:

• Try to pull a container if it does not yet exist (see $pull in docker_image_collection)

• Create the container (see $create in docker_container_collection)

• Start the container (see $start in docker_container)

• Optionally stream the logs, if not detached (see $logs in docker_container

• Wait for the container to finish (see $wait in docker_container)

It returns a list with a container object as "container" and a "docker_stream" object containing logs as "logs"). If rm = TRUE and detach = TRUE the container object will be of limited utility and you will need to use reload = FALSE on many methods (and some will not work) as the container will have been removed on exit.

Unlike the command line version, interrupting the streaming logs will not necessarily kill the container but may leave it running in the background.

Unlike the command line version, the attach = TRUE simply attaches the output of the container and blocks the R session until it is complete. There is currently no way of sending input into the docker container. Similar to the cli command docker run.

Usage:

  run(image, cmd = NULL, ..., detach = FALSE, rm = FALSE,
      stream = stdout(), host_config = NULL)

Arguments:

• image: Image to run. Can be a name, id, or a docker_image object.

• cmd: Command to run in the container. Must be a character vector. If not specified then the default ENTRYPOINT and CMD will be used (see the docker documentation for details)

• ...: Additional arguments passed through to $create (see docker_container_collection. There are many possible arguments here.

• detach: Detach the container as soon as it has started and return control to R. The container will run in the background. The returned object can be used to interrogate the container afterwards (see docker_container).

• rm: Remove the container on exit.

• stream: The stream to use to send output to, if detach = FALSE. The default uses the standard output stream (i.e., where cat would send output). Other valid values are an R connection object, a string (interpreted as a filename) or FALSE to prevent any output.

• host_config: Passed through to $create, as with ....

See also

docker_container for information on container objects.