Using the SBGrid Environment
Support for Site Administrators
Hardware Support Notes
Support for Developers
One of the primary benefits of an SBGrid software installation is that it is a managed software stack. New titles are added, obsolete versions are removed, and updates happen automatically. New software and bug fixes are an email request away (email@example.com) without requiring local administrators or system admistration expertise. While there are other installation modes available (GUI, default versions, select titles, etc), this is the recommended mode of installation for most sites.
|Hard Drive Space||~1+ Tb recommended for full installation|
|Operating System||Linux, macOS|
|Privileges||sudo / root for initial install only|
|network||Outbound https, rsync|
Approximate size per Branch
|shared files||~50 Gb|
1. Create an 'sbgrid' user on the machine that will host your software installation. This step is not strictly required, but is highly recommended.
By default the SBGrid installation manager,
sbgrid-cli, will install at
/opt/sbgrid. This path typically requires sudo/root to create Linux and macOS. The sudo requirement can be skipped by using the
--target flag to specify an alternate installation location. This is usually preferred as /opt may be on a filesystem with insufficient capacity. The sbgrid user must have write access to this target directory.
2. Log in as the 'sbgrid' user
3. Download the sbgrid-cli application
To download directly to a server or workstation from the command line : For Linux:
curl -LO https://sbgrid.org/downloads/latest/sbgrid-cli_linux.tar.gz
curl -LO https://sbgrid.org/downloads/latest/sbgrid-cli_macos.tar.gz
4. Untar the archive
tar -zxvf sbgrid-cli_linux.tar.gz
5. Activate the installation
Activating the installation will create the required installation directories and core libraries for installing the software. Alternate installation paths can be used with the '--target flag'. The entire software collection will not be installed here - just an initial the core without the titles.
./sbgrid-cli activate-site --target <path to software installation location>
where the target path is writable. With --target, activation does not require sudo. The application will prompt for a site name and key which was provided by email. After this is entered and confirmed the software will be installed. A cron task is created for update checks.
The manual creation of the "/programs" symlink to the target installation directory will be required, but only for machines running the software. /programs is not needed for updates or servers that host the programs as a network share.
Once the download has completed, you'll need to add a "/programs" symlink in the root directory of each machine that wants to use the software. Typically, this directory is shared via NFS to each of your computers.
ln -s /path/to/sbgrid/install/target /programs
On macOS, root level symlinks must be defined in the /etc/synthetic.conf file. This is a simple configuration file, More info on synthetic.conf can be found here.
Any user that wishes to use SBGrid needs to configure their shell to initialize the SBGrid shell environment:
For bash: add
source /programs/sbgrid.shrc to ~/.bashrc
For tcsh: add
source /programs/sbgrid.cshrc to ~/.cshrc
Configure your workstations for compatibility: https://sbgrid.org/wiki/software/workstation_setup NOTE: XQuartz is required for many applications on macOS
sbgrid-cli admin mode replaces the sbgrid-admin script installation method used previously to install and automatically update SBGrid site installations.
sbgrid-cli admin offers a some advantages:
sbgrid-cli admin command will:
sbgrid-cli admin commands are typically run periodically from cron.
To install all default versions of all titles, add new titles when available, update all installed when available and remove obsolete versions, run :
To do the same but to include all versions of all titles :
sbgrid-cli admin --all-versions
To make this automatic, add a crontab entry. This can be done from
sbgrid-cli with this command:
Full auto mode - all versions, all titles mac and linux, 4 processes. This is the recommened installation configuration.
$ sbgrid-cli crontab --all-versions --darwin --linux -j 4
*/15 * * * * /programs/x86_64-linux/sbgrid_installer/latest/sbgrid-cli update --all-titles --linux --darwin --yes --quiet
* 1 * * * /programs/x86_64-linux/sbgrid_installer/latest/sbgrid-cli clean --yes --quiet
For more info on cron configuration, see https://www.man7.org/linux/man-pages/man5/crontab.5.html
To migrate an existing site-install that uses our sbgrid-admin script, use the
sbgrid-cli migrate-admin command as your sbgrid user. This will convert the legacy sbgrid-admin installation.
sbgrid@computer $ sbgrid-cli migrate-admin
When migrating from an sbgrid-admin "site" installation to a sbgrid-cli installation, the symlinks are likely to be already in place and the info about creating them can usually be ignored
warn: The RSYNC_ARGS in your sbgridrc will not be copied over to the new configuration file. warn: (in most cases sbgrid-cli doesn't require any custom arguments for rsync, so this should be fine) info: Retrieving package metadata... info: (1/9) Checking connection... info: Checking services... info: Checking sbgrid.org (HTTPS) ... info: Checking sbgrid.org (HTTP) ... info: (2/9) Checking rsync credentials... info: (3/9) Calling activate API endpoint... info: Site activation credentials provided, skipping API activation info: (4/9) Initializing installation directories... info: Please note that a link from the default installation directory /opt/sbgrid to the install target is required to run the software. A link from /programs to /opt/sbgrid is also required. info: (5/9) Synchronizing... info: (6/9) Synchronizing... info: (7/9) Installing firstname.lastname@example.org (x86_64-linux)... info: Installation complete for email@example.com (x86_64-linux) info: (8/9) Saving installation sitename file... info: (9/9) Setting up your installation... info: Setting all packages to installed & synchronizing your installation... info: (1/2) Installing the admin cron job... info: Cron job successfully installed to the current user's crontab info: (2/2) Setting up your installation... info: Migration to sbgrid-cli complete. The legacy configuration file has been renamed to /home/sbgrid/.sbgridrc_migrated
The default crontab is added by this process. You can set that with the
crontab -l command. This will check for updates every 15 minutes for the default software versions.
sbgrid@computer $ crontab -l */15 * * * * /programs/x86_64-linux/sbgrid_installer/latest/sbgrid-cli admin
To check for updates for all versions (recommended), run
sbgrid-cli crontab --all-versions which will create a crontab with the proper
sbgrid@computer $ crontab -l */15 * * * * /programs/x86_64-linux/sbgrid_installer/latest/sbgrid-cli admin --all-versions
Add the relevant
--linux flags to the crontab command if your installation should include software for macOS on linux or vice-versa, i.e. for an SBGrid installation shared across Mac and Linux workstations.