o2rproject/containerit repository overview

⁠containerit

containerit packages R script/session/workspace and all dependencies as a Docker⁠ container by automagically generating a suitable Dockerfile. The package’s website is https://o2r.info/containerit/⁠.

⁠Prerequisites

• containerit only fully works if you have Docker⁠ installed and is only tested with Docker Engine - Community⁠ (previously called Docker Community Edition or Docker CE).
• R (>= 3.5.0) is needed so that some dependencies (e.g. BiocManager) are available; older versions of R predate the development of the package and were never tested.

⁠Quick start

⁠Try out containerit in a container

You can spin up a Docker container with containerit pre-installed if you want to try out the package. The default of the containerit images on Docker Hub⁠ is to start plain R, but you can also start an with RStudio⁠ session in a browser.

Note: The geospatial variant is used so that examples from containerit vignettes are likely to work. For a minimal Dockerfile to run containerit, see inst/docker/minimal/Dockerfile.

docker run --rm -it -e PASSWORD=o2r -p 8787:8787 o2rproject/containerit:geospatial /init

Now go to http://localhost:8787⁠ and log in with the user rstudio and password o2r. Continue in section Use⁠.

⁠Install

Installation is only possible from GitHub:

# install.packages("remotes")
remotes::install_github("o2r-project/containerit")

⁠Use

containerit can create Dockerfile objects in R and render them as Dockerfile instructions based on session information objects or runnable R files (.R, .Rmd).

suppressPackageStartupMessages(library("containerit"))
my_dockerfile <- containerit::dockerfile(from = utils::sessionInfo())
#> INFO [2021-06-25 11:10:38] Created Dockerfile-Object based on sessionInfo

print(my_dockerfile)
#> FROM rocker/r-ver:4.1.0
#> LABEL maintainer="daniel"
#> WORKDIR /payload/
#> CMD ["R"]

You can disable logging:

futile.logger::flog.threshold(futile.logger::ERROR)

Now we create a Dockerfile for a specific R version and a given R Markdown file. The option filter_baseimage_pkgs is used to not add any packages already available in the base image, which can save a lot of build time.

rmd_dockerfile <- containerit::dockerfile(from = "inst/demo.Rmd",
                                          image = "rocker/verse:3.5.2",
                                          maintainer = "o2r",
                                          filter_baseimage_pkgs = TRUE)
#> Detected API version '1.41' is above max version '1.39'; downgrading
#> Detected API version '1.41' is above max version '1.39'; downgrading
print(rmd_dockerfile)
#> FROM rocker/verse:3.5.2
#> LABEL maintainer="o2r"
#> # CRAN packages skipped because they are in the base image: knitr
#> RUN ["install2.r", "fortunes"]
#> WORKDIR /payload/
#> CMD ["R"]

For extended instructions, see the vignettes at in the directory vignettes/, which are readable online at https://o2r.info/containerit/articles/⁠.

⁠Images

Images are available starting from different base images. All images are also available with version tags.

The Dockerfiles are available in the directory inst/docker/Dockerfile.

⁠verse

docker inspect o2rproject/containerit

Base image: rocker/verse:4.0.5

⁠geospatial

docker inspect o2rproject/containerit:geospatial

Base image: rocker/geospatial:4.0.5

⁠RStudio Add-in

RStudio Addins⁠ allow to create interactive user interfaces for the RStudio development environment. Courtesy of a great contribution by a group of enthusiasts⁠ at the ROpenSci OZ Unconference 2018⁠, there are several forms to quickly create Dockefiles from different use cases, e.g. the current session, a vector of expressions, or a script file.

⁠Contribute

All help is welcome: asking questions, providing documentation, testing, or even development.

Please note that this project is released with a Contributor Code of Conduct⁠. By participating in this project you agree to abide by its terms.

See CONTRIBUTING.md⁠ for details.

⁠Development

r-hub builder⁠ is great for running checks, e.g. before submitting to CRAN and on other operating systems.

library("rhub")
rhub::check_for_cran()
rhub::check_on_windows()

You can build the pkgdown⁠ site with

pkgdown::build_site()

You can build the Docker images locally with the current development version using the following commands.

docker build --tag containerit:dev --file inst/docker/Dockerfile.local .
docker build --tag containerit:geospatial-dev --file inst/docker/geospatial/Dockerfile.local .

You can use pre-commit hooks⁠ to avoid some mistakes.

A codemeta⁠ file, codemeta.json, with metadata about the package and its dependencies is generated automatically when this document is compiled.

codemetar::write_codemeta(".")
#> Added codemeta.json to .Rbuildignore
#> codemetar has the highest opinion of this R package :-)

⁠Citation

To cite containerit in publications use:

  Nüst, D. and Hinz, M. (2019). containerit: Generating Dockerfiles for
  reproducible research with R. Journal of Open Source Software, 4(40),
  1603, https://doi.org/10.21105/joss.01603

A BibTeX entry for LaTeX users is

  @Article{,
    title = {{containerit: Generating Dockerfiles for reproducible research with R}},
    author = {Daniel Nüst and Matthias Hinz},
    journal = {{Journal of Open Source Software}},
    year = {2019},
    month = {8},
    volume = {4},
    number = {40},
    pages = {1603},
    doi = {10.21105/joss.01603},
    url = {https://doi.org/10.21105/joss.01603},
  }

⁠License

containerit is licensed under GNU General Public License, version 3, see file LICENSE.

Copyright (C) 2019 - o2r project.