Publishing from the RStudio IDE

Note

You must configure your Posit Connect account before attempting to publish with the RStudio IDE. See the Connecting section for information on configuring your Connect account. If you do not have at least the Publisher role within Connect, then you can request permission to publish your own content via the link under Info on the Content page.

General Publishing Instructions

Posit Connect accepts publishing Shiny applications, R Markdown documents, plots, graphs, websites, Jupyter Notebooks, Plumber APIs, and Quarto documents and projects. The blue Publishing icon in the RStudio IDE indicates built-in support for publishing this piece of content.

You can find the blue Publishing icon in the following locations:

• The upper right of the file editor
• The document viewer when viewing a document
• The embedded viewer when running a Shiny application
• The plots pane

Note

The functionality to publish Jupyter Notebooks to Posit Connect is provided by a notebook extension. See the publishing Jupyter Notebooks section for details.

Click on this icon to open a publishing dialog where you can name your content and select additional files to include in the deployment. By default, the RStudio IDE will try to infer the data files and scripts are used in your content. This window lets you refine those file selections.

Most of the time, the IDE is able to determine automatically which files are needed to render your document on Posit Connect. However, there are situations in which it will miss a file (for instance, if it isn’t referenced directly in your document). The Add More… button lets you add files to the bundle that will be sent to Posit Connect so that they will be available on the server when your document is rendered. You can also use the resource_files field in your document’s YAML header to add additional files.

Deployed data files must be in the same directory as your Shiny application or R Markdown document, or in a subdirectory of that location. Files stored elsewhere on your computer will not be available on the remote server and cannot be included in the content bundle.

Click Publish after verifying your settings.

Your first deployment may take a few minutes, as Posit Connect attempts to recreate the R and/or Python environments your content uses locally, and referenced packages are downloaded and installed. These packages are cached on the server; subsequent deployments will be faster.

Not all of your IDE environment can be replicated on the server. Different operating systems or versions of R can occasionally make content behave differently. Package installation failures may require the installation of additional system libraries on Posit Connect.

When the deployment completes, the Posit Connect Settings page for your content will open. You should see your deployed content alongside its settings — for example, a rendered version of your document, or a live instance of your Shiny application.

This page allows you to verify the sharing and visibility of your deployed content. See the Content Settings Panel section for additional information.

Publishing Documents

You can publish R Markdown (.Rmd) and Quarto (.qmd) documents to Posit Connect.

When publishing documents to Posit Connect, you may encounter other deployment options, depending on your content. These are discussed here.

Publishing Destination

RPubs is a service for easily sharing R Markdown documents. RPubs is not related to Posit Connect, and you should always choose “Posit Connect” if you wish to publish your content to Posit Connect.

Publish Source Code

These options display when publishing from the document viewer.

Publishing the document with source code means that your R Markdown or Quarto file (.Rmd or .qmd) will be deployed to Posit Connect. This file will be rendered (usually to HTML) on the server.

Publishing only the finished document means that the HTML file you rendered locally is deployed to Posit Connect.

We recommend publishing your documents with source code, as it allows you to re-render the document with Posit Connect (on a weekly schedule, for example). If the document cannot be rendered by Posit Connect because of files or data sources that are unavailable on the server, choose “Publish finished document only” so others can view your work.

Document Selection

This option appears when publishing an R Markdown or Quarto document from a directory that contains more than one such document. It is possible to link together multiple R Markdown or Quarto documents to make a multi-page document, so this is your chance to indicate that you’ve done this, and to publish all the documents at once. In most cases, you’ll want to publish just the current document.

Collaboration

Some data products will have multiple authors and collaborators who are responsible for managing the content deployed to Posit Connect. The first step to collaboration is sharing and working together on code. We recommend using a version control tool like Git to coordinate collaboration across many users. General information about getting started with git is available elsewhere.

The second step is collaborating on the published data product. To let multiple users maintain and update a single piece of content on Posit Connect, all users should be listed as collaborators on the content.

When content is published to Posit Connect for the first time, a folder named rsconnect is created in your content’s directory.

Note

The rsconnect folder should be added to and tracked by version control, as does not contain any private or secure information. It contains information about the Posit Connect server to which the content has been deployed, including the server and content URLs. This allows content to be published to the same destination in the future, updating that published copy in place.

