Get Started

Table of contents

  1. Introduction
  2. New Member Onboarding — Do These IN ORDER
  3. Getting Set Up to Work
  4. Few words on structure of SDCC
  5. Software Setup:
    1. 0) Preconditions
    2. 1) Generate an SSH key (local) and upload .pub to SDCC
      1. Copy-paste script (local)
      2. Test: passwordless login
    3. 2) VS Code: Remote-SSH
    4. 3) Mount SDCC
    5. 4) Running STAR software locally (optional)
      1. Important!
      2. MacOS

Introduction

Welcome to STAR! This page is a checklist for new collaboration members. Work through it top to bottom — the onboarding steps have hard dependencies, so order matters.

New Member Onboarding — Do These IN ORDER

flowchart LR
    A[1 - Get ORCID] --> B[2 - BNL Guest Appointment]
    B --> C[3 - SDCC Account]
    C --> D[4 - Email SDCC and ORCID to Phonebook keeper]
    A -.-> D
    D --> E[5 - Start Working]
    style A fill:#e1f5ff,stroke:#0277bd,stroke-width:2px
    style B fill:#e1f5ff,stroke:#0277bd,stroke-width:2px
    style C fill:#e1f5ff,stroke:#0277bd,stroke-width:2px
    style D fill:#fff3e0,stroke:#e65100,stroke-width:3px
    style E fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
#StepLink
1Get ORCID — required for STAR publications and the author listorcid.org/register
2BNL guest appointment — sponsored by your home institution’s BNL liaison or your STAR advisor. Required before the SDCC accountBNL Guest Registration
3SDCC account — needed for Drupal login, computing, and disk quotaSDCC new user
4Email BOTH your SDCC username AND ORCID to Rachel (current STAR Phonebook keeper) — see the prefilled templateSend email to Rachel  ·  Phone Book

Getting Set Up to Work

Once your Phonebook entry is live, wire yourself into the collaboration:

  1. Join Mattermost — the Software & Infrastructure channel is the main place to ask technical questions.
  2. Set up Drupal 2FA on first login. If it fails, ping Dmitry Arkhipkin or Jerome Lauret.
  3. Subscribe to mailing lists:

Few words on structure of SDCC

flowchart LR
    L["💻 Your laptop"] -->|ssh| GW["🔑 ssh.sdcc.bnl.gov<br>gateway"]
    GW --> N["🖥️ starsub01-07<br>Alma 9 · tcsh"]

    subgraph S["💾 Shared SDCC storage "]
      direction TB
      H["🏠 /star/u/USER<br><b>25 GB</b>"]
      P["📂 /gpfs01/star/pwg/USER<br><b>up to 5.5 TB</b>"]
    end

    N --- S
    P -.->|" you back up"| T["📼 HPSS<br>tape"]

    style L  fill:#f5f5f5,stroke:#616161,stroke-width:2px
    style GW fill:#e1f5ff,stroke:#0277bd,stroke-width:2px
    style N  fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
    style H  fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px
    style P  fill:#fff3e0,stroke:#e65100,stroke-width:3px
    style T  fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px
    style S  fill:#ffffff,stroke:#9e9e9e,stroke-width:1px,stroke-dasharray: 5 5
  • The HOME directory is under /star/u/<username> - it has only 25 GB available (could be a reason why some software like VS Code is not starting Remote SSH). This is where you land when performing SSH command. By default STAR uses tcsh, not bash, which was a historical choice.
  • The second place with dynamical quota (up to 5.5 TB ) which depends on institution is /gpfs01/star/pwg/<username>.

However, there is a twist - after not touching files for > than 500 days, the files on /gpfs01/star/pwg/ are DELETED - make sure to back them up on HPSS (tape). The home directory is not touched in any case.

Software Setup:

All following instructions are for Linux/MacOS users. Windows users are asked to use WSL2 which is a Linux subsystem integrated into Windows

0) Preconditions

1) Generate an SSH key (local) and upload .pub to SDCC

