Vignette need

[bomeara]

I've been using docker for projects in my lab (and for my kids' minecraft servers), so I have some familiarity with running containers, using docker compose, writing dockerfiles, etc., but I'm by no means an expert [just giving a sense of my baseline knowledge]. I've looked through the vignettes and help, and I'm still uncertain how to convert

docker run --rm -it -p 8888:80 gplates/gws

to something like

docker <- stevedore::docker_client()
docker$container$run("gplates/gws")

How can I do port forwarding, etc.

I don't need this urgently, but it was blocking for me, and I thought it'd be helpful to have an unmet documentation use case.

And thanks for your work on this -- I can see this package being very useful.

[richfitz]

Thanks Brian - you're right, this is not discussed anywhere.

• I've created a new vignette cookbook to help with snippet related documentation and used your specific example here (https://github.com/richfitz/stevedore/blob/develop/vignettes/cookbook.Rmd - on the develop branch for now)
• There's a limit to what can be sensibly included in the intro vignette but if you can see where this would fit I can include something there too

More generally, there is extensive help in the package but it is mostly autogenerated from the docker spec and may not be that obvious to get to or super appropriate. So I am curious to know what you managed to find to distinguish between discoverability of the help vs its suitability:

If you print a stevedore function, it documents it's arguments

> docker$container$run
function(image, cmd = NULL, ..., detach = FALSE, rm = FALSE,
    stream = stdout(), host_config = NULL)
------------------------------------------------------------
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.
------------------------------------------------------------
  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 ....

Then if you follow through to ?docker_container_collection (which you can also get to with docker$container$help()) it says, under the documentation for the create method

             • ‘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), (2) the form ‘<port>’ as 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.

(it turns out that help is actually slightly incorrect and I'm fixing that at the same time!)

Can I ask how far you got, which help you didn't know about and how it could be made more obvious to find?

(sorry for the delay - I've had to disable most notifications for github etc so I only find out about things periodically).

[richfitz]

Fixed in 0.9.3