Get Started

Table of contents

1. Introduction
2. New Member Onboarding — Do These IN ORDER
3. Getting Set Up to Work
4. Software Setup:
5. 0) Preconditions
6. 1) Generate an SSH key (local) and upload .pub to SDCC
   1. Copy-paste script (local)
   2. Test: passwordless login
7. 2) VS Code: Remote-SSH
8. 3) Mount SDCC
9. 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

#	Step	Link
1	Get ORCID — required for STAR publications and the author list	orcid.org/register
2	BNL guest appointment — sponsored by your home institution’s BNL liaison or your STAR advisor. Required before the SDCC account	BNL Guest Registration
3	SDCC account — needed for Drupal login, computing, and disk quota	SDCC new user
4	Email BOTH your SDCC username AND ORCID to Rachel (current STAR Phonebook keeper) — see the prefilled template	Send 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:
   • starmail
   • star-talks
   • star-juniors
   • Your physics working group

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

• 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

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.

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

# 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.

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

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 ~/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

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 Linux 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

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 can do:

star-shell