dockerWrapper

Overview

This vignette describes the Docker helper functions in OmopStudyBuilder:

• dockeriseStudy() builds a Docker image for your study
• runRStudio() starts an interactive RStudio Server session inside the image
• runStudy() runs your study script in automated mode (streaming logs)
• stopStudy() stops containers started by runRStudio()/runStudy()
• pushDockerImage() tags and pushes your image to Docker Hub

All Docker calls require Docker to be installed and the Docker daemon to be running.

Build an image

dockeriseStudy() expects an renv.lock (and renv activation files) in the directory you point it at. By default it will also snapshot your dependencies before building.

# From the studyCode folder (or pass path=...)
dockeriseStudy(
  image_name = "my-study",
  path = "./studyCode",
  useRStudio = FALSE
)

If you want runRStudio(), build with an RStudio base image:

dockeriseStudy(
  image_name = "my-study",
  path = "./studyCode",
  useRStudio = TRUE
)

If your renv.lock includes GitHub packages and you hit GitHub rate limits during the build, pass a token:

dockeriseStudy(
  path = "./studyCode",
  github_token = Sys.getenv("GITHUB_PAT")
)

Run interactively (RStudio Server)

runRStudio() runs the Docker image and opens a browser to the RStudio Server URL. Results are written to results_path on your host.

runRStudio(
  image_name = "my-study",
  results_path = "./results"
)

To pass runtime settings to the container, create a .env file in your working directory and it will be used automatically (or provide env_file = "path/to/.env").

Run in automated mode

runStudy() executes an R script in the container (default codeToRun.R) and streams stdout/stderr to your console.

runStudy(
  image_name = "my-study",
  results_path = "./results",
  data_path = "/path/to/cdm/data",
  script_path = "codeToRun.R"
)

Stop containers

Use stopStudy() to stop containers started by runRStudio() and/or runStudy().

stopStudy(image_name = "my-study")

Push to Docker Hub

pushDockerImage() will tag image_name:latest and push it to a Docker Hub repository.

pushDockerImage(
  image_name = "my-study",
  repo = "yourusername/my-study"
)