Publishing from R

This section describes how to publish content to Posit Connect from R. This can be done from the RStudio R Console as an alternative to push-button publishing, or for content types or options that do not support push-button publishing. You can also use this method to publish from R session in a terminal outside of RStudio.

This workflow uses the rsconnect R package. See the rsconnect documentation or the package help for details.

Connect your account

Before publishing, you need to connect to your Posit Connect account. If you need to publish a type of content that doesn’t support push-button publishing or if you want to publish from R code or the R console, follow these instructions to get started.

RStudio provides a push-button publishing experience for some content types. See the Publishing from RStudio section for details.

You need the following information to connect your account:

  • The Posit Connect server URL
  • Your username on the Connect server
  • An API key from the Connect server. See the API Keys section.

First, install the rsconnect R package:

install.packages("rsconnect")

Then use the rsconnect::addServer()1 and rsconnect::connectApiUser() functions to configure the server location and your account:

rsconnect::addServer(
    "https://connect.mydomain.com",
    name = "connect.mydomain.com")
rsconnect::connectApiUser(
    server="connect.mydomain.com",
    account="myusername",
    apiKey="micOXRF89vCQgEr1DovGQMyhmsASz1sf")

Now you’re ready to publish!

Shiny applications

To publish a Shiny application, use the deployApp function, specifying your project’s directory:

rsconnect::deployApp(appDir = '<project-dir>')

For more information:

install.packages('rsconnect')
library(rsconnect)
?rsconnect::deployApp

Plumber APIs

To get started with publishing Plumber API endpoints, create a directory with a plumber.R file defining your endpoints. From the R console, execute the following, replacing <project-dir> with your project’s directory:

rsconnect::deployAPI(api = '<project-dir>')

Quarto content

The rsconnect package can deploy all Quarto content supported by Posit Connect (Quarto support is included in version 0.8.26).

To use rsconnect::deployApp() to deploy Quarto content, you need to pass the path to a Quarto binary to function’s quarto argument:

rsconnect::deployApp(appDir, quarto = "path/to/quarto")

If Quarto is available on your PATH, you can use "quarto". If this doesn’t work, you can use the function quarto_path() from the quarto package:

rsconnect::deployApp(quarto = quarto::quarto_path())

The function rsconnect::writeManifest() can also generate manifests for Quarto content when provided a quarto argument.

R version matching

Posit Connect attempts to find an R installation that is appropriate for published content based on the version constraint specified in the manifest.json file.

Example manifest.json file segment:

"environment": {
    "r": {
        "requires": ">=4.2.0, <5.0" 
    }
}

By default, the rsconnect package generates this section automatically looking up for R version information at an existing DESCRIPTION or renv.lock file, in that order.

Environment section support

Support for manifest.json environment section was introduced in rsconnect v1.3.5.

In cases where rsconnect cannot find an R version specification in any of the environment files when generating the manifest.json, the version constraint is not included in the environment section and the current R version in use is included as is. For this case, Posit Connect falls back to matching the “nearest” versions of R. Your administrator can also enable exact R version matching which is stricter and requires matching major, minor, and patch versions. For more information see the R Version Matching section of the Admin Guide.

Specifying a target image

If your Connect installation uses off-host content execution with Kubernetes, Connect automatically selects an appropriate image to use when building or running your content. However, you can also specify a different image if you prefer, by providing the image argument when writing a manifest or deploying:

rsconnect::writeManifest(...,
    image = "ghcr.io/rstudio/content-base:r4.0.5-py3.8.8-jammy")
rsconnect::deployApp(...,
    image = "ghcr.io/rstudio/content-base:r4.0.5-py3.8.8-jammy")
rsconnect::deployAPI(...,
    image = "ghcr.io/rstudio/content-base:r4.0.5-py3.8.8-jammy")
rsconnect::deployDoc(...,
    image = "ghcr.io/rstudio/content-base:r4.0.5-py3.8.8-jammy")
rsconnect::deploySite(...,
    image = "ghcr.io/rstudio/content-base:r4.0.5-py3.8.8-jammy")

You can only use an image that has been configured by your administrator. You can see a list of available images by logging in to Posit Connect and clicking the Environments button at the top of the page.

If the image you select does not contain appropriate R, Python, or Quarto versions for the content you are deploying, the deployment will fail.

At any time, you can redeploy content without specifying an image (or write a manifest without specifying an image, and deploy the manifest) to go back to allowing Connect to choose an image automatically.

Note

Push-button publishing does not support selecting a specific content image at this time.

Specifying an environment management strategy

Note

Note that the environment management features used in this guide are also applicable for local execution mode with Connect. Off-host execution is not required to use the R and Python environment management features.

Sometimes it is preferable to self-manage R package installation for your system, rather than allowing Connect to install packages for you. This can be useful in situations where many pieces of content share the same set of packages, or if off-host execution is enabled and the packages are already installed in the execution environment image.

rsconnect::writeManifest(..., envManagementR = FALSE)
rsconnect::deployApp(..., envManagementR = FALSE)
rsconnect::deployAPI(..., envManagementR = FALSE)
rsconnect::deployDoc(..., envManagementR = FALSE)
rsconnect::deploySite(..., envManagementR = FALSE)

When environment management is disabled, Connect uses only the packages that are already installed in the system library, no new packages are installed during the deployment. It is up to your administrator to install the required packages in the system library so that they are available for your content at runtime.

At any time, you can redeploy content without specifying an environment management strategy (or write a manifest without specifying, and deploy the manifest) to go back to allowing Connect to choose an environment management strategy based on the application-level and server-level defaults.

Note

Push-button publishing does not support selecting an environment management strategy at this time.

Footnotes

  1. Use rsconnect::addConnectServer rather than rsconnect::addServer when using rsconnect versions before 1.0.0.↩︎