BioHPC Cloud:
: User Guide

Default port of Rstudio server is changed to 8016. If your Rstudio on port 8015 stops working due to a recent change in Cornell campus network, you will need to restart the Rstudio server:

/programs/rstudio_server/rstudio_stop
/programs/rstudio_server/rstudio_start

After this, open web browser to http://cbsuxxxxx.biohpc.cornell.edu:8016

There are multiple ways to use Rstudio at BioHPC. First we describe the pros/cons to help you decide. After that we give specific instructions for getting started with each option.

1. Rstudio Server is the most common choice. It allows you to have an Rstudio session that you connect to within a web browser. It is persistent, meaning that it keeps working even if you lose connection with the server, you can reconnect to it and your session will still be running. However, it has two important limitations:

   • Only one “Rstudio Server” can run on each BioHPC machine. The server can service many users, so anyone with access to the machine can log in and have their own Rstudio session once the server is started. The main limitation is that this server only runs a single version of R. If multiple users want to use Rstudio Server from the same machine, with different versions of R, this will not work.

   • Each user can only have one active Rstudio session at a time on a particular machine. If you have access to multiple machines at BioHPC, you can have a different session on each machine, but only if you move your session info out of your home directory (see specific instructions in the Rstudio Server setup section below).

2. RStudio Desktop is an X-windows (graphical) software that each user can run from the command line. It is similar to Rstudio server, but does not operate through a web browser and is not persistent (unless you run it over VNC, which is not always reliable).  Most users find the graphics are slower with this option. But there are no limitations about number of instances per machine, or versions of R.

3. You can run Rstudio Server in a docker container. In this way, you can have multiple independent instances of Rstudio server running on the same machine, each running different versions of R, if desired. The downside to this solution is that your R packages need to be installed in the docker container, so you cannot automatically use the packages installed on the BioHPC machines or in your home directory. However, once you have your R environment configured within your docker container, you can save this container as an image, which can be reused on any linux machine, or shared with others who may want to reproduce your research environment.

Setting up RStudio Server (without docker)

***Start-up instructions (but please read Notes below)***

1. SSH Login (through Putty or Mac Terminal) to the BioHPC server you want to run RStudio. 

2. Run the command "/programs/rstudio_server/mv_dir" if you want to keep the very big session data files under /workdir (see Note 2 below)

3. Run the command "/programs/rstudio_server/rstudio_start"  to start RStudio server. You may get a message that Rstudio is already running. This may mean that another user on the same machine has already started Rstudio. In this case, proceed to step 4.

4. From a browser on your laptop/desktop computer, go to this site "http://cbsuxxxxxx.biohpc.cornell.edu:8016".   (replacing the "cbsuxxxxx" with the acutal machine name ). Sometimes, you might need to reshresh the page once.  Log in with your BioHPC username and password.

