use_docker {pracpac}

Use docker packaging tools

Description

Wrapper function around other pracpac functions. See help for the functions linked below for detail on individual functions. All arguments to use_docker() are passed to downstream functions. use_docker() will sequentially run:

1. pkg_info to get information about the current R package.

2. create_docker_dir to create the ⁠docker/⁠ directory in the specified location, if it doesn't already exist.

3. renv_deps (if use_renv=TRUE, the default) to capture package dependencies with renv and create an renv.lock file

4. add_dockerfile to create a Dockerfile using template specified by use_case

5. add_assets depending on the use_case

6. build_pkg to build the current R package source .tar.gz, and place it into the ⁠docker/⁠ directory

7. build_image optional, default FALSE; if TRUE, will build the Docker image.

The default build=FALSE means that everything up to build_image() is run, but the image is not actually built. Instead, use_docker() will message the ⁠docker build⁠ command, and return that string in ⁠$buildcmd⁠ in the invisibly returned output.

See vignette("use-cases", package="pracpac") for details on use cases.

Usage

use_docker(
  pkg_path = ".",
  img_path = NULL,
  use_renv = TRUE,
  use_case = "default",
  base_image = NULL,
  other_packages = NULL,
  build = FALSE,
  repos = NULL,
  overwrite_assets = TRUE,
  overwrite_renv = TRUE,
  consent_renv = TRUE
)

Arguments

pkg_path

Path to the package directory. Default is "." for the current working directory, which assumes developer is working in R package root. However, this can be set to another path as needed.

img_path

Path to the write the docker image definition contents. The default NULL will use ⁠docker/⁠ as a subdirectory of the pkg_path.

use_renv

Logical; use renv? Defaults to TRUE. If FALSE, package dependencies are scraped from the DESCRIPTION file without version information.

use_case

Name of the use case. Defaults to "default", which only uses the base boilerplate.

base_image

Name of the base image to start FROM. Default is NULL and the base image will be derived based on use_case. Optionally override this by setting the name of the base image (including tag if desired).

other_packages

Vector of other packages to be included in renv lock file; default is NULL.

build

Logical as to whether or not the image should be built. Default is TRUE, and if FALSE the ⁠docker build⁠ command will be messaged. Setting build=FALSE could be useful if additional ⁠docker build⁠ options or different tags are desired. In either case the ⁠docker build⁠ command will be returned invisibly.

repos

Option to override the repos used for installing packages with renv by passing name of repository. Only used if use_renv = TRUE. Default is NULL meaning that the repos specified in renv lockfile will remain as-is and not be overridden.

overwrite_assets

Logical; should existing asset files should be overwritten? Default is TRUE.

overwrite_renv

Logical; should an existing lock file should be overwritten? Default is TRUE; ignored if use_renv = TRUE.

consent_renv

Logical; give renv consent in this session with options(renv.consent = TRUE)? Default is TRUE. See renv::consent for details.

Value

Invisibly returns a list with information about the package (⁠$info⁠) and the ⁠docker build⁠ command (⁠$buildcmd⁠). Primarily called for side effect. Creates ⁠docker/⁠ directory, identifies renv dependencies and creates lock file (if use_renv = TRUE), writes Dockerfile, builds package tar.gz, moves all relevant assets to the ⁠docker/⁠ directory, and builds Docker image (if build = TRUE).

Examples

## Not run: 

# Specify path to example package source and copy to tempdir()
# Note that in practice you do not need to copy to a tempdir()
# And in fact it may be easiest to use pracpac relative to your package directory root
ex_pkg_src <- system.file("hellow", package = "pracpac", mustWork = TRUE)
file.copy(from = ex_pkg_src, to = tempdir(), recursive = TRUE)

# Run use_docker to create Docker directory and assets for the example package
use_docker(pkg_path = file.path(tempdir(), "hellow"))
# To not use renv
use_docker(pkg_path = file.path(tempdir(), "hellow"), use_renv=FALSE)
# To specify a use case
use_docker(pkg_path = file.path(tempdir(), "hellow"), use_case="pipeline")
# To overwrite the default base image
use_docker(pkg_path = file.path(tempdir(), "hellow"), base_image="alpine:latest")

## End(Not run)