Adding RStudio to Workbench#

This topic covers how to install RStudio and use it within Data Science & AI Workbench.

Note

Anaconda recommends installing RStudio during a scheduled maintenance interval to prevent users from creating new sessions during installation. Existing sessions or deployments do not need to be halted.

Prerequisites#

These instructions are written for Workbench version 5.5.2 or later, and require the /tools volume from managed persistence to be enabled. For more information, see Mounting an external file share.

Installing RStudio#

Launching the RStudio installer project#

  1. Download the RStudio installer project and save it to your machine.

  2. Log in to Workbench as a user with read/write access to the /tools volume.

    Tip

    The anaconda-enterprise user has the correct permissions.

  3. Use the Create+ / Upload Project dialog to upload the RStudio installer project you just downloaded. Anaconda recommends using the JupyterLab editor for this task.

  4. Open a session for the RStudio installer project.

Obtaining the RStudio Server binaries#

Now that your project is created, you need to obtain and install the Red hat Package Manager (RPM) files and pull them into the project session. There are multiple methods for accomplishing this.

Downloading RStudio directly from Workbench#

Anaconda recommends users with clusters that have internet access download RStudio directly through Workbench.

  1. From your RStudio project session, open a new terminal window.

  2. If you need to set proxy variables manually to access the internet, do so now.

  3. Run the command:

    bash download_rstudio.sh
    Here is an example output from the download script:
    +------------------------+
| AE5 RStudio Downloader |
+------------------------+
- Target version: 2023.12.0-369
- Downloading into the data directory
- Downloading RHEL9 version only
- Downloading RHEL9/CentOS9 RPM file to data/rs-centos9.rpm
- URL: https://download2.rstudio.org/server/rhel9/x86_64/rstudio-server-rhel-2023.12.0-369-x86_64.rpm
% Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                Dload  Upload   Total   Spent    Left  Speed
100  108M  100  108M    0     0  18.4M      0  0:00:05  0:00:05 --:--:-- 23.2M
- Verifying data/rs-centos9.rpm
+------------------------+
The RStudio binaries have been downloaded.
You may now proceed with the installation step.
See the README.md file for more details.
+------------------------+

Using the download script on another Unix server#

If you need to download the binaries on a separate machine first, use the download_rstudio.sh script.

  1. Download the script file download_rstudio.sh from the project to your desktop.

  2. Move the script file to a machine that can run bash and curl and has connectivity to download2.rstudio.org.

  3. Run the command:

    bash download_rstudio.sh

  4. If necessary, transfer the binaries rs-centos7.rpm and rs-centos8.rpm to the machine from which you access Workbench.

  5. Use the JuptyerLab upload button to upload both binaries into the RStudio installer project.

Running the installation script#

Now that you have obtained the RStudio binaries and uploaded the rs-centos7.rpm and rs-centos8.rpm files to your RStudio installer project:

  1. Open a terminal window.

  2. If you have previously installed content into /tools/rstudio, remove it now by running the following command:

    rm -r /tools/rstudio

  3. Install RStudio by running the following command:

    bash install_rstudio.sh

    Note

    The script will verify that all prerequisites are met before performing any file modifications.

    Here is an example output from the RStudio installer:
    +-----------------------+
| AE5 RStudio Installer |
+-----------------------+
- Install prefix: /tools/rstudio
- Verifying data/rs-centos9.rpm
- Creating directory /tools/rstudio
- Unpacking RHEL9/CentOS9 package
1177155 blocks
- Moving files into final position
- Installing support files
+-----------------------+
RStudio installation is complete.
Once you have verified the installation, feel free to
shut down this session and delete the project.
+-----------------------+
WARNING: Many R packages make use of Java, and it seems
not to be present on this installation of AE5. To make
Java available to all AE5 users, run install_java.sh, or
manually download a JDK Linux x64 archive and unpack its
contents into the directory /tools/java.
+-----------------------+

Enabling RStudio as an editor#

With installation complete, the next step is to add RStudio to the editor selection list within Workbench’s User Interface (UI).

  1. Access your Kubernetes cluster resource management console.

  2. Open the anaconda-enterprise-anaconda-platform.yml ConfigMap and search for the tools: section of the file.

  3. Add the following line, nested under tools::

    rstudio: Rstudio

  4. Save your work and close the file.

  5. Open a terminal and restart the workspace and ui pods by running the following command:

    kubectl delete --wait=false $(kubectl get pods -o name|grep -E 'worksapce|ui')

Note

