{"id":13858164,"url":"https://github.com/richfitz/stevedore","last_synced_at":"2025-04-06T02:11:26.380Z","repository":{"id":52844713,"uuid":"111851919","full_name":"richfitz/stevedore","owner":"richfitz","description":":cloud::rowboat::whale::cloud: Docker client for R","archived":false,"fork":false,"pushed_at":"2024-02-08T00:08:19.000Z","size":3477,"stargazers_count":134,"open_issues_count":17,"forks_count":10,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-10-13T17:49:41.448Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://richfitz.github.io/stevedore","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/richfitz.png","metadata":{"files":{"readme":"README.Rmd","changelog":"NEWS.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-11-23T21:35:13.000Z","updated_at":"2024-05-24T13:54:45.000Z","dependencies_parsed_at":"2024-02-09T02:09:45.243Z","dependency_job_id":"86d2fcb7-aef4-46eb-9d06-68259a3e44ce","html_url":"https://github.com/richfitz/stevedore","commit_stats":{"total_commits":850,"total_committers":4,"mean_commits":212.5,"dds":"0.045882352941176485","last_synced_commit":"668d7c9a3ae23279a2c41498e58c36bb01b4a76d"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/richfitz%2Fstevedore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/richfitz%2Fstevedore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/richfitz%2Fstevedore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/richfitz%2Fstevedore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/richfitz","download_url":"https://codeload.github.com/richfitz/stevedore/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247423515,"owners_count":20936626,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-05T03:01:58.898Z","updated_at":"2025-04-06T02:11:26.357Z","avatar_url":"https://github.com/richfitz.png","language":"R","funding_links":[],"categories":["R"],"sub_categories":[],"readme":"\u003c!-- -*-markdown-*- --\u003e\n# stevedore\n\n\u003c!-- badges: start --\u003e\n[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)\n[![R build status](https://github.com/richfitz/stevedore/workflows/R-CMD-check/badge.svg)](https://github.com/richfitz/stevedore/actions)\n[![codecov.io](https://codecov.io/github/richfitz/stevedore/coverage.svg?branch=master)](https://app.codecov.io/github/richfitz/stevedore?branch=master)\n[![](https://www.r-pkg.org/badges/version/stevedore)](https://cran.r-project.org/package=stevedore)\n\u003c!-- badges: end --\u003e\n\nA docker client for R\n\n```{r, prep, include = FALSE}\nknitr::opts_chunk$set(error = FALSE)\nhas_internet \u003c- function() {\n  !is.null(suppressWarnings(utils::nsl(\"www.google.com\")))\n}\nif (has_internet()) {\n  d \u003c- stevedore::docker_client()\n  try(d$image$remove(\"alpine:3.1\"), silent = TRUE)\n}\n```\n\n![hello world example of stevedore](https://raw.githubusercontent.com/richfitz/stevedore/master/demo/hello.gif)\n\n\n## Background\n\n**What is docker?** Docker is a platform for \"containerising\" applications - running them in isolation from one another, removing differences of how they are built, what they are built from, and what resources they need (disk, ports, users, etc).  It's similar conceptually to virtualisation, but much more light weight.\n\n**Why would one want to use docker from R?** Whenever you need to control external processes from an R script or package, it might be useful to interact with this process from in containers using docker\n\n- *package authors* might want a clean environment to test their code (similar to travis)\n- *a developer using an external database* in a package or in an analysis script might use docker to create disposable copies of the database, or to create a copy isolated from their production database\n- *a researcher* might use docker to do a reproducible analysis, or preserve the artefacts that were created along with a copy of the environment that created them\n\nThese are discussed further in the [applications vignette](https://richfitz.github.io/stevedore/articles/examples.html)\n\n\n## Usage\n\nThe main function in the package is `docker_client`; this will construct an object with which we can talk with the docker server.\n\n```{r, create}\ndocker \u003c- stevedore::docker_client()\ndocker\n```\n\nWith this you can run containers:\n\n```{r, run}\ndocker$container$run(\"alpine:3.1\", c(\"echo\", \"hello world\"))\n```\n\nOr run containers in the background\n\n```{r, background}\ndocker$container$run(\"bfirsh/reticulate-splines\", detach = TRUE)\n```\n\nYou can manage containers\n\n```{r, list}\ndocker$container$list()\nid \u003c- docker$container$list(limit = 1L)$id\ncontainer \u003c- docker$container$get(id)\ncontainer\n```\n\nAnd control containers\n\n```{r, control}\ncontainer$inspect()$config$image\ncontainer$logs()\ncontainer$stop(t = 0)\ncontainer$remove()\n```\n\nAnd manage images\n\n```{r, images}\nhead(docker$image$list())\n```\n\nSome of these functions have many arguments, but `stevedore` includes help inline:\n\n```{r, help}\ndocker$container$create\n```\n\nas well as via an `help()` method on each object (e.g., `docker$help()`, `docker$container$help()`) which will display help for the API version that you are using.\n\n## Approach\n\nThe Docker API is [versioned](https://docs.docker.com/develop/sdk/#api-version-matrix) and each version includes a [machine-readable API specification](https://docs.docker.com/engine/api/v1.29).  Rather than manually write wrappers that fit the output docker gives, `stevedore` _generates_ an interface directly from the spefification.  Currently `stevedore` supports docker API versions `r stevedore:::DOCKER_API_VERSION_MIN` to `r stevedore:::DOCKER_API_VERSION_MAX` (defaulting to `r stevedore:::DOCKER_API_VERSION_DEFAULT`).\n\nThis approach means that the output will be type-stable - there is no inference on what to return based on what the server chooses to return.  With a given API version, the same fields will always be returned.  Some of this information is very rich, for example, for the backgrounded container above:\n\n```{r, inspect}\ncontainer$inspect(reload = FALSE)\n```\n\n## Windows support\n\nWindows support for docker through this package is currently incomplete.  The [appveyor build](https://ci.appveyor.com/project/richfitz/stevedore) tests only the parts of the package that don't actually call docker due to difficult-to-debug issues with container compatibility on that platform.\n\n### Current situation\n\nThe support for windows is not as comprehensive as for other platforms (but I'm not sure how common using docker is on windows yet).  The reason for this is that [`curl`](https://cran.r-project.org/package=curl) (and the underlying `libcurl` library) do not support communicating over \"named pipes\" which is how docker works on windows 10.\n\nThe package includes a small wrapper around the python sdk's docker support.  On the R side this requires the `reticulate` package.  It also requires that you have a python installation that includes both the `docker` package and `pypiwin32` - once python is installed you can add these packages to python with\n\n```\npip install docker pypiwin32\n```\n\n(or `pip3` instead of `pip` to use python3).\n\nYou can check that everything is configured by running\n\n```r\nstevedore:::httppipe_available(verbose = TRUE)\n```\n\nwhich will return `TRUE` if everything is OK, and otherwise print some information about errors loading the package.  In the case of error consult the reticulate documentation (`vignette(\"versions\", package = \"reticulate\")` will be especially useful).  Improvements to installation documentation and process are welcome!\n\n### Limitations\n\nThe primary limitation of the `httppipe` interface is that streaming connections are not supported.  This affects the following methods\n\n* container logs with `follow = TRUE`: completely unsupported\n* container run - works completely with `detach = TRUE`, and with `detach = FALSE` works but prints output only at the end (not streaming output)\n* image build - works but information printed only at end of build rather than streaming\n* image pull - works but information printed only at end of pull\n* exec start - works but information printed only at end of execution\n\n### Going forward\n\nThe support in this package is a duplicate of the micropackage [`httppipe`](https://github.com/richfitz/httppipe/).  This implements the minimum functionality with windows named pipes to support docker.  I would **love** for someone to help port this to a python-free package.  This probably requires a bit of C/C++ and knowledge of the win32 API.\n\n## Development and testing\n\nSee the [development guide](https://github.com/richfitz/stevedore/blob/master/development.md) if you want to get started developing `stevedore` - it provides pointers to the core objects.\n\n## Package limitations\n\nEndpoints that require \"http hijacking\" are not fully supported (primarily `attach`) but the foundations are there to support this - stdin is likely to be a major hassle though and I'm not sure if it's possible from within R's REPL.\n\n## Installation\n\n`stevedore` can be installed from CRAN using\n\n```r\ninstall.packages(\"stevedore\")\n```\n\nOn windows you will also need `reticulate`\n\n```r\ninstall.packages(\"reticulate\")\n```\n\nYou will also need a python installation and the `docker` and `pypiwin32` packages, which can be installed with pip (see [above](#windows-support)).\n\nOnce installed, find out if everything is set up to use docker by running\n\n```{r, available}\nstevedore::docker_available()\n```\n\nTo install the development version from GitHub, you can use `remotes`:\n\n```r\nremotes::install_github(\"richfitz/stevedore\", upgrade = FALSE)\n```\n\n## Licence\n\nMIT © [Rich FitzJohn](https://github.com/richfitz).\n\nPlease note that this project is released with a [Contributor Code of Conduct](https://github.com/richfitz/stevedore/blob/master/CONDUCT.md). By participating in this project you agree to abide by its terms.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frichfitz%2Fstevedore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frichfitz%2Fstevedore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frichfitz%2Fstevedore/lists"}