Use RSA-4096 for generation of the key pair (if you don’t have one already):

mkdir -p ~/.ssh
chmod 700 ~/.ssh
ssh-keygen -b 4096 -t rsa -f ~/.ssh/id_rsa_sdcc

After generating, upload it to SDCC in order to connect to ssh.sdcc.bnl.gov gateway if it has not been done.

There exists 2 possibilities - either to use password every time you login or upload your public SSH key to servers. This is how you could upload your key and setup SSH connection with script:

Copy-paste script (local)

Now, add your public key to SDCC STAR nodes authorized_keys using this script:

flowchart LR
    A[Your Laptop] -->|ssh using web uploaded key| B[ssh.sdcc.bnl.gov]
    B -->|ssh starsub03 with password| C[starsub03.sdcc.bnl.gov]
    A -.->| Single Command 
    without password| C


(
YOUR_KEY="${HOME}/.ssh/id_rsa_sdcc"  # replace with your key path if different
LOCAL_USER="$(whoami)"

# Ask whether SDCC username matches local username
read -r -p "Is your SDCC username the same as your local username (${LOCAL_USER})? [Y/n] " ans
case "${ans:-Y}" in
  [Yy]|[Yy][Ee][Ss])
    SDCC_USERNAME="${LOCAL_USER}"
    ;;
  *)
    read -r -p "Enter your SDCC username: " SDCC_USERNAME
    SDCC_USERNAME="${SDCC_USERNAME//[[:space:]]/}"
    if [ -z "${SDCC_USERNAME}" ]; then
      echo "ERROR: Empty SDCC username. Exiting."
      exit 1
    fi
    ;;
esac

if [ ! -f "${YOUR_KEY}" ]; then
  echo "ERROR: Private key not found: ${YOUR_KEY}"
  exit 1
fi

mkdir -p ~/.ssh
chmod 700 ~/.ssh
b64="$(base64 < ${YOUR_KEY}.pub | tr -d '\n')"
ssh -tt -x -o ForwardX11=no $SDCC_USERNAME@ssh.sdcc.bnl.gov "ssh -t -x -o ForwardX11=no -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null $SDCC_USERNAME@starsub03.sdcc.bnl.gov \
\"umask 077; mkdir -p ~/.ssh; touch ~/.ssh/authorized_keys ; chmod 700 ~/.ssh; printf '%s\n' '$b64' | base64 -d >> ~/.ssh/authorized_keys; chmod 600 ~/.ssh/authorized_keys\""

touch ~/.ssh/config
chmod 600 ~/.ssh/config
grep -qF "=== SDCC jump host ===" ~/.ssh/config || cat >> ~/.ssh/config <<EOF
# === SDCC jump host ===
Host starsub0*
    HostName %h.sdcc.bnl.gov
    User ${SDCC_USERNAME}
    ProxyJump ${SDCC_USERNAME}@ssh.sdcc.bnl.gov
    IdentityFile ${YOUR_KEY}
    ForwardAgent yes
    RequestTTY yes
    ServerAliveInterval 60
    ServerAliveCountMax 2
Host star
    HostName starsub03.sdcc.bnl.gov
    User ${SDCC_USERNAME}
    ProxyJump ${SDCC_USERNAME}@ssh.sdcc.bnl.gov
    IdentityFile ${YOUR_KEY}
    ForwardAgent yes
    RequestTTY yes
EOF

# Load your key into the SSH agent (local)
if [ -n "${SSH_AUTH_SOCK:-}" ]; then
  ssh-add -L 2>/dev/null || true
  ssh-add ${YOUR_KEY}
fi
)

Test: passwordless login

ssh star
# or
ssh starsub05

If it still asks for a password, check ~/.ssh/config: the Host star block should be there exactly once.

2) VS Code: Remote-SSH

