Get Started

Introduction

Welcome to STAR! This is a checklist and starting point for new users joining the collaboration.

Main Steps Checklist:

1) Join Mattermost Software channel

2) Make a Drupal 2FA access for first login; if failed - ask Dmitry Arkhipkin or Jerome Lauret

3) Subscribe to mailing lists:

• starmail
• star-talks
• star-juniors
• your physics working group

4) Add yourself/Check for STAR Phone Book entry by writing to Liz Mogavero

Software Setup:

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

0) Preconditions

• SDCC account working with password login (first-time users must set up their account and add their SSH key manually)
• Local OpenSSH client (ssh, ssh-keygen)
• Local VS Code + extension Remote - SSH

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

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

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"  # replace with your key path if different
SDCC_USERNAME=$(whoami) # replace with your SDCC username if different from local

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
# legacy RCAS nodes
Host rcas60*
    HostName %h.rcf.bnl.gov
    User ${SDCC_USERNAME}
    ProxyJump ${SDCC_USERNAME}@ssh.sdcc.bnl.gov
    HostKeyAlgorithms +ssh-rsa
    PubkeyAcceptedKeyTypes +ssh-rsa
    RequestTTY yes
    ForwardAgent 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

2) VS Code: Remote-SSH

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.

3) Mount SDCC

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 ~/star
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} ~/star'" >> ~/.bashrc
source ~/.bashrc
starmount

4) Running STAR software locally (optional)

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

• You need to install either Docker engine or Apptainer (singularity). For simplier Apptainer (singularity) installation:

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

• 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"