docker_client: Create docker client

In richfitz/stevedore: Docker Client

Create docker client

Description

Create a docker client object, which allows you to interact with docker from R. The object has several methods that allow interaction with the docker daemon (for this object they are all "system" commands) and collections, which contains further methods. The client is structured similarly to the docker command line client, such that docker container create <args> in the command line becomes docker$container$create(...) in R (if the client is called R).

Usage

docker_client(
  ...,
  api_version = NULL,
  host = NULL,
  cert_path = NULL,
  tls_verify = NULL,
  machine = NULL,
  http_client_type = NULL,
  data_frame = NULL,
  quiet = FALSE,
  debug = NULL,
  ignore_environment = FALSE
)

Arguments

...	Reserved for future use. Passing in any unrecognised argument will throw an error. Part of the role of this argument is to force use of named arguments until the API is stabilised.
api_version	Version of the API to use when communicating with the docker daemon. The default value, NULL, detects the docker server API version and attempts to match it (this mirrors the default behaviour of the docker command line client). Alternatively, provide an API version number as a string or numeric_version object (supported between \Sexpr{stevedore:::DOCKER_API_VERSION_MIN} and \Sexpr{stevedore:::DOCKER_API_VERSION_MAX}). The version \Sexpr{stevedore:::DOCKER_API_VERSION_DEFAULT} is the version used in most automated tests, and if problems are encountered, consider forcing this version).
host	The URL for the docker daemon. This can be a unix socket (e.g., unix:///var/run/docker.sock) on macOS/Linux, a named pipe (e.g., npipe:////./pipe/docker_engine) on Windows, or an http or https url (e.g., https://localhost:2376). If not given, we use the environment variable DOCKER_HOST, falling back on the default socket or named pipe (for macOS/unix and windows respectively).
cert_path	The path to a directory containing certificate files. If using an https url this is required. If not given, we use the environment variable DOCKER_CERT_PATH. This is ignored without warning if used with a socket or named pipe connection.
tls_verify	Logical, indicating if TLS should be verified. This is only used if using an https connection (i.e., host is a tcp/http/https url andcert_path is given). If not given, we use the environment variable DOCKER_TLS_VERIFY.
machine	Scalar character (if provided) indicating the name of a "docker machine" instance to use. If this is provided then docker-machine must be installed and the machine must exist and be running. stevedore will run docker-machine env machine to determine the environment variables to contact this machine and use these values for host, cert_path and tls_verify (silently ignoring any provided values). Carl Boettiger is working on a docker machine package for R that would make managing docker machines from R easier. As an alternative to this option, one can set docker-machine environment variables as described in docker-machine env before running R and they would be picked up as described above.
http_client_type	HTTP client type to use. The options are (currently) "curl", which uses the curl package (works over unix sockets and over TCP) and httppipe which works over unix sockets and windows named pipes, using the Docker SDK's pipe code via the httppipe package. Not all functionality is supported with the httppipe client. This option may eventually be moved into the ... argument as is not intended for end-user use; it is primarily intended for debugging in development (forcing the httppipe client where the curl client would ordinarily be preferred).
data_frame	Function, used to wrap data.frames returned. This may make output easier to consume. You might use tibble::as_tibble to return a tbl_df or datatable::as.data.table to return data.table objects. This will be applied to all data.frames after they are constructed, and so must take a single argument (the newly constructed data.frame) and return a new object that is largely compatible with data.frame. Another use for this would be to define a function data_frame = function(x) structure(x, class = c("foo", "data.frame")) to set the class of all returned data.frame objects to be "foo" as well and then defining a custom S3 print method for "foo" that limited the output.
quiet	Suppress informational messages.
debug	Enable http debugging (supported by the curl http driver only). Provide a connection object and http headers and content will be sent to it. Using debug = TRUE is equivalent to code = stdout(), while debug = FALSE is equivalent to debug = NULL (the default) which prevents debugging information being printed. This option can be used to write to a file by opening a writeable connection but care must be made not to close this connection because otherwise the curl requests may fail.
ignore_environment	Logical, indicating if environment variables (DOCKER_HOST, DOCKER_CERT_PATH, DOCKER_TLS_VERIFY and DOCKER_API_VERSION) should be ignored (this has no effect if machine is specified).

Details

\Sexpr[results=rd,stage=render]{stevedore:::generate_help()}

Connection options

stevedore can connect to the docker daemon via a unix socket (this is the default set-up on Linux and macOS), over a named pipe (Windows 10 - see below) and https over a normal tcp connection (this is especially useful with docker-machine.

1. If the machine argument is given then stevedore queries docker-machine for settings. If that command fails (e.g., there is no machine, docker-machine not installed) then that will cause an error. (Note that the docker-machine output does not include API version information so the api_version argument is relevant, but host, cert_path and tls_verify will be silently ignored if provided).

2. The arguments host overrides the environment variable DOCKER_HOST, cert_path overrides DOCKER_CERT_PATH and tls_verify overrides DOCKER_TLS_VERIFY. If ignore_environment is TRUE then the environment variables are not used at all.

3. if code is not provided by any of the above methods (machine, argument or environment variable) it will fall back on the default unix socket (var/run/docker.sock) on Linux/macOS or the default windows named pipe (npipe:////./pipe/docker_engine) on windows.

The API version is set by the api_version argument, which falls back on the environment variable DOCKER_API_VERSION (this is the same as the docker command line client and the python SDK). If neither are provided then stevedore will detect the API version being used by the daemon and match that (provided it falls within the range of versions supported by the package).

Examples

if (stevedore::docker_available()) {
  # Create a new client object:
  client <- stevedore::docker_client()

  # Version information for your docker daemon:
  client$version()

  # General information about your daemon:
  client$info()

  # Most of the interesting methods are within the collections.
  # For example, to see a summary of running containers:
  client$container$list()

  # (see ?docker_container) for more information.
}

richfitz/stevedore documentation built on July 22, 2023, 1:13 p.m.