richfitz
commented
5 years ago Thanks Brian - you're right, this is not discussed anywhere.
- I've created a new vignette
cookbookto 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).
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
to something like
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.