% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dock_from_renv.R
\name{dock_from_renv}
\alias{dock_from_renv}
\title{Create a Dockerfile from an \code{renv.lock} file}
\usage{
dock_from_renv(
  lockfile = "renv.lock",
  distro = NULL,
  FROM = "rocker/r-ver",
  AS = NULL,
  sysreqs = TRUE,
  repos = c(CRAN = "https://p3m.dev/cran/latest"),
  expand = FALSE,
  extra_sysreqs = NULL,
  use_pak = FALSE,
  user = "rstudio",
  dependencies = NA,
  sysreqs_platform = "ubuntu",
  renv_version,
  github_pat = c("none", "build_arg", "secret"),
  renv_paths_cache = NULL
)
}
\arguments{
\item{lockfile}{Path to an \code{renv.lock} file to use as an input.
The \code{basename(lockfile)} must be located at the docker build
context root at \verb{docker build} time, because the generated
Dockerfile emits \verb{COPY <basename(lockfile)> renv.lock}. Validated
as a single string whose basename contains only alphanumerics,
dots, underscores or hyphens (no spaces or shell metacharacters).}

\item{distro}{\itemize{
\item deprecated - only debian/ubuntu based images are supported
}}

\item{FROM}{Docker image to start FROM. Default is \code{"rocker/r-ver"},
which is multi-arch (linux/amd64 + linux/arm64) and gets the
lockfile's R version appended at codegen time (e.g.
\verb{rocker/r-ver:4.5.0}). Pass an already-tagged or
already-digested reference (\verb{rocker/r-ver:4.4.1},
\code{rocker/r-base@sha256:...}) to override the auto-tag; the user's
tag is honoured verbatim, even if it differs from the lockfile's
\code{R$Version}. R-devel and release-candidate users whose lockfile
records \code{r-devel} or \verb{4.5.0-RC} may want to pass an explicit
tag like \code{FROM = "rocker/r-ver:devel"} to control which base
image is pulled.
Validated as a Docker image reference
(\verb{<host>[:<port>]/<image>[:<tag>][@sha256:<hex>]}); other values
raise an error to prevent shell-metacharacter injection into the
generated FROM directive.}

\item{AS}{The AS of the Dockerfile. Default is \code{NULL}. When non-NULL,
validated as a simple build-stage name (\verb{^[a-zA-Z0-9][a-zA-Z0-9._-]*$}).}

\item{sysreqs}{boolean. If \code{TRUE}, the Dockerfile will contain sysreq installation.}

\item{repos}{character. The URL(s) of the repositories to use for
\code{options("repos")}. Default is
\code{c(CRAN = "https://p3m.dev/cran/latest")} (Posit Public Package
Manager). When the URL is recognized as a PPM host
(\code{packagemanager.posit.co}, \code{packagemanager.rstudio.com}, or
\code{p3m.dev}), the codegen rewrites it to the
\verb{__linux__/$VERSION_CODENAME/} shape so the build pulls Linux
binaries (5-10x faster than building from source). Each value
must look like an http(s) URL (no quotes, spaces or newlines);
each name (when set) must be a simple identifier
(\verb{^[A-Za-z][A-Za-z0-9._-]*$}). Other values raise an error to
prevent injection into the generated \verb{echo "options(...)"} shell
command.}

\item{expand}{boolean. If \code{TRUE} each system requirement will have its own \code{RUN} line.}

\item{extra_sysreqs}{character vector. Extra debian system requirements.
Will be installed with apt-get install. Each entry must be a Debian
package name (\verb{^[a-z0-9][a-z0-9.+-]+$}); other values raise an error
to prevent injection into the generated apt-get RUN.}

\item{use_pak}{boolean. If \code{TRUE} use pak to deal with dependencies
during \code{renv::restore()}. FALSE by default. Must be a single
\code{TRUE} or \code{FALSE} (no \code{NA}, no vector).}