Minor disruptions in UI responsiveness may occur while the pods are stabilizing. If you have allowed users to continue working during this installation, they may need to refresh their browsers.

Once the cluster pods stabilize, the RStudio editor will be present in the Default Editor dropdown on any project’s Settings page.

With RStudio enabled as an editor, your Op-Center will typically look like this:

Verifying your installation#

  1. If necessary, stop the session for your RStudio installer project.

  2. Go to the RStudio installer project’s Settings page.

  3. Open the Default Editor dropdown, select RStudio, and then click Save.

  4. Start a new session and wait for the editor to launch.

If your installation is unsuccessful:

  1. Click on the Logs tab.

  2. Search the editor logs for a section titled Workbench R Session Manager and look for errors there and below.

  3. Copy the full content of this log so it can be shared with Anaconda.

  4. Stop the session completely.

  5. Go to the project’s Settings page, and change the Default Editor back to JupyterLab.

  6. If your errors are obvious to you and understand what corrective action is needed, open a new session to make those changes.

Please reach out to Anaconda support if this occurs. Make sure to include a copy of the editor logs you obtained above.

Disabling RStudio#

To remove RStudio as an editor option for new projects:

  1. Log in to your Kubernetes administrative console.

  2. Open the anaconda-enterprise-anaconda-platform.yml ConfigMap file.

  3. Search for the tools: section of this file and remove the following line:

    rstudio: Rstudio

  4. Save your work and close the file.

  5. Open a terminal and restart the workspace and ui pods by running the following command:

    kubectl delete --wait=false $(kubectl get pods -o name|grep -E 'worksapce|ui')

    Note

    Existing projects that are using RStudio will still have access to the editor.

Uninstalling RStudio#

Caution

If you need to permanently remove /tools/rstudio, instruct all users to stop all sessions currently using RStudio and choose a different editor, such as JupyterLab, before continuing. If they do not, sessions will fail to fully start.

To permanently uninstall RStudio, you need to remove the /tools/rstudio directory. Anaconda recommends removing the directory from outside Workbench, if possible. If necessary, instructions are provided to remove RStudio using Workbench.

Uninstalling RStudio using Workbench#

  1. Log in to Workbench as a user with read/write access to the /tools volume.

    Tip

    The anaconda-enterprise user has the correct permissions.

  2. Remove /tools/rstudio from within a Workbench session by running the following command:

rm -r /tools/rstudio

Upgrading to a new version of Workbench#

Upgrading to a new version of Workbench will not affect your RStudio installation; however, the upgrade process will cause the editor to be hidden. Once the upgrade is complete, you’ll need to enable RStudio as an editor again.

Upgrading RStudio#

Anaconda recommends performing a fresh installation when upgrading RStudio.

  1. Launch the RStudio installation project.

  2. Obtain the RStudio server binaries.

  3. (Optional) Rename your existing RStudio directory. If your installation is unsuccessful for any reason, you can rename the existing RStudio directory back to its original state to avoid downtime. Run the command:

    mv /tools/rstudio /tools/rstudio.old

  4. Instruct all users to stop all sessions currently using RStudio.

  5. Run the installation script.

  6. Enable RStudio as an editor.

  7. Verify your installation.

  8. If necessary, remove the old installation /tools/rstudio.old. Run the command:

    rm -r /tools/rstudio.old

  9. Log out of Workbench.

Installing RStudio on additional Workbench instances#

Once you have successfully installed RStudio on one instance, you can copy and move the /tools/rstudio directory to another instance, reducing the amount of work involved for a second install.

Create an archive of an existing installation#

  1. Log in to an instance of Workbench with a running RStudio installation.

  2. Open a session using the JupyterLab editor.

  3. Open a terminal window.

  4. Create the archive. Run the command:

    tar cfz rstudio.tar.gz -C /tools rstudio

  5. Download this file to your desktop. Once you have done so, you can remove the file from your Workbench session.

Move the archive to a new instance#

  1. Open any session using the JupterLab editor.

  2. Upload the archive rstudio.tar.gz into the project.

  3. Open a terminal window.

  4. (Optional) Rename your existing RStudio directory. If your installation is unsuccessful for any reason, you can rename the existing RStudio directory back to its original state to avoid downtime. Run the command:

    mv /tools/rstudio /tools/rstudio.old

  5. Install the archive. Run the command:

    tar xfz rstudio.tar.gz -C /tools

  6. Verify your installation.

  7. If necessary, remove the old installation /tools/rstudio.old. Run the command:

    rm -r /tools/rstudio.old

  8. Enable RStudio as an editor.

  9. Log out of Workbench.