Longleaf Setup

UNC’s HPC cluster

Longleaf is UNC’s primary high-performance computing cluster and the recommended environment for all production lab work.

ImportantUse Longleaf for Production Work

Longleaf is the recommended environment for:

  • Running simulations and calibrations
  • Reproducible analyses
  • Collaborative work (shared file system)
  • Long-running jobs

Local machines are fine for writing and editing code, small-scale testing, and manuscript writing.

Request Access

  1. Go to ITS Research Computing
  2. Request Longleaf access with PI: Naim Rashid
  3. Wait for approval email (~1-2 business days)

Connection Options

You have three ways to access Longleaf:

Method Best For Setup Difficulty
OnDemand (Web) Beginners, RStudio users None
VS Code Remote Modern editor experience Easy
SSH Command-line power users Easy

Open OnDemand (Web Interface)

Open OnDemand provides a web-based interface to Longleaf—no software installation required. This is the easiest way to get started.

Access

  1. Go to ondemand.rc.unc.edu
  2. Log in with your Onyen and password
  3. You’ll see the OnDemand dashboard
Note

You must have a Longleaf account before using OnDemand. See Request Access above.

Key Features

Feature Description
Files Browse, upload, download, edit files on Longleaf
Shell Terminal access in your browser (no SSH needed)
RStudio Server Full RStudio IDE running on cluster
Jupyter Jupyter notebooks with Python/R kernels
Job Composer Submit and manage Slurm batch jobs

Launching RStudio Server

This is the recommended way to use RStudio on Longleaf:

  1. Go to Interactive Apps –> RStudio Server
  2. Fill in the resource request form:
    • Number of hours: Start with 4-8 hours
    • Number of cores: 1-4 for interactive work
    • Memory (GB): 8-16 GB is usually sufficient
    • Partition: general (or gpu if needed)
  3. Click Launch
  4. Wait for job to start (usually 1-5 minutes)
  5. Click Connect to RStudio Server
# Example resource request for typical development work:
Hours: 8
Cores: 4
Memory: 16 GB
Partition: general

Launching Jupyter Notebooks

For Python work or R via IRkernel:

  1. Go to Interactive Apps –> Jupyter Notebook
  2. Fill in resources (similar to RStudio)
  3. Select Python version or load R kernel
  4. Click Launch then Connect

Browser-Based Terminal

Access a shell without any local software:

  1. Go to Clusters –> Longleaf Shell Access
  2. A terminal opens in your browser
  3. You’re on a login node—same as SSH

Use cases: Quick file operations, git commands, checking job status, module loading.

File Management

The Files menu provides a web-based file browser:

  • Navigate to any directory you have access to
  • Upload files via drag-and-drop (useful for small files)
  • Download files or entire directories
  • Edit text files directly in the browser
  • Access lab shared space at /proj/rashidlab/

Tip: For large files, use scp or rsync instead of the web uploader.

Job Composer for Batch Jobs

For long-running analyses, use Job Composer instead of interactive sessions:

  1. Go to Jobs –> Job Composer
  2. Click New Job –> From Template
  3. Select a template (or create from scratch)
  4. Edit the job script:
#!/bin/bash
#SBATCH --job-name=my_analysis
#SBATCH --time=24:00:00
#SBATCH --cpus-per-task=8
#SBATCH --mem=32G
#SBATCH --output=logs/%j.out

module load r/4.3.0
Rscript scripts/run_analysis.R
  1. Click Submit
  2. Monitor in Jobs –> Active Jobs

OnDemand Best Practices

Tip
  1. Request appropriate resources - Don’t over-request; it slows queue time
  2. Save work frequently - Sessions can timeout
  3. Use /work/ for large temp files - Not /home/ (quota limited)
  4. Check job status - Jobs –> Active Jobs shows your running sessions
  5. Delete completed jobs - Keeps your dashboard clean

Troubleshooting OnDemand

Issue Solution
Session won’t start Check if cluster is busy; try smaller resource request
RStudio unresponsive Delete job, relaunch; check memory limits
Can’t find files Verify path; check you’re in correct directory
Git authentication fails Re-enter credentials; check token hasn’t expired
Session timeout Relaunch; consider batch job for long work

If sessions consistently fail: Go to Jobs –> Active Jobs, delete the problematic job, clear browser cache, and try again. For persistent issues, contact ITS Research Computing.

VS Code Remote SSH

The recommended way to work on Longleaf with a modern editor.