5. If you want to stop the RStudio Server, use the command "/programs/rstudio_server/rstudio_stop". Be aware that this will stop all Rstudio sessions on the machine (including other user's, if it is a hosted machine or you have a shared reservation).

*** Notes ***

1. Rstudio Server runs through http (not https), but as BioHPC is only accessible through Cornell local network, it is reasonably safe.
2. About your Rstudio session data (~/.local/share/rstudio):
   • Rstudio stores its “session info” in your home directory, at ~/.local/share/rstudio. You may want to move this to local storage, for two reasons:
     1. If you are working with big data files, the session info can get quite large, and your home directory is paid storage (or subject to a quota).
     2. Your home directory is shared across BioHPC machines, so if rsession data is stored there, you can only have one session across all machines. By moving it to local storage, you can have different Rstudio sessions on different BioHPC machines.
   • To move your session data to local storage, use the command:
     /programs/rstudio_server/mv_dir
     *before* starting Rstudio. This command will delete existing rstudio session data in your home directory (~/.local/share/rstudio), create a new directory for session data (/workdir/$USER/rstudio), and create a symbolic link (~/.local/share/rstudio) to it.
   • If you cannot open Rstudio page, e.g. you are switching between versions of R, or between different servers, or session file too large, you can clear your rstudio session with the command:
     /programs/rstudio_server/mv_dir

3. Alternative versions of R: By default, R studio uses 4.2.1-r9. If you want to use another version of R, e.g. R v4.0.5,  start R studio with "/programs/rstudio_server/rstudio_start 4.0.5-r9", supported versions include 4.0.5-r9, 4.1.3-r9, 4.2.1-r9, 4.3.2, 4.4.2.  When you switch between versions, make sure you delete the session data and restart Rstudio, i.e.:
   
   /programs/rstudio_server/rstudio_stop
/programs/rstudio_server/mv_dir
/programs/rstudio_server/rstudio_start 4.0.5-r9

4. Avoid swapping of R session to disk: By default, R studio server will swap your session to disk after 2 hours of inactivity, thus freeing precious RAM memory for use by other users and applications. With large data sets, this may cause delays when your sessions has to be recovered from disk. Swapping can be avoided by specifying the option noswap as the last argument to rstudio_start. For example,
   
   /programs/rstudio_server/rstudio_start 4.2.1-r9 noswap
   
   will start Rstudio with R version 4.2.1-r9 and no swapping, whereas
   
   /programs/rstudio_server/rstudio_start noswap
   
   will start R studio with the default version of R and no swapping. Please note that runing R studio without swapping on a shared machine may adversely impact other users by depriving their applications of memory! Use noswap considerately!
    
5. Change default network port: By default, R studio server will use port 8016, so you can access it with "http://cbsbsuxxxxxx.biohpc.cornell.edu:8016". However, this port can be changed by adding new port number to the end of the command line parameters, which may be necessary if another service is already using port 8016. Please remember that the port MUST be between 8009 and 8039, you will then access your server with "http://cbsbsuxxxxxx.biohpc.cornell.edu:80XX", where 80XX is the new port number. You can use the other options as well, as long as port number is the last one, i.e. all examples below will run R studio server on port 8022:
   
   /programs/rstudio_server/rstudio_start 4.2.1-r9 noswap 8022
/programs/rstudio_server/rstudio_start noswap 8022
/programs/rstudio_server/rstudio_start 8022

Running Rstudio Desktop

Rstudio Desktop is an X-windows software. If you do not know how to run an X-windows software on BioHPC lab, read this page: https://cbsu.tc.cornell.edu/lab/userguide.aspx?a=access#b (read the section under under How to run graphical applications)

If you have never run rstudio on the server before, run this command:

To start the software, use this command: 

#to start Rstudio with default R v4.0
rstudio

#to start Rstudio with a different version, e.g. R v4.4.2
export RSTUDIO_WHICH_R=/programs/R-4.4.2/bin/R
rstudio

Running Rstudio Server in Docker

To start docker container, use the commands:

#On the host machine, create a local directory (any name) which would serve as rstudio session directory
mkdir /workdir/$USER/rstudio_dir

#start the docker container from Rocker/rstudio image
docker1 run -d -p 8009:8787 rocker/rstudio 

#get the container ID, replace xxxxxxx below with your container ID
docker1 ps

#add your BioHPC user ID and primary group ID into Docker container 
docker1 exec xxxxxxx groupadd -g `id -g` `id -g -n $USER`

docker1 exec xxxxxxx useradd -m -u `id -u` -g `id -g` -d /home/$USER $USER


#set password for your user account within container, this is the password you will use later to login to Rstudio
docker1 exec -it xxxxxxx passwd $USER

#make $USER as a sudo user in container
docker1 exec xxxxxxx usermod -aG sudo $USER

#make an alias /home/$USER/.local that point to your local /workdir/$USER/rstudio_dir
docker1 exec --user $USER xxxxxxx ln -s /workdir/rstudio_dir /home/$USER/.local

At this point, you might want to commit this container to a new image, so that you can re-use it later

docker1 commit 30b31021e48e myrstudio

#you can also export to a portable image file so that you can use on any servers later

docker1 save -o myrstudio.tar biohpc_$USER/myrstudio

Then, if you are on the Cornell network (or connected to VPN), you should then be able to go to http://cbsuxxxx.biohpc.cornell.edu:8009 and log in with the BioHPC user name, and password  your just set (Replace cbsuxxxx with actual machine name).  If you get an error about the port already being used after the docker1 run command, you can try another available port: 8009-8039 are open, although 8016 is used by the non-docker Rstudio. Rstudio runs on port 8787 inside the docker container, but this is mapped to port 8009 on the BioHPC server. If you want to have multiple Rstudio sessions, you can repeat the "docker1 run" command with different ports (keep 8787 the same, but change 8009 to something between 8009-8039).

All your files in /workdir/$USER/ will be mounted at /workdir/ within the container.

The example above will run R version 4.1.0, most other versions of R are also available (see https://hub.docker.com/r/rocker/rstudio/). 

If you need to install Linux libraries, you can do "sudo apt update" and "sudo apt install" to install libraries from the Terminal window in Rstudio.

You can install your R packages within the docker container (you can do this inside your Rstudio session using the install.packages() function, for example). It is possible you may also need to open a bash terminal within the docker container to install any system libraries required by your R packages. We can guide you through this if you need help. Once you have all your packages installed, you can save the container as an image and use it on any linux machine, or share it with others to reproduce your research.

More information about docker at biohpc is here: https://biohpc.cornell.edu/lab/userguide.aspx?a=software&i=340#c. 

Important: you need to restart the R session file regularly.

If you can still login to the Rstudio web page, follow instructions here to restart R:
https://argoshare.is.ed.ac.uk/healthyr_book/restart-r-regularly.html
 
Otherwise, do the following in Linux shell, then restart the Rstudio container:

rm -fr /workdir/$USER/rstudio_dir
mkdir /workdir/$USER/rstudio_dir