\item{user}{Name of the user the runtime container drops privilege
to before the \code{renv::restore()} step (and therefore at runtime).
Default is \code{"rstudio"} so the generated image runs as a non-root
user out of the box, which is the recommended security posture.

The Dockerfile is emitted in two halves: every step that needs
root (apt-get, R install commands, \code{chown} of the renv cache)
runs first; then a \verb{USER <user>} directive drops privilege; then
the \code{renv::restore()} cache-mount RUN happens.

To make this work regardless of the FROM image, the package
emits a defensive \verb{RUN id -u <user> >/dev/null 2>&1 || useradd -m -d /home/<user> -s /bin/bash <user>} early. On
rocker/* images the \code{useradd} is a no-op (the user already
exists); on \code{r-base}, \verb{ubuntu:*}, \verb{debian:*} it creates the user
with the standard home directory.

Pass \code{user = NULL} to opt out: no \code{USER} directive is emitted
and the container runs as root (the previous behaviour).
Pass any other string to use that user instead of \code{rstudio}.
Custom homes (e.g. \verb{/srv/myapp}) require also passing an
explicit \code{renv_paths_cache}.

debian/ubuntu images only (\code{useradd} is the standard form);
for alpine-based images you must pass \code{user = NULL} and handle
user creation yourself with the alpine-native \code{adduser}.

The argument is validated at codegen time against
\verb{^[a-zA-Z_][a-zA-Z0-9_-]\{0,31\}$} (POSIX-style username, max 32
chars, no shell metacharacters). Other values raise an error
to prevent metacharacter injection into the generated \code{RUN}
commands.}

\item{dependencies}{What kinds of dependencies to install. Most commonly
one of the following values:
\itemize{
\item \code{NA}: only required (hard) dependencies,
\item \code{TRUE}: required dependencies plus optional and development
dependencies,
\item \code{FALSE}: do not install any dependencies. (You might end up with a
non-working package, and/or the installation might fail.)
}}

\item{sysreqs_platform}{System requirements platform.\code{ubuntu} by default. If \code{NULL}, then the  current platform is used. Can be : "ubuntu-22.04" if needed to fit with the \code{FROM} Operating System. Only debian or ubuntu based images are supported}

\item{renv_version}{character or \code{NULL}. The renv version to install.
The argument has three distinct modes, deliberately encoded with
the missing-vs-\code{NULL} distinction:
\itemize{
\item \strong{not supplied (default)}: read the renv version from the
\code{renv.lock} file. If the lockfile does not pin renv either,
the latest available version is installed.
\item \code{NULL} (explicit): always install the latest renv from the
configured repos, even when the lockfile pins a specific
version.
\item a character string such as \code{"1.0.0"}: install that specific
version regardless of what the lockfile says.
}

When supplied as a string, validated as a version-like token
(\verb{^[0-9]+(\\.[0-9]+)\{0,3\}([-.][a-zA-Z0-9]+)?$}).}

\item{github_pat}{character. How to provide a GitHub PAT to
\code{renv::restore()} for private dependency repositories. One of
\code{"none"} (default; the generated Dockerfile does not reference
any PAT), \code{"build_arg"} (emit \verb{ARG GITHUB_PAT} + \code{ENV} propagation;
pass with \verb{--build-arg GITHUB_PAT=$GITHUB_PAT}; the PAT will be
visible in the image metadata), or \code{"secret"} (BuildKit secret
mount on the \code{renv::restore()} RUN; the PAT is never persisted in
the image; requires BuildKit, so pass with
\verb{DOCKER_BUILDKIT=1 docker build --secret id=github_pat,env=GITHUB_PAT ...}).}

\item{renv_paths_cache}{character or \code{NULL}. Path used as the
default of the \code{RENV_PATHS_CACHE} build-arg, propagated as an
\code{ENV} variable, and used as the cache mount target for
\code{renv::restore()}. Lets users override the renv cache location
at image build time via \verb{--build-arg RENV_PATHS_CACHE=...}.

When \code{NULL} (the default), the cache path is derived from
\code{user}: \verb{/root/.cache/R/renv} when \code{user = NULL}, and
\verb{/home/<user>/.cache/R/renv} when \code{user} is a non-root username.
Pass an explicit string to override the convention (e.g. for
custom-home users like \code{user = "myapp"} with home at
\verb{/srv/myapp}, pass \code{renv_paths_cache = "/srv/myapp/.cache/R/renv"}).

In all cases (\code{user = NULL} excepted), the generated Dockerfile
emits a single \verb{RUN mkdir -p "$\{RENV_PATHS_CACHE\}" && chown -R <user>:<user> "$\{RENV_PATHS_CACHE\}"}
step right before the \verb{USER <user>} directive so the cache mount
target is writable from the un-privileged user. The cache path
is double-quoted at shell expansion time so a build-arg
override containing whitespace cannot break the command.}
}
\value{
A R6 object of class \code{Dockerfile}.
}
\description{
Create a Dockerfile from an \code{renv.lock} file
}
\details{
System requirements for packages are provided
through RStudio Package Manager via the pak
package. The install commands provided from pak
are added as \code{RUN} directives within the \code{Dockerfile}.

The R version is taken from the \code{renv.lock} file.
Packages are installed using \code{renv::restore()} which ensures
that the proper package version and source is used when installed.
}
\examples{
\dontrun{
dock <- dock_from_renv("renv.lock")
dock$write("Dockerfile")
}
}