Setup

  1. Install VS Code
  2. Install the Remote - SSH extension
  3. Press Ctrl+Shift+P –> “Remote-SSH: Connect to Host”
  4. Enter: your_onyen@longleaf.unc.edu
  5. VS Code opens a remote session on Longleaf

SSH Config (Optional)

Create ~/.ssh/config on your local machine for easier connections:

Host longleaf
    HostName longleaf.unc.edu
    User your_onyen
    ForwardAgent yes
    ForwardX11 yes

Then connect with just: ssh longleaf or select “longleaf” in VS Code.

SSH Access

For command-line access to Longleaf.

Connect via SSH

# Basic SSH connection
ssh your_onyen@longleaf.unc.edu

# With X11 forwarding (for plots)
ssh -Y your_onyen@longleaf.unc.edu

Windows users: Use MobaXterm or Windows Terminal with OpenSSH.

SSH Key Setup (Passwordless Login)

# On your LOCAL machine, generate key
ssh-keygen -t ed25519 -C "your.email@unc.edu"

# Copy to Longleaf
ssh-copy-id your_onyen@longleaf.unc.edu

# Test (should not ask for password)
ssh your_onyen@longleaf.unc.edu

Longleaf Environment

Module System

Longleaf uses modules instead of package managers. Software is pre-installed and loaded on demand.

# See available modules
module avail

# Search for specific software
module avail r
module avail quarto

# Load R (run 'module avail r' to see available versions)
module load r/4.3.0

# Load multiple modules
module load r/4.3.0 gcc/11.2.0 quarto/1.4.550

# See loaded modules
module list

# Unload a module
module unload r

# Unload all
module purge

Key Directories

Path Purpose Quota
/home/your_onyen/ Home directory 50 GB
/work/users/y/o/your_onyen/ Scratch space 10 TB (not backed up)
/proj/rashidlab/ Lab shared space 1 TB shared (not backed up)
/proj/rashidlab/projects/ Project data (private) Within lab 1 TB quota
/proj/rashidlab/users/ Personal work (private) Within lab 1 TB quota
/proj/rashidlab/R-packages/ Shared R packages Within lab 1 TB quota
WarningImportant: /proj/rashidlab/ Access Rules
  • The top-level /proj/rashidlab/ directory is publicly readable on the cluster — anyone can read files placed directly there. Store private or sensitive data in the projects/ or users/ subdirectories instead.
  • This space is not backed up. If you have data that can’t be easily reproduced, keep a copy elsewhere.
  • Quota: 1 TB soft limit. You can check current usage at service.rc.unc.edu. If the folder exceeds the soft limit, a 7-day grace period starts — after that, no new files can be added until usage drops back below the limit.
  • Access: To add or remove cluster access for lab members, email research@unc.edu referencing group rc_nur2lab_psx.
  • Compliance: If storing data requiring NIST 800-171 compliance, see Longleaf Compliance.

R Package Installation

# First, set up personal library (one time)
dir.create("~/R/library", recursive = TRUE)

# Add to ~/.Rprofile
cat('.libPaths(c("~/R/library", "/proj/rashidlab/R-packages", .libPaths()))\n',
    file = "~/.Rprofile", append = TRUE)

# Restart R, then install packages
install.packages("data.table")

Quarto on Longleaf

# Load Quarto module
module load quarto/1.4.550

# Verify
quarto --version

# Render document
quarto render manuscript.qmd --to pdf

Note: If Quarto module isn’t available, check module avail quarto or contact ITS Research Computing.

Longleaf Configuration Templates

~/.bashrc on Longleaf:

# Load standard modules on login
module load r/4.3.0
module load gcc/11.2.0
module load git/2.36.0
module load quarto/1.4.550

# R library path
export R_LIBS_USER=~/R/library

# Useful aliases
alias ll='ls -la'
alias squeue-me='squeue -u $USER'

Then run: source ~/.bashrc

~/.Rprofile on Longleaf:

# Library paths (personal + shared lab + system)
.libPaths(c(
  "~/R/library",
  "/proj/rashidlab/R-packages",
  .libPaths()
))

# CRAN mirror
options(repos = c(CRAN = "https://cloud.r-project.org"))

Verification

After setup, verify everything works:

ssh your_onyen@longleaf.unc.edu
module load r/4.3.0
R --version
Rscript -e "library(data.table); print('OK')"
module load quarto
quarto --version
git --version

Next: Local Development Setup | Git & GitHub Setup