Installing SBGrid Software
Using the SBGrid Environment
Support for Site Administrators
Hardware Support Notes
Getting Help
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 away (bugs@sbgrid.org) without requiring local administrators or system admistration expertise. While there are other modes available (GUI, granular versions, titles, etc), this is the recommended mode of installation for most sites.
Installation Requirements | |
---|---|
Hard Drive Space | ~1 Tb recommended for full installation |
Operating System | Linux, macOS |
Privileges | sudo root or administrator account (macOS) |
network | Outbound https, rsync |
Approximate size per Branch
Branch | size |
---|---|
i386-mac | ~400 Gb |
x86_64-linux | ~700 Gb |
shared files | ~50 Gb |
sbgrid-cli admin mode replaces the sbgrid-admin script installation method used previously to install and automatically update SBGrid installations. sbgrid-cli admin
offers a some advantages:
The sbgrid-cli admin
command will:
An SBGrid installation manager account is required. Please register here for an account https://sbgrid.org/registration/register/. Accounts are available for lab members and IT support staff.
1. Create an 'sbgrid' user on the machine that will host your software installation. This step is not strictly required, but is highly recommended.
adduser sbgrid
By default sbgrid-cli
will attempt to use sudo to create the install path at /opt/sbgrid
and symlink at /programs
.
The /programs
path is required to run the software.
The sudo requirement can be skipped by using the --target
flag to specify an alternate installation location.
The sbgrid user must have write access to this directory (detailed here).
If you would prefer the sbgrid-cli create the /programs
and the installation path, add the sbgrid user to sudo.
One method to do this is with this command:
echo 'sbgrid ALL=(ALL) ALL' > /etc/sudoers.d/sbgrid
This is only required for the activation step. The '/etc/sudoers.d/sbgrid' entry can be removed anytime after the installation is activated.
2. Log in as this 'sbgrid' user
su sbgrid
3. Download the sbgrid-cli application
https://sbgrid.org/wiki/client_downloads
For Linux:
curl -LO https://sbgrid-installation-manager.s3.amazonaws.com/2.5.7/sbgrid-cli_2.5.7-linux.tar.gz
For Mac:
curl -LO https://sbgrid-installation-manager.s3.amazonaws.com/2.5.7/sbgrid-cli_2.5.7-macos.tar.gz
4. Untar the archive
tar -zxvf sbgrid-cli_2.5.7-linux.tar.gz
5. Activate the installation
Activating the installation will create the required installation paths and directories for installing the software. This is the point where alternate installation paths can be used with the --target flag. Please see https://sbgrid.org//wiki/sbgrid-cli#activation for more info.
./sbgrid-cli activate <site> <user> <key>
If the sbgrid user does not have sudo access, use
./sbgrid-cli activate <site> <user> <key> --no-link --target=<path to where the software should be installed>
where the target path is writable. This option does not require sudo but will require manual creation of the /programs symlink to the target installation directory. This is not required for installation and updates, only for using the software. It may not be needed on servers that host the programs as a network share.
6. Run the installation using ./sbgrid-cli admin
7. Add to crontab for periodic updates using ./sbgrid-cli crontab
Once the download has completed, you'll need to add a 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 /programs
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 maximum compatibility:
To install all default versions of all titles, add new titles when available, update all installed when available and remove obsolete versions, run :
sbgrid-cli admin
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:
sbgrid-cli crontab
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
For more info on cron, see https://www.man7.org/linux/man-pages/man5/crontab.5.html
To migrate an existing site-install, use the sbgrid-cli migrate-admin
command as the sbgrid user. This will convert the legacy sbgrid-admin installation.
sbgrid@computer $ sbgrid-cli migrate-admin
Will produce
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 sbgrid-installer@2.5.7 (x86_64-linux)...
info: Installation complete for sbgrid-installer@2.5.7 (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
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
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 --all-versions
flag.
sbgrid@computer $ crontab -l
*/15 * * * * /programs/x86_64-linux/sbgrid_installer/latest/sbgrid-cli admin --all-versions
Add the relevant --darwin
or --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.
This version of the page was edited by Jason Key at 2021-11-15 18:01:12. View the most recent version.