Once this folder is tracked in version control, a collaborator can clone or check out the code to their development system and make whatever changes or improvements are necessary. When ready to publish, they can click the Publish button in the RStudio IDE, which will use the rsconnect folder to determine where the content has been published. During the publishing process, Posit Connect will check that the authenticated user has collaborator access for this piece of content.

In addition to updating an existing published copy, a publisher can always publish a new copy by selecting “Other Destination…” from the Publish menu. This will create a new piece of content on the selected server, and will leave the original content deployment unmodified.

If you want to surface a single URL for your users despite publishing a new copy on the same server, keep in mind that you can assign a URL to a piece of content, and later assign it to a different piece of content on the server.

Keep in mind that package environments may be different on each developer’s computer. The original author and a collaborator may be using different computers, operating systems, or R versions with different package versions installed. Posit Connect will attempt to reproduce the environment of whoever is publishing the content. Keeping developer environments in sync is not a problem solved by Posit Connect. The renv package and Posit Workbench address this problem more directly.

Note

Watch a video demonstration of basic push-button publishing with collaboration here.

Publishing Content that uses Python and R

The reticulate package allows users to create projects that contain R and Python code. Reticulate can be used across content types including Shiny applications, R Markdown documents, and plumber APIs.

Posit Connect can deploy and host this content, and will automatically restore both the R and Python environments. To deploy:

1. Ensure your server administrator has enabled Python in the Posit Connect configuration, and double check that your project uses a version of Python available on Posit Connect.

2. Projects deployed to Posit Connect should use the RETICULATE_PYTHON environment variable and should not include any references to reticulate::use_python, reticulate::use_virtualenv, or reticulate::use_conda. See an example of switching to RETICULATE_PYTHON.

3. Check to be sure you are using rsconnect version 0.8.13 or above:

   packageVersion('rsconnect')

4. Follow the publishing instructions that are specific to the type of content you are deploying. During deployment, the list of necessary Python packages are sent to Connect. Connect installs these packages into an isolated virtual environment, similar to the approach used for R packages.

Deployment Logs for Content with R and Python Dependencies

When you deploy this type of content, you will see additional logs in both the RStudio Deploy pane and the Posit Connect Logs pane.

In RStudio, you will see something like the following in the Deploy pane, typically after a series of log lines detailing the R environment restore:

Completed packrat build against R version: '3.4.4' Bundle requested Python
version 3.6.7; using /opt/Python/3.6.7/bin/python3.6 which has version 3.6.7
2019/03/05 22:31:15.585067606 Running with python "3.6.7 (default, Dec 11 2018,
22:03:50)  [GCC 4.8.4]" at /opt/Python/3.6.7/bin/python3.6

The first line signals that Posit Connect has completed restoring the R environment. The second line indicates the version of Python discovered in RStudio as well as the matched version available on Posit Connect. These lines will be followed by logging that indicates Posit Connect’s progress in re-creating the Python environment. In some cases, these environments may be cached. For example:

2019/03/05 22:31:15.586051939 Using cached environment: eTZbLgG9EAv8_Nfcrq7LYw
2019/03/05 22:31:16.025098703 Packages in the environment: numpy==1.16.2,
pandas==0.24.1, python-dateutil==2.8.0, pytz==2018.9, six==1.12.0, Completed
python build against Python version: '3.6.7'

In Posit Connect, you will see two log entries each with a unique Job ID, one entry will be titled “R snapshot restore” and the second will be titled “Python environment restore.”

Switching to RETICULATE_PYTHON

If your reticulate code currently uses use_conda, use_virtualenv, or use_python, you’ll need to switch to using the RETICULATE_PYTHON environment variable in order for push-button publishing to work. Any of the reticulate::use functions can be replaced using the environment variable. For example, if you are using a virtual environment located in the project subfolder ./env:

1. Remove the code reticulate::use_virtualenv("./env")

2. Create a .Renviron file in your project containing the line:

   RETICULATE_PYTHON=./env/bin/python`

3. Restart your R session

4. Use reticulate::py_config() to confirm the correct environment is in use

After following these steps you will be able to push-button publish the content to Posit Connect. You can continue project development using the environment variable, you do not need to undo the change to continue working on your code.

During push-button publishing, do not include the .Renviron file.