Publishing from the RStudio IDE

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 Connect is provided by a notebook extension. See the publishing Jupyter Notebooks section for details.

Click on the publishing 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 tries 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 automatically determine which files are needed to render your document on Connect. However, there are situations in which it misses files (for instance, if the file is not referenced directly in your document). The Add More… button lets you add files to the bundle that are sent to Connect so that they are 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 are not available on the remote server and cannot be included in the content bundle.

Click Publish after verifying your settings.

Your first deployment can take a few minutes, as 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 Connect Settings page for your content opens. Your deployed content should display 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 Connect, you might 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. You should always select Posit Connect if you wish to publish your content to Connect.

Publish source code

The Publish document with source code and Publish finished document only 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 is rendered (usually to HTML) on the server.

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

We recommend publishing your documents with source code, as it allows you to re-render the document with Connect (on a weekly schedule, for example). If the document cannot be rendered by 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

The Publish just this document and Publish all documents in the directory options appear 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 will want to publish just the current document.

Collaboration

Some data products 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 Connect, all users should be listed as collaborators on the content.

When content is published to 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 it does not contain any private or secure information. The folder contains information about the 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 uses the rsconnect folder to determine where the content has been published. During the publishing process, Connect checks 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 creates a new piece of content on the selected server, and leaves 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 might be different on each developer’s computer. The original author and a collaborator might be using different computers, operating systems, or R versions with different package versions installed. Connect attempts to reproduce the environment of whoever is publishing the content. Keeping developer environments in sync is not a problem solved by 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 Python and R 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 automatically restores both the Python and R environments. To deploy:

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

2. Projects deployed to 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. Verify that 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 Python and R dependencies

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

In RStudio, something similar to the following example displays 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 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 Connect. These lines are followed by logging that indicates the progress Connect has made 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 Connect, two log entries open, each with a unique Job ID, one entry is titled “R snapshot restore” and the second is titled “Python environment restore.”

Switching to RETICULATE_PYTHON

If your reticulate code currently uses use_conda, use_virtualenv, or use_python, you 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 can push-button publish the content to Connect. You can continue project development using the environment variable, and you do not need to undo the change to continue working on your code.

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