> For the complete documentation index, see [llms.txt](https://igb.mit.edu/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://igb.mit.edu/mini-courses/research-computing-on-engaging-with-vscode/running-containerized-rstudio.md).

# Running Containerized RStudio

When working with R on a computing cluster, sometimes R packages install normally. Other times, there may be incompatibilities between the version of R installed on the cluster and the R package you're trying to install, or a dependency that an R package needs to function is not installed on the cluster, and installing the dependency without administrative privileges is difficult to do.

In cases like these, we recommend using R inside of a container that bundles all of the necessary system packages and R packages.

We will not show the process of building the image needed to run the container, although that may be the topic of another training session. Instead, we will show an example of using an already-built image. Specifically the `bumproo/r4_5_3_singlecell_bulk_rnaseq` image that we have created that has R 4.5.3, RStudio, and R packages for single cell bulk RNA-Seq built-in.

Running a containerized RStudio and accessing it in your web browser can be done with the following script. Simply save this to a file named `rstudio.sh`. Make sure to change `example@mit.edu` to your e-mail address.

```bash
#!/bin/bash

#SBATCH -n 8
#SBATCH --job-name=Rstudio       # Assign an short name to your job
#SBATCH --output=slurm.%N.%j.out     # STDOUT output file
#SBATCH --mail-user=example@mit.edu # The user to email
#SBATCH --mail-type=ALL

module load apptainer
module load miniforge

workdir=$(python -c 'import tempfile; print(tempfile.mkdtemp())')

mkdir -p -m 700 ${workdir}/run ${workdir}/tmp ${workdir}/var/lib/rstudio-server
cat > ${workdir}/database.conf <<END
provider=sqlite
directory=/var/lib/rstudio-server
END

cat > ${workdir}/rsession.sh <<END
#!/bin/sh
export OMP_NUM_THREADS=${SLURM_JOB_CPUS_PER_NODE}
exec /usr/lib/rstudio-server/bin/rsession "\${@}"
END

chmod +x ${workdir}/rsession.sh

export APPTAINER_BIND="${workdir}/run:/run,${workdir}/tmp:/tmp,${workdir}/database.conf:/etc/rstudio/database.conf,${workdir}/rsession.sh:/etc/rstudio/rsession.sh,${workdir}/var/lib/rstudio-server:/var/lib/rstudio-server"
export APPTAINERENV_RSTUDIO_SESSION_TIMEOUT=0
export APPTAINERENV_USER=$(id -un)
export APPTAINERENV_PASSWORD=$(echo $RANDOM | base64 | head -c 20)

readonly PORT=$(python -c 'import socket; s=socket.socket(); s.bind(("", 0)); print(s.getsockname()[1]); s.close()')

cat 1>&2 <<END

Connect to RStudio using either of these options:

1. Forward port in VSCode.

   Ports > Forward a Port > Set "Port" to: ${HOSTNAME}:${PORT}

   Navigate to http://localhost:${PORT} in your web browser.
   Login with the following credentials:

   user: ${APPTAINERENV_USER}
   password: ${APPTAINERENV_PASSWORD}

2. Manually forward ports with SSH.

   From your MacOS Terminal / Windows Powershell, run:
   
   ssh -N -L ${PORT}:${HOSTNAME}:${PORT} ${USER}@orcd-login.mit.edu
   
   Navigate to http://localhost:${PORT} in your web browser.
   Login with the following credentials:

   user: ${APPTAINERENV_USER}
   password: ${APPTAINERENV_PASSWORD}

When done using RStudio Server, terminate the job by:

1. Exit the RStudio Session ("power" button in the top right corner of the RStudio window)
2. Issue the following command on the login node:

      scancel -f ${SLURM_JOB_ID}
END

apptainer exec --cleanenv \
               -B /orcd:/orcd \
               docker://docker.io/bumproo/r4_5_3_singlecell_bulk_rnaseq:latest /usr/lib/rstudio-server/bin/rserver \
                  --server-user ${USER} --www-port ${PORT} \
                  --auth-none=0 \
                  --auth-pam-helper-path=pam-helper \
                  --auth-stay-signed-in-days=30 \
                  --auth-timeout-minutes=0 \
                  --rsession-path=/etc/rstudio/rsession.sh
```

After saving this to a file, you can submit it by running `sbatch rstudio.sh`. This will send it to the Slurm scheduler and produce a Slurm output file. Open the Slurm output file and read through the instructions for forwarding ports in VSCode.

<figure><img src="https://498238201-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWuHhstIreJ3jFvE4gQ3y%2Fuploads%2FGJesV3f72LXPqYZbU2IW%2FScreenshot%202026-09-23%20at%202.48.59%E2%80%AFPM.png?alt=media&amp;token=cf20b160-c7af-433b-813f-6a056c19554e" alt=""><figcaption></figcaption></figure>

For example, forwarding the ports as described in the instructions will look like this.

<figure><img src="https://498238201-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWuHhstIreJ3jFvE4gQ3y%2Fuploads%2FXxlNNO9hx64DykLqbg8E%2FScreenshot%202026-09-23%20at%202.55.02%E2%80%AFPM.png?alt=media&amp;token=bb932f05-49bc-4dc9-8aff-a20d827180aa" alt=""><figcaption></figcaption></figure>

Once you've done that, you can navigate to the website listed in the instructions, login with the provided credentials, and RStudio will be available to you with common single cell RNA-Seq packages pre-installed.

<figure><img src="https://498238201-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWuHhstIreJ3jFvE4gQ3y%2Fuploads%2FfFWyfwUvH4cMdfGSeCqN%2FScreenshot%202026-09-23%20at%202.50.07%E2%80%AFPM.png?alt=media&amp;token=3101f58a-409f-462e-8091-1dbeb9b2c301" alt=""><figcaption></figcaption></figure>