Skip to contents

Render Containerized R Markdown Documents

Source: R/render_docker.R
render_docker.Rd

Render R Markdown documents using Docker.

Usage

render_docker(
  input = NULL,
  tag = NULL,
  container_name = NULL,
  cache = TRUE,
  build_args = NULL,
  run_args = NULL,
  prune = TRUE,
  prune_info = TRUE,
  dry_run = FALSE,
  ...
)

drender(...)

Arguments

input

Input file to render in Docker container.

tag

Docker image name to build, sent as docker argument -t. If not specified, it will use the same name as the input file.

container_name

Docker container name to run. If not specified, will use a randomly generated name.

cache

Logical. Controls the --no-cache argument in docker run. Setting this to be TRUE can accelerate the rendering speed substantially for repeated/interactive rendering since the Docker image layers will be cached, with only the changed (knitr related) image layer being updated. Default is TRUE.

build_args

A character string specifying additional docker build arguments. For example, --pull=true -m="1024m" --memory-swap="-1".

run_args

A character string specifying additional docker run arguments. For example, --privileged=true.

prune

Logical. Should we clean up all dangling containers, volumes, networks, and images in case the rendering was not successful? Default is TRUE.

prune_info

Logical. Should we save the Docker container and image information to a YAML file (name ended with .docker.yml) for manual pruning or inspections later? Default is TRUE.

dry_run

Preview the Docker commands but do not run them? Useful for debugging purposes. Default is FALSE.

...

Additional arguments passed to render.

Value

  • A list containing the image name, container name, and Docker commands will be returned.

  • An YAML file ending with .docker.yml storing the image name, container name, and Docker commands for rendering this document will be written to the directory of the input file.

  • The rendered output will be written to the directory of the input file.

Details

Before using this function, please run lift on the RMD document first to generate the Dockerfile.

After a successful rendering, you will be able to clean up the Docker image with prune_image.

Please see vignette('liftr-intro') for details of the extended YAML metadata format and system requirements for writing and rendering containerized R Markdown documents.

Examples

# copy example file
dir_example = paste0(tempdir(), "/liftr-tidyverse/")
dir.create(dir_example)
file.copy(system.file("examples/liftr-tidyverse.Rmd", package = "liftr"), dir_example)
#> [1] TRUE

# containerization
input = paste0(dir_example, "liftr-tidyverse.Rmd")
lift(input)

if (FALSE) {
# print the Docker commands first
render_docker(input, dry_run = TRUE)

# render the document with Docker
render_docker(input)

# view rendered document
browseURL(paste0(dir_example, "liftr-tidyverse.pdf"))

# remove the generated Docker image
prune_image(paste0(dir_example, "liftr-tidyverse.docker.yml"))}