# dockerWrapper

    library(OmopStudyBuilder)

## 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"
    )