Skip to content

Upgrade and/or Migrate Posit Team — Overview

flowchart LR
    A((0))
    B((1))
    C(("✔"))
    D((2))
    E((#9829;))
    A---B
    B---C
    C---D
    D---E
    A ~~~|"<b>Overview</b>"|A
    B ~~~|"<a style="text-decoration:none" href="phase1-upgrade">Phase 1\n Install\n Upgraded\n Products</a>"|B
    C ~~~|"<a style="text-decoration:none" href="phase1-test">Test\n Phase 1</a>"|C
    D ~~~|"<a style="text-decoration:none" href="phase2-migrate">Phase 2\n Migrate\n Data</a>"|D
    E ~~~|"<a style="text-decoration:none" href="rollout">Rollout</a>"|E

    %% click A href "../"
    click B href "phase1-upgrade"
    click C href "phase1-test"
    click D href "phase2-migrate"
    click E href "rollout"

    classDef activePage fill:#447099, stroke:#D1DBE5, color:#fff, padding:4px
    classDef inactivePage fill:#D1DBE5, stroke:#447099, color:#151515, padding:4px
    classDef activeDesc font-size:20px
    class B,C,D,E inactivePage
    class A activePage

Purpose#

These procedures describe how to conduct a migration or upgrade of the Posit products (Posit Package Manager, Posit Workbench, and Posit Connect). Upgrade of the Linux operating system (OS) is also considered.

Scope#

If you are currently running a supported product version and only need to upgrade that product, refer to the product upgrade instructions in the administrator guide for Package Manager Upgrade, Workbench Upgrade, and Connect Upgrade.

If you are upgrading from an unsupported product version, changing servers, and/or changing the Linux OS, follow these procedures.

Applicability#

  • These procedures directly address single-server installations for each product. These procedures can be used as a basis for developing an upgrade plan for high availability deployments, or configurations that are deployed in / integrate with external clusters.
  • Out of scope:
    • Architecture changes are out of scope of these procedures and should be considered as separate efforts following successful OS and product upgrade.
    • Upgrades to supporting infrastructure, such as the Postgres product database, are out of scope.
    • Database administration and Linux administration tasks are out of scope for Posit support.

Requirements#

Phase overview#

These procedures stand up a net-new Posit Team environment (Package Manager, Workbench, and Connect) in isolation from the existing production deployment. This method brings all three products up to date in a two-phased approach. If upgrading the OS, Python and R packages in the production environment will be affected. Perform work on dedicated staging servers so that the production environment remains isolated while confirming package compatibility under the new OS.

Package Manager is installed first so that it can be configured as the default repository source for both Workbench and Connect. If you do not have a professional version of Package Manager, we recommend configuring Workbench and/or Connect to use Posit Public Package Manager. In either case, Package Manager provides precompiled Linux binaries for packages, which accelerates package library rebuilds and avoids many package installation issues due to missing system dependencies.

This two-phased approach is:

  1. Phase 1 — Stand up and configure a new Posit Team environment in a separate staging environment:

    • This is fully isolated from the existing production deployment. This staging environment will have no content but will be configured per the production requirements (e.g., authentication, network connections, drivers, versions of Python, R, and Quarto). During Phase 1 activities, the production deployment can remain online. Testing and verification of the environment are conducted before moving to Phase 2 to keep changes to a more narrowly scoped statement of work.

  2. Phase 2 — Migrate user/content data and product database:

    • The second phase is strictly the movement of content and data, rebuilding environments as required. To preserve consistent state between the content data and product database, the production environment must be shut down when snapshots are taken for migration purposes. The production environment can be turned back on following snapshots, but be aware that any changes made after this point are not captured in the new environment and a separate plan should be enacted to capture any new work or deployments in production occurring during this time.

Upon completion of the two phases, the entire environment can then be released to production as one unit.

About in-place Linux OS upgrades

An in-place upgrade of the Linux OS is generally not recommended.

Your organizational processes may seek this type of approach. You may consider an in-place OS and product upgrade if you:

  • Are upgrading from a supported Posit product version to another supported product version. Refer to the list of Supported Pro product versions to determine applicability.
  • Have a staging server available to perform all work in an isolated environment. Without a staging environment, troubleshooting issues is challenging because the old environment is not available for reference.
  • Are satisfied with the support (if any) provided by your OS vendor during the in-place OS upgrade.
  • Recognize that upgrading the OS also updates system libraries. The updated system libraries are often incompatible with older R and Python package versions, package binaries installed under the old OS, or other software packages installed on the server. These incompatibilities may not be uncovered at the time of upgrade, making them difficult to troubleshoot.

Upgrading the OS in place requires that the Posit software, and all versions of R, Python, and Quarto be re-installed, as they are not upgraded as part of the OS upgrade.

If you satisfy the requirements listed above and wish to forgo the recommended phased approach outlined in this How-To, review the overview of How to Upgrade the Linux OS and Posit Product(s) In-Place.


Next Step:
Proceed to Phase 1