Using Continuous Integration to Deploy Content#
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.
Note
Posit 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 Posit Connect API Cookbook will get you started with the content APIs. All of the Content API endpoints are described in the Posit Connect API Reference.
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 the
Deployment Guide appendix for more information.
Configuring a CI Server to Deploy Content to Connect#
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")
Configuring rsconnect#
Note
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")
Note
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
Deploying Content with rsconnect#
Now rsconnect is configured to use the ci-server Connect account
when running with the jenkins server account.
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.
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"))
rsconnect::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.
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.