VS Code is an IDE (integrated development environment) that is recommended to be used. However it is not required for work - you could install terminal-based editor on SDCC or use vim/emacs, or use your preferred IDE that has SSH capability (e.g. JetBrains Gateway) Screenshot 2026-01-20 100729

  1. Install VS Code extension Remote - SSH and some other useful extensions like ROOT File viewer
  2. Open Command Palette (Ctrl+Shift+P) → start typing Remote-SSH: Connect to Host...
  3. Select star.
  4. VS Code installs the remote server on first connect; then open your folder on SDCC, e.g. /gpfs01/star/pwg/${SDCC_USERNAME}/ Persistence note: the node state is not persistent; use tmux for long-running terminal sessions.

Remark: for WSL2 it is necessary to change Windows SSH config to work with VS Code

3) Mount SDCC

mounting

If you need to download files from SDCC (like ROOT Trees) I recommend mounting SDCC filesystem via sshfs:

sudo apt install sshfs #linux
# brew install sshfs # for MacOS use Homebrew
mkdir -p ~/starmount
SDCC_USERNAME=$(whoami) # replace with your SDCC username if different from local
echo "alias starmount='sshfs -o reconnect,ServerAliveInterval=15,ServerAliveCountMax=3  ${SDCC_USERNAME}@sftp.sdcc.bnl.gov:/gpfs01/star/pwg/${SDCC_USERNAME} ~/starmount'" >> ~/.bashrc
source ~/.bashrc
starmount

Afterwards ~/starmount behaves like a normal folder. Unmount with fusermount -u ~/starmount.

4) Running STAR software locally (optional)

In case you want to enter and run STAR container on your own laptop:

sudo apt update
sudo apt install -y software-properties-common
sudo add-apt-repository -y ppa:apptainer/ppa
sudo apt update
sudo apt install -y apptainer

Important!

Do not forget to comment in your ~/.bashrc sourcing your local Root installation (source /path/thisroot.sh), otherwise there will be a conflict of 2 ROOT versions: one - from your local installation, another - from STAR container on startup.

  • And then run commands:
apptainer run docker://ghcr.io/star-bnl/star-sw:main-root5-gcc485 bash -l
  • You may also create a shortcut for star-shell using code below:
mkdir -p ~/.local/bin && cat >~/.local/bin/star-shell <<'EOF'
#!/usr/bin/env bash
apptainer run  docker://ghcr.io/star-bnl/star-sw:main-root5-gcc485 "$@"
EOF
chmod +x ~/.local/bin/star-shell
grep -qxF 'export PATH="$HOME/.local/bin:$PATH"' ~/.bashrc || echo 'export PATH="$HOME/.local/bin:$PATH"' >>~/.bashrc
export PATH="$HOME/.local/bin:$PATH"

MacOS

Install Docker Desktop

brew install --cask docker-desktop

Then start Docker Desktop once (so the Docker daemon is running), and enter the STAR container with your current folder available inside the container:

docker run --rm -it \
  --platform linux/amd64 \
  -v "$PWD":/work -w /work \
  ghcr.io/star-bnl/star-sw:main-root5-gcc485 \
  bash -l

Important (ROOT conflict on macOS): macOS usually uses zsh, so your ROOT init might be in ~/.zshrc or ~/.zprofile (not ~/.bashrc). Comment out any source /path/thisroot.sh

This is the Docker equivalent of your Linux star-shell. It mounts the current directory into /work

mkdir -p ~/.local/bin && cat >~/.local/bin/star-shell <<'EOF'
#!/usr/bin/env bash
IMAGE="ghcr.io/star-bnl/star-sw:main-root5-gcc485"

# If no args provided -> interactive login shell
if [ $# -eq 0 ]; then
  set -- bash -l
fi

docker run -it --rm \
  --platform linux/amd64 \
  -v "$PWD":/work -w /work \
  "$IMAGE" "$@"
EOF

chmod +x ~/.local/bin/star-shell

# Add ~/.local/bin to PATH for zsh (default on macOS)
grep -qxF 'export PATH="$HOME/.local/bin:$PATH"' ~/.zshrc || echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
export PATH="$HOME/.local/bin:$PATH"

Now you can do:

star-shell