E Using Continuous Integration to Deploy Content

E.1 Overview

It is possible to use the rsconnect R package to programmatically deploy content to a Connect server. This is particularly useful when combined with a continuous integration (CI) server that builds and deploys your content.

RStudio Connect includes experimental HTTP APIs that let you build your own deployment workflows. Those APIs will replace the rsconnect package as the preferred way to perform programmatic deployment.

The Deploying Content recipes in the RStudio Connect API Cookbook will get you started with the content APIs. All of the Content API endpoints are described in the RStudio Connect API Reference.

E.2 Prerequisites

Currently, it is only feasible to use a CI server to update content that you originally published from the same server. You cannot update content that you published from elsewhere. To clarify, the CI server must perform both the initial deployment and subsequent updates of the application.

Configuring a CI server to deploy content with rsconnect requires that you log in to the CI server with the credentials the CI server uses to run rsconnect. For example, if your CI server uses the jenkins account, you need to log in as jenkins to configure rsconnect for the CI server.

You must be familiar with deploying content with rsconnect. Please see D for more information.

E.3 Configuring a CI Server to Deploy Content to Connect

E.3.1 Installing rsconnect

The rsconnect package is used to deploy content to Connect. Install it with the following command in the R console. In practice, rsconnect may already be available.

install.packages("rsconnect")

E.3.2 Configuring rsconnect

Configuring rsconnect requires a user home directory. In this use case, a valid home directory is required for the jenkins user account.

You must configure rsconnect for the user account that will be used by the CI server to deploy content with rsconnect. In this document, we assume that this user is jenkins.

sudo su jenkins

Next, while running as jenkins, run R and issue the following commands in the R console:

library(rsconnect)
addConnectServer("http://myserveraddress:3939", "mylocaldeployserver")
connectUser(server="mylocaldeployserver")

The rsconnect server name, mylocaldeployserver, is an arbitrary name that is used to identify a Connect server when using rsconnect. You can choose any name you wish.

After the last command, you will see output similar to this:

A browser window should open; if it doesn’t, you may authenticate manually by visiting http://myserveraddress:3939/__login__?url=......

Waiting for authentication…

Copy the URL in the output above, then paste it into a Web browser and authenticate with the Connect user credentials for your CI server. In this example, we assume that you wish to deploy content with the ci-server Connect acount.

After successfully connecting the ci-server Connect account to rsconnect, you will see this message at the R console:

Account registered successfully: CI Server (ci-server)

The server and account information are persisted to configuration files on the server in the jenkins user’s home directory:

/home/jenkins/.config/R/connect/servers/mylocaldeployserver.dcf
/home/jenkins/.config/R/connect/accounts/mylocaldeployserver/connectuser.dcf

E.3.3 Deploying Content with rsconnect

Now rsconnect is configured to use the ci-server Connect account when running with the jenkins server account.

E.3.4 Package and R Version Compatibility

rsconnect will use the package libraries and the R installation available on the CI server to create the manifest used by Connect. It is crucial that the environment on the CI server is compatible with the content you are deploying. Ideally, you should maintain the same R version, the same available packages, and the same package versions that you use in development.

E.3.5 CRAN Note

If you don’t already have it in an .RProfile, be sure to specify a default CRAN repository in your application before issuing the rsconnect command to deploy content. For example:

options(repos=c(CRAN="https://cran.rstudio.com"))
deployDoc(doc="out.Rmd", appName="ServerDeployedDoc",
                     account="ci-server", server="mylocaldeployserver")

Please note that Connect content must be published before it is publicly available. This means that you must log in to Connect and publish the content after the initial deployment. Subsequent automated deployments of the same content are automatically published and require no manual intervention.

E.4 Warning and Security Information

A CI server account that is configured to deploy content to Connect can deploy additional content to Connect without further authentication.

For example, Bob logs in to a server console as Unix user jenkins, which is the account used by his CI server. Bob then configures rsconnect to deploy content. During the authorization step, Bob signs in to Connect as a publisher with user name ci-server. Now, any other CI processes running on this server under the jenkins user account can deploy additional content using the Connect user ci-server.