Shiny Server Pro to Posit Connect Migration Process

An overview to review and migrate from Shiny Server Pro to Posit Connect.

Return to How-To Guides page

Overview

This guide provides a feature and configuration review to help you understand:

  • The differences between the SSP and Connect in how applications are deployed and managed
  • Identifies additional functionality that your organization can utilize with Connect.

Additionally, it provides a framework for migrating applications from Shiny Server Pro (SSP) to Posit Connect.

The intended audience is your administration team. However, collaboration with your organization’s data scientists is stronly recommended/required.

Why Connect?

Connect was developed as the evolution of SSP, because of various limitations within SSP’s architecture. These shortcomings (like the inability to scale individual applications and natively integrate with standard infrastructure scaling and high-availability architectures, such as Kubernetes) have been remedied by writing Connect from the ground up.

Warning

Reflecting the maturity of Connect as a product, Posit is discontinuing the sales of SSP to new customers and initiated the End of Life (EoL) cycle. Posit is focusing its engineering efforts on providing the best experience in deploying all forms of R and Python data products.

Feature comparison

The following feature comparison spans Shiny Server Open Source (SSOS), Shiny Server Pro (SSP) and Connect.

Feature SSOS SSP Connect
Multiple independent applications ✅ ✅ ✅
User developed Shiny application hosting ✅ ✅ ✅
Auto restart Shiny applications ✅ ✅ ✅
Authenticate users to Shiny applications ❌ ✅ ✅
Scale applications to multiple processes ❌ ✅ ✅
Enable SSL encryption ❌ ✅ ✅
Shiny application monitoring ❌ ✅ ✅
Push-button publishing ❌ ❌ ✅
Built-in content versioning ❌ ❌ ✅
Expanded SSO options ❌ ❌ ✅
Git-backed content ❌ ❌ ✅
Scheduled jobs ❌ ❌ ✅
Off-Host execution ❌ ❌ ✅
Shiny for Python ✅ ❌ ✅
Other Python native and API content types ❌ ❌ ✅
Support for Quarto hosting and scheduling ❌ ❌ ✅

SSP migration preparation

In collaboration with your data scientists, consider the following factors prior to migrating from SSP to Connect, several factors need to be considered by the administration team:

  • Identify the scope of the migration:
    • Identify the applications to migrate.
    • Understand the data scientists’ current application deployment workflow.
    • Identify a plan for the cutover or parallel deployment of applications on an application-by-application basis, i.e., can specific applications be moved to Connect while the old SSP server is still active, or is a hard cutover from Shiny SSP to Connect required?
  • Verify the installation details for your environment, this includes:
    • Reviewing your SSP configuration file, normally located at /etc/shiny-server/shiny-server.conf to determine what options were used in the configuration and their parallel settings and configurations in Connect. A detailed mapping is included at the Appendix but review some critical in the table below:
SSP Setting Connect Setting (Equivalent) Description
run_as Applications.RunAs run_as defines the Linux user running the application at the location specified in this block. This is important because some applications that use this user’s Linux file system permissions to access data files on local or shared drives.
site_dir N/A Defines a location that hosts an entire directory tree (Shiny Apps and static assets) that SSP hosts. No direct parallel in Connect exists because each application published to Connect is standalone and hosted from its own directory.
app_dir N/A Specifies the directory that contains a single application to be hosted by SSP. There isn’t a direct parallel in Connect, but this option is closest to how Connect individually separates published applications from one another.
user_dirs N/A Specifies an entire directory of user-owned subdirectories that contain applications and content to host. Since Connect treats each application as standalone content, this option doesn’t have a direct parallel. However, this setting is important during the migration because user_dirs specifies where users may have stored their applications that need to be republished to Connect.
Authentication Authentication Since Connect supports most modern Single-Sign On (SSO) methods, the migration may be the best opportunity to change authentication methods. The authentication method SSP uses is important because that could influence the authentication method used in Connect.
r_path R Versions The r_path SSP configuration setting identifies the location of R installed on the server and used to determine the version of R used by SSP. Install this version of R on your Connect server to maintain compatibility with the applications you migrate.
allow_app_override Content Settings If the allow_app_override setting is set to true, the SSP administrator should review the application location in question for files called .shiny_app.conf, which can include critical configuration settings that may need to be replicated to your Connect server. Some configuration directives to look for are r_path, required_user, and required_group.
server_name Server.Address SSP supports serving content at multiple hostnames, and the server_name directive can identify the hostnames that are used for routing to specific applications. Connect only supports hosting content at one URL, with customizable URIs that can replace the server_name directive.

Install Connect

Posit recommends installing Connect on a new server for two key reasons:

  1. Deploying Connect to a new server allows you to deploy and test migrating your applications in parallel without the possibility of impacting your production instance of SSP.
  2. Most instances of SSP are deployed on Linux servers with operating systems that are nearing end of life (EoL), such as Ubuntu Bionic 18.04 or Red Hat/CentOS 7, and the migration to Connect provides the opportunity to upgrade to a supported operating system.

Use the Posit Connect Admin Guide for installation and configuration of Connect.

Shiny application migration options

Getting the application running on Connect is likely to be an iterative process where parts of the application code and the server configuration may need to be adjusted to allow the application to work within the Connect operating model. The types of errors that occur are usually in the following categories:

These application dependencies are a necessary consideration regardless of the publishing method.

Publish from the RStudio IDE

The easiest application migration option is to publishing option is to publish your applications from the RStudio IDE. If the Shiny application runs in the RStudio IDE, then your data science team can use Push-Button Publishing to publish the Shiny application to an appropriately configured instance of Connect.

Publish from the SSP server

If your data science team cannot run the application inside the RStudio IDE, your SSP administrator can publish the application directly from the SSP server to Connect without an intermediate process. This process should likely only be used for archival applications that your data science team doesn’t anticipate updating in the future. If future updates/changes are needed, then your data science team should undertake the effort required to update the application to get the application running in the RStudio IDE and publish from there using Publish from the RStudio IDE.

Requirements

  • Root access to the SSP Linux environment
  • An account on Connect with a minimum of Publisher permissions
  • A list of the necessary data source dependencies
  • The directory and all files associated with the Shiny application on the SSP server
  • A list of required environment variables associated with the application on the SSP server
  • The named Connect user who owns the application post-publishing

Once your SSP administrator has the information listed above, follow the steps below to publish the application from SSP to Connect.

  1. Access the SSP server command line and su to the correct run_as user for the application you need to publish. Generally, this is the shiny user.

  2. Then, change your terminal location to the directory that contains the Shiny application that needs to be published:

    # Become the application run_as user
su - shiny
# Change directory to the directory that contains the application source code
cd <path-to-your-application-directory>

  3. Create an .Renviron file with the Connect API key associated with the selected Publisher account and the Server URL for your Connect instance to set them as environment variables during the next step:

    vi .Renviron
# Lines to add:
CONNECT_SERVER  = https://<connect-URL>
CONNECT_API_KEY = <my-secret-api-key>

  4. Start an R session in the current directory, and then read in the .Renviron file that you created in the previous step:

    R
readRenviron(".Renviron")

  5. Once the R console loads, run the following code to install the rsconnect package, which is required for publishing content to Connect and use the rsconnect package to generate a manifest for the target application:

    install.packages("rsconnect")
library(rsconnect)
rsconnect::writeManifest("<path-to-application>")

  6. In the same R session, install the connectapi package, load it, and then create a client connection as well as the application bundle:

    install.packages("connectapi")
library(connectapi)
# Creates a client connection to your Connect server, using the CONNECT_SERVER and CONNECT_API_KEY environment variables that we loaded from the .Renviron
client <- connect()
# Creates a Connect application bundle that will be deployed to Connect in the following step
bund <- bundle_dir("<path-to-application>")

  7. Deploy the application to Connect and poll the deployment status:

    # Deploys the application bundle created in the previous step using the client connect that was created. <application-name> should be replaced with a uniquely identifying name for your application
dep <- deploy(client, bund, "<application-name>")
# Poll the deployment to get logs and deployment status. This information should be available in the Connect user interface
poll_task(dep)

  8. Optionally, transfer ownership of the application from the Publisher/Administrator who published the application to the permanent owner. The steps to transfer content between users are accomplished via calls to the Connect API.

Once the application is successfully published to Connect and transferred to the permanent owner, it may not immediately start running. There are several reasons that a published application may fail to start, some of which are outlined below.

Testing migrated applications

After you’ve migrated a new SSP application to Connect, functional and validation testing is required. The combination of changing platforms, servers, and runtime environments often results in application errors or necessary configuration changes to the underlying Connect Linux Server. Testing processes and rigor vary between organizations, but generally, this testing period requires the skills of both the application owner, the Connect administrator, and the Connect Linux server administrator.

Some of the most common changes needed are:

  • Package versions/availability:
    • Make packages installed from private git repositories or inaccessible sources like local files or internal repositories that aren’t configured on Connect, available to Connect.
  • Data source connectivity, especially when the user_dirs directive was used in SSP:
    • When user_dirs is defined, it’s common for individual users to have their own .odbc.ini and .odbcinst.ini stored in their home directory, which defines user-specific ODBC data sources that need to be replicated on the Connect server.
  • Supported R versions in Connect:
    • Update applications using R versions previous to R 3.1 to at least R 3.1 to work on Connect.

After the migration

The migration of your organization’s Shiny applications results in your data science team facing many new workflow changes and options. The first change they’ll encounter is that rather than copying files/directories to your SSP instance, they have to remotely publish to Connect from their RStudio IDE or the command line using the rsconnect utility from their desktops/remote servers. This first workflow change is usually welcome and results in a quicker, more reliable process once each application’s initial testing and issue resolution period is completed.

Next, a framework for managing Shiny application permissions needs to be developed. Decisions need to be made around which data science team members need the ability to republish/modify which individual applications and what audience should be able to see their published applications. The Content Settings section of the Posit Connect User Guide details the options and limitations.

Data science teams must also shift their mindset from managing application directories to managing individual applications. This means that if a data science team is typically updates an entire directory of applications that are interrelated and tested together, they need to:

  • shift their perspective toward an understanding of the critical points where these applications interact, and
  • focus on those integration points when testing before publishing one of the included applications to avoid breaking the others.

This independent application structure allows for a more micro-service style approach. It can allow for efficient architecture decisions that split the presentation applications from the back-end data APIs that populate it.

Last in this list, but not the last consideration or new functionality they need to consider, is Git integration.

Connect allows data science publishers to integrate directly with an internal or external Git repository to enable Git-backed publishing. This pull or push-based publishing model allows for rigorous code review or publishing constraints that can increase application traceability and reliability and reduce the risk of security incidents.

Appendix

Mapping between SSP and Connect

Settings for content deployed to Connect are currently managed individually. Each application and document you publish must be configured separately.

The following sections list settings that you may be using in SSP, with their parallel settings in Connect

Hosting and administration

Custom headers

SSP set_header directive in /etc/shiny-server/shiny-server.conf
Connect Server.CustomHeader setting in /etc/rstudio-connect/rstudio-connect.gcfg


Specify SockJS protocols

SSP disable_protocols directive in /etc/shiny-server/shiny-server.conf
Connect Applications.DisabledProtocols setting in /etc/rstudio-connect/rstudio-connect.gcfg


Customize the run user for each application

SSP run_as directive in /etc/shiny-server/shiny-server.conf
Connect Administrators can customize the RunAs user on a content-specific level in the Connect dashboard, on the Access tab of the application or document settings.


Customize Shiny scaling settings

SSP  utilization_scheduler directive in /etc/shiny-server/shiny-server.conf
Connect The default settings are configured in the Scheduler section of /etc/rstudio-connect/rstudio-connect.gcfg, and custom scheduler settings for individual applications can be set in the Connect dashboard in the Performance tab of an application or document page.


Set the R version for a given application

SSP  r_path directive within a location in /etc/shiny-server/shiny-server.conf
Connect Uses Packrat to manage the packages associated with each application, and when you publish an application identifies a compatible version of R automatically based on the author’s environment. That same R installation is used any time R is needed for that content; there is no need to set the version in a configuration file on the server.


Host a directory of applications

SSP site_dir directive within a location in /etc/shiny-server/shiny-server.conf
Connect Individuals can publish their content into Connect themselves, rendering this feature redundant.


Local application configurations

SSP allow_app_override directive in /etc/shiny-server/shiny-server.conf, in conjunction with a .shiny_app.conf file in each application.
Conenct Application authors can manage their content independently in the Connect dashboard.

Metrics and session management


Historical system metrics

SSP admin directive in /etc/shiny-server/shiny-server.conf enables the admin dashboard
Connect Metrics section of /etc/rstudio-connect/rstudio-connect.gcfg enables the collection of historical metrics, which can then be viewed via Connect’s API and administrative dashboard.


Graphite export

SSP graphite_enabled directive in /etc/shiny-server/shiny-server.conf
Connect Metrics.GraphiteEnabled setting in /etc/rstudio-connect/rstudio-connect.gcfg


Health check

SSP /__health-check__ endpoint
Connect /__health-check__ endpoint


Authentication


Flat file authentication

SSP auth_passwd_file directive
Connect Authentication.Provider = password


PAM authentication

SSP auth_pam directive
Connect Authentication.Provider = pam, and [PAM] setting


LDAP and Active Directory authentication

SSP auth_ldap or auth_active_dir directive
Connect Authentication.Provider = ldap, and [LDAP] setting


Proxied authentication

SSP auth_proxy directive
Connect Authentication.Provider = proxy, and [ProxyAuth] setting


Google authentication

SSP auth_google directive
Connect Authentication.Provider = oauth2, and [OAuth2] setting


SSL support

SSP ssl directive
Connect [Https] section


Kerberos

SSP PAM sessions
Connect PAM sessions
Back to top