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).
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
)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.
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 stevedore:::DOCKER_API_VERSION_MIN and
stevedore:::DOCKER_API_VERSION_MAX). The version
stevedore:::DOCKER_API_VERSION_DEFAULT is the version
used in most automated tests, and if problems are encountered,
consider forcing this version).
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).
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.
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.
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 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).
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.
Suppress informational messages.
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.
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).
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.
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).
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.
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).
stevedore:::generate_help()
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.
}
Run the code above in your browser using DataLab