jetty: Execute R in a 'Docker' Context

Description

The goal of 'jetty' is to execute R functions and code snippets in an isolated R subprocess within a 'Docker' container and return the evaluated results to the local R session. 'jetty' can install necessary packages at runtime and seamlessly propagates errors and outputs from the 'Docker' subprocess back to the main session. 'jetty' is primarily designed for sandboxed testing and quick execution of example code.

Author(s)

Maintainer: Daniel Molitor molitdj97@gmail.com [copyright holder]

See Also

Useful links:

• https://github.com/dmolitor/jetty

• http://www.dmolitor.com/jetty/

• Report bugs at https://github.com/dmolitor/jetty/issues

Execute an R expression inside a Docker container

Description

This function is somewhat similar in spirit to callr::r() in that the user can pass a function (or a code block) to be evaluated. This code will be executed within the context of a Docker container and the result will be returned within the local R session.

Usage

run(
  func,
  args = list(),
  image = paste0("r-base:", r_version()),
  stdout = "",
  stderr = "",
  install_dependencies = FALSE,
  r_profile = jetty_r_profile(),
  r_environ = jetty_r_environ(),
  debug = FALSE
)

Arguments

Value

Value of the evaluated expression.

Side effects

It is important to note that some side effects, e.g. plotting, may be lost since these are being screamed into the void of the Docker container. However, the user has full control over the 'stdterr' and 'stdout' of the R sub-process running in the Docker container, and so side effects such as messages, warnings, and printed output can be directed to the console or captured by the user.

It is also crucial to note that actions on the local file system will not work with jetty sub-processes. For example, reading or writing files to/from the local file system will fail since the R sub-process within the Docker container does not have access to the local file system.

Error handling

jetty will propagate errors from the Docker process to the main process. That is, if an error is thrown in the Docker process, an error with the same message will be thrown in the main process. However, because of the somewhat isolated nature of the local process and the Docker process, calling functions such as base::traceback() and rlang::last_trace() will not print the callstack of the uncaught error as that has (in its current form) been lost in the Docker void.

Examples

## Not run: 
run(
  {
    mtcars <- mtcars |>
      transform(cyl = as.factor(cyl))
    model <- lm(mpg ~ ., data = mtcars)
    model
  }
)

# A code snippet that requires packages to be installed
run(
  {
    mtcars <- mtcars |> 
      dplyr::mutate(cyl = as.factor(cyl))
    model <- lm(mpg ~ ., data = mtcars)
    model
  },
  install_dependencies = TRUE
)

# This will error since the `praise` package is not installed
run(function() praise::praise())

# Explicitly tell jetty to ignore an existing .Rprofile
run(function() summary(cars), r_profile = NULL)

## End(Not run)

Execute an R script inside a Docker container

Description

This function is somewhat similar in spirit to callr::rscript() in that the user can specify an R script to be executed within the context of a Docker container.

Usage

run_script(
  file,
  ...,
  context = dirname(file),
  image = paste0("r-base:", r_version()),
  stdout = "",
  stderr = "",
  install_dependencies = FALSE,
  r_profile = jetty_r_profile(),
  r_environ = jetty_r_environ(),
  debug = FALSE
)

Arguments

Details

NOTE: this feature is still fairly experimental. It will NOT work on Windows. It is only made to be compatible with MacOS and Linux.

Value

The value of the last evaluated expression in the script.

Interaction with the local file system

The user will be asked to specify a context (local directory) for executing the R script. jetty mounts this directory to the Docker container, allowing the script to interact with files within it (read/write). Attempts to access files outside the context directory will cause the script to fail. Ensure the context directory includes all files needed for the script to run.

Error handling

run_script will handle errors using the same mechanism as run. See that documentation for more details.

Examples

## Not run: 
# Execute a simple script that has no package dependencies
run_script(file = here::here("code/analysis_script.R"))

# Execute a script that needs access to the entire analysis directory
run_script(
  file = here::here("code/analysis_script.R"),
  context = here::here()
)

# Execute a script that needs access to the entire analysis directory
# and relies on external packages
run_script(
  file = here::here("code/analysis_script.R"),
  context = here::here(),
  install_dependencies = TRUE
)

# Execute a script and explicitly ignore an existing .Rprofile
run_script(
  file = here::here("code/analysis_script.R"),
  r_profile = NULL
)

## End(Not run)