sbgrid-cli version 2.1.3

+* [Site installation](managing_install)

+* [Command line installation manager](sbgrid-cli)

+* [Installation on macOS 10.15+ (Catalina, Big Sur)](catalina)

+* [Apple Silicon Support](big_sur)

+* [Software Usage Examples](examples)

+client_CLI_install-old.md

+## SBGrid command line installation manager - v2.1.2

+

+## How do I get it?

+[LINUX : sbgrid-cli_2.1.2_linux.tar.gz](https://sbgrid.org/wiki/downloads/sbgrid-cli_2.1.2_linux.tar.gz)

+

+[macOS : sbgrid-cli_2.1.2_macos.tar.gz](https://sbgrid.org/wiki/downloads/sbgrid-cli_2.1.2_macos.tar.gz)

+

+## Supported OSes

+[Linux (CentOS/RHEL 7 or 8 recommended) or Apple OSX computers running MacOSX v10.13 - 10.15.](operatingsystems)

+

+

+MacOS 10.15 Catalina can be used, but a work-around is required to add the /programs path.

+See [here for more info :](catalina)

+

+### Pre-installation requirements

+**Admin access required on your computer.**

+ The SBGrid installation manager will install the software tree to /opt/sbgrid and create a symlink from this directory to /programs.

+ While admin privileges are not required to run the application, you will likely need admin privileges to create /opt/sbgrid and /programs .

+

+```

+ $ ./sbgrid-cli

+Usage: sbgrid-cli [command] [options]

+

+Commands:

+ help [command] command-specific help

+

+ activate [options] <site user key> | <credential-key> activate a new installation

+ reactivate [options] <configFilePath> [packagesPath] reactivate installation using config or package list

+

+ install [options] [title] [otherTitles...] install package(s)

+ remove|uninstall [options] [title] [otherTitles...] remove package(s)

+ reinstall [options] [title] [otherTitles...] reinstall package(s)

+ update|upgrade [options] [title] [otherTitles...] update package(s) to the latest release/version

+

+ list [options] [title] list available software titles

+ installed list installed software titles

+ updates list available updates

+ pending list pending installations

+ obsolete list obsolete software titles

+ search <query> search availble titles

+ collections list available package collections

+ grids list available software trees

+ info [options] [title] print title information

+ shell start SBGrid Shell

+

+ clean [options] remove obsolete software versions and titles

+ admin [options] run periodic installation, update and clean up

+ rebuild rebuild installation environment

+ crontab [options] basic script for crontab

+ save [filename] save current configuration

+

+ check-connection connectivity checks

+ diag [options] troubleshooting and diagnostics

+ verify list missing software versions and .rc files

+

+ Options:

+ -V, --version version

+ --verbose verbose output

+ --quiet disable output

+ -h, --help usage information

+ --linux specify linux as platform

+ --darwin specify macOS as platform

+ --no-color disable output colors

+```

+

+## General Usage

+The SBGrid command line installation manager takes subcommands and arguments to those commands to perform various tasks. These can be found in the usage info shown above.

+Each subcommand can also take a -h or --help argument to show usage info.

+

+### Activation

+To install the software, you must have valid credentials provided by SBGrid.

+

+Activate with the 'activate' subcommand

+

+**activate**

+

+```

+Usage: activate [options] [site] [user] [key]

+

+activate new installation using credentials provided

+(credentials are sent via email and can either be a single credential-key, or a site username key triplet)

+

+Options:

+ -k, --credential-key <credential-key> activate with activation key

+ -h, --help output usage information

+```

+

+Trouble activating? See Troubleshooting options further down this page.

+

+**reactivate**

+

+*reactivate* can restore from a saved config file. See below.

+

+```

+ $ ./sbgrid-cli reactivate -h

+Usage: reactivate [options] <configFilePath> [packagesPath]

+

+reactivate a new instance of an installation using a “saved” configuration file

+to repair an existing installation see “reinstall --all-versions”

+

+Options:

+ --skip-folder-checking skip checking if folder with programs already exists

+ --just-activation skip software titles installation

+ -h, --help output usage information

+```

+

+### Listing available titles, status

+

+The *sbgrid list* command will show all available titles. They are normally colored by their installation status.

+Available options :

+

+**list**

+

+```

+Usage: list [options] [title] [otherTitles...]

+

+list available software titles

+

+Options:

+ -a, --all-versions list all available software versions

+ -d, --default-versions list default software versions

+ -c, --collections list available collections

+ -o, --one-column list software in one column

+ -l, --long-format list software versions in long format

+ -h, --help output usage information

+```

+

+**updates**

+

+Shows available updated version and titles

+

+```

+./sbgrid-cli updates

+```

+

+**obsolete**

+

+Shows obsolete versions that will be removed.

+Obsolete versions are previously installed versions no longer included in the SBGrid installation.

+

+```

+./sbgrid-cli obsolete

+```

+

+### Getting Information about titles

+

+**info**

+

+The *info* flag shows information about each title, including a description and links to documentation can be show with the *sbgrid info <title>* command. See example below.

+

+```

+Usage: info [options] [title] [otherTitles...]

+

+print software title(s) metadata

+

+Options:

+ -v, --versions list available and default versions for <title> on current platform

+ -c, --collections list available collections with software count

+ -h, --help output usage information

+```

+

+For example, info for RELION :

+

+```

+ $ ./sbgrid-cli info relion

+Fetching requested info...

+------------------------------------------------------------------------------------

+Package information for relion (i386-mac):

+

+Package: RELION

+Title: relion

+Architecture: i386-mac

+

+Available version(s):

+ * 1.3 (installed) depends on: openmpi (1.8.4)

+ * 1.4 (installed) depends on: openmpi (1.8.4)

+ * 2.1 (installed) depends on: openmpi (2.1.2)

+ * 3.0.6 (installed) depends on: openmpi (2.1.3)

+ * 3.0.7 (installed) depends on: openmpi (2.1.3)

+ * 3.0.8 (installed, default)

+ * 3.1-beta (installed)

+

+Grid(s): SBGrid

+Collection(s): Electron Microscopy

+

+Description:

+(REgularised LIkelihood OptimisatioN) a stand-alone computer program for Maximum A Posteriori (MAP) refinement of (multiple) 3D reconstructions or 2D class averages in cryo-electron microscopy.

+

+Technical notes:

+**GPU-accelerated RELION : ** RELION versions > 2.0 are GPU-accelerated using Nvidia CUDA on Linux.

+For general information on running GPU accelerated applications from SBGrid, please see here : https://sbgrid.org/wiki/gpu</a>

+

+CUDA builds of RELION are designated by a '_cu<cuda_version>' suffix in the version of the application.

+For example, 2.0.4_cu7.5 is linked against CUDA v7.5 libraries and is not recommended for Pascal architecture Nvidia hardware (GTX 1080 and higher). 2.0.4_cu8.0 is built with CUDA 8.0 which supports Pascal architecture GPUs. The '_SP' designation indicates 'single precision' CPU builds. All builds are single precision on the GPU and can be run on 'consumer-grade' GPU hardware.

+

+**RELION and MPI : **

+RELION uses the 'mpirun' executable to manage MPI ranks. SBGrid includes two OpenMPI versions, 2.1.2 (default) and 1.8.4 (legacy).

+The OpenMPI mpirun executable must match the version of OpenMPI used to build RELION.

+For example, RELION versions 2.1_cu*.0 use OpenMPI version 2.1.2 and must use mpirun from 2.1.2.

+

+Older RELION versions require an override in $HOME/.sbgrid.conf to set the older OpenMPI version to 1.8.4. Add

+

+OPENMPI_X=1.8.4"

+

+to $HOME/.sbgrid.conf and open a new terminal to use the correct mpirun.

+You can also use the 'mpirun.relion' executable in place of mpirun to use the MPI that matches the currently configured version of RELION.

+

+Links:

+ Website: http://www2.mrc-lmb.cam.ac.uk/relion/index.php/Main_Page

+ Manual: http://www2.mrc-lmb.cam.ac.uk/relion/index.php/Main_Page

+ Forumhelp: https://www.jiscmail.ac.uk/cgi-bin/webadmin?A0=CCPEM

+```

+

+### Installing and removing

+

+Install and remove titles with the *sbgrid install <title>* and *sbgrid remove <title>* command. Each of these commands can take multiple titles with versions at one time.

+

+**install**

+

+```

+install software title(s)

+

+Options:

+ -d, --all-default install all default versions of all available software titles

+ -a, --all-versions install all versions of all available software titles

+ -c, --collection <collection> install all software titles from collection

+ title@all install all versions of a software title

+ title@x.y.z install "x.y.z" version of a software title

+ -p, --progress-bar show progress bar during installation

+ -y, --yes continue without confirmation

+ -h, --help output usage information

+```

+

+**Install examples :**

+

+Install a single default version of an application :

+

+```

+./sbgrid-cli install relion

+```

+

+Install a specific version of a relion :

+

+```

+ ./sbgrid-cli install relion@3.0.8

+```

+

+Install all versions of relion :

+

+```

+ ./sbgrid-cli install relion@all

+```

+

+Install the 'Electron Microscopy' collection of titles (see above *list* command to list *collections*):

+

+```

+ $ ./sbgrid-cli install -c 'Electron Microscopy'

+```

+

+Install all default versions of all titles :

+

+```

+ ./sbgrid-cli install --all-defaults

+```

+

+Install all versions of all titles ( The full collection):

+

+```

+ ./sbgrid-cli install --all-versions

+```

+

+**remove**

+

+Same options as install flag above.

+

+```

+remove software title(s)

+

+Options:

+ -d, --all-default remove all default versions of all installed software titles

+ -n, --non-default remove all non-default versions of all installed software titles

+ -a, --all-versions remove all versions of all installed software titles

+ -c, --collection <collection> remove all software titles from collection

+ title@all remove all installed versions of a software title

+ title@x.y.z remove "x.y.z" version of a software title

+ -y, --yes continue without confirmation

+ -h, --help output usage information

+```

+

+### Updating titles

+

+Updates are performed when default titles change to a new version or bugs are fixed in existing verisons. To update, use the update flag.

+

+**update**

+

+```

+./sbgrid-cli update relion

+```

+

+### Remove obsolete titles

+

+Use the obsolete flag to list or remove obsolete versions or titles

+

+**obsolete**

+

+```

+ $ ./sbgrid-cli obsolete -h

+Usage: obsolete [options]

+

+list obsolete software versions

+

+Options:

+ -r, --remove remove the obsolete software versions

+ -y, --yes continue without confirmation

+ -h, --help output usage information

+

+```

+

+## Advanced modes

+

+The advanced modes perform multiple actions and are designed for automated use for a managed 'rolling release' installation.

+

+**clean**

+

+Removes all obsolete software versions and titles

+

+**admin**

+

+Run periodic installation, update and removal. Installs all new titles, updates where appropriate and cleans up (removes) obsolete versions

+

+```

+Usage: admin [options]

+

+periodic update and installation

+

+Options:

+ -a, --all-versions install all versions of all available software titles

+ -r, --reinstall reinstall all of installed software titles

+ -h, --help output usage information

+```

+

+For example running

+

+```

+./sbgrid-cli admin

+```

+

+will install all default, update all installed titles and remove all obsolete versions while

+

+```

+./sbgrid-cli admin -a

+```

+

+will install all versions of all titles, add any new titles, update any pending updates, and remove obsolete versions.

+This

+

+

+**rebuild**

+

+*rebuild* rebuilds the installation environment configuration files.

+

+**crontab**

+

+Writes a basic script for crontab for *admin* functionality

+

+**save**

+

+The *save* flag saves the current configuration so it can be restored at a later stage or replicated on another machine (or in the cloud).

+

+

+## Troubleshooting and diagnostics

+

+**check-connection**

+connectivity checks

+

+**diag**

+troubleshooting and diagnostics

+

+**verify**

+list missing software versions and .rc files

+

+## Installing software for multiple platforms

+

+On linux, add the --darwin command to install / remove for macOS .

+Conversely, use the --linux command to install / remove for Linux while on macOS.

+

+```

+ --linux specify linux as platform

+ --darwin specify macOS as platform

+```

+The platform flag is implied for the platform used to install the software.

+

+

+### Software Version Management in the SBGrid environment

+If you have a single version of an application installed, explicit version selection in your environment is not needed.

+

+In the case of multiple installed versions, the *SBGrid Default* version will be the version available at the terminal when it is installed, unless configured otherwise in *~/.sbgrid.conf*. This is standard for the SBGrid software environment.

+

+In the case of multiple non-default versions installed, the *latest release* will be version available in your shell. If you would like to have more than one version of a title installed, and prefer to use an older release or the non-default version when a default version is installed, you must set this explicitly in your *~/.sbgrid.conf* file. This is the same as in the standard SBGrid environment.

+

+**Version priority in the shell**

+ 1. *~/.sbgrid.conf*

+ 2. Installed single version

+ 3. Installed Default version

+ 4. Latest installed release

+

+There is more info on how to do that here --> [SBGrid version overrides](versions)

+

+### Running SBGrid software

+

+To use the software at the terminal in bash, open a new terminal and run

+

+ $ source /programs/sbgrid.shrc

+

+or in tcsh

+

+ $ source /programs/sbgrid.cshrc

+

+### Known Issues

+

+* **rsync required on 873 or 8080**. The application will fail if outbound port 873 and port 8080 are blocked by your institution or are otherwise not available. You can check if you can access [port 873 here](http://portquiz.net:873) and [port 8080 here](http://portquiz.net:8080)

+

+For help or to report issues, please email *bugs@sbgrid.org.*

+## SBGrid command line installation manager

+

+ - [Installation](#installation)

+ - [Pre-installation requirements](#installation_pre-installation-requirements)

+ - [Binary releases : MacOS and Linux Installation](#installation_binary-releases)

+ - [Installation on an external drive or USB key](#installation_installation-on-an-external-drive-or-usb-key)

+ - [General Usage](#general-usage)

+ - [Activation](#general-usage_activation)

+ - [Listing available titles](#general-usage_listing-available-titles)

+ - [Getting Information](#general-getting-information-about-titles)

+ - [Installing and Removing Titles](#general-usage_installing-and-removing)

+ - [Updating packages](#general-usage_updating-titles)

+ - [Example : Installing Albula](#general-usage_example-installing-albula)

+ - [Example : Removing Albula](#general-usage_example-removing-albula)

+ - [Version selection](#general-usage_version-selection)

+ - [Software Version Management in the SBGrid environment](#general-usage_software-version-management-in-the-sbgrid-environment)

+ - [Running SBGrid software](#general-usage_running-sbgrid-software)

+ - [Known Issues](#general-usage_known-issues)

+

+## Installation

+The SBGrid software stack can be installed using our command line program for [Linux (CentOS/RHEL 7 or 8 recommended) or Apple OSX computers running MacOSX v10.13 - 10.15.](operatingsystems)

+CentOS 6 is no longer supported.

+

+Two software installers are available. Binary releases are available for MacOS and CentOS operating systems.

+

+The SBGrid installation manager requires an individual account. To get started, first, set up an account by registering here : [SBGrid registration](https://sbgrid.org/registration/register/)

+

+**Check out [Jason Key's presentation on SBGrid installation tools](https://www.youtube.com/watch?v=sAxIzWhWX5o&t=1s)**

+

+### Pre-installation requirements

+**Admin access required on your computer.**

+ The SBGrid installation manager will install the software tree to /opt/sbgrid and create a symlink from this directory to /programs. While admin privileges are not required to run the application, you will need admin privileges to create /opt/sbgrid and /programs. The install manager currently relies on 'sudo' for these tasks and should in installed from an account with sudo privileges. While not strictly required, we recommend a dedicated 'sbgrid' user account for software management. This ensures the software can't be modified by user accounts and that data won't be mistakenly saved into the software stack and possibly inadvertantly deleted by software updates.

+

+**Existing SBGrid installations must be renamed or removed.**

+ If you have previously installed SBGrid software on your computer at /programs or at /opt/sbgrid, these directories should be removed or renamed. The manager will create these on first run.

+

+**Hard Drive Space**

+ Depending on what you install, ensure you have enough free hard drive space on your machine.

+

+**For large packages (Phenix, Rosetta, CCP4), a wired connection is recommended.**

+ Some packages are quite large and can be slow to download, especially over WiFi.

+

+### Binary releases

+Binary releases of the install manager are recommended - there is minimal installation needed for these binaries and they can be run from any location with no dependencies. Untar the archive, make the file executable if necessary, and run from your preferred location.

+

+[Mac : 1.0.695, 2020-05-31](downloads/sbgrid-1.0.695-Darwin.tgz)

+

+[Linux : 1.0.695, 2020-05-31](downloads/sbgrid-1.0.695-Linux.tgz)

+

+```

+$ tar -zxf sbgrid-1.0.695-Darwin.tgz

+

+$ cd sbgrid-1.0.695-Darwin

+

+$ ./sbgrid

+usage:

+sbgrid <command> [<command_args>]

+

+Available commands are:

+

+Query packages:

+ collections list available collections

+ grids list available grids

+ info get detailed information on a particular package

+ installed list all installed packages

+ list list available packages

+ search list and search installed packages

+ updates list available updates

+

+Manage packages:

+ install install packages

+ install-all

+ rebuild rebuild installation of all installed packages

+ remove / uninstall remove installed packages

+ resume resume interrupted installations

+ update update installed package

+ update-all

+

+Environment:

+ shell Load sbgrid environment

+

+Installation management

+ activate activate new installation

+ admin cron mode

+ autoclean removes unused packages

+ reactivate reactivate installation using existing config and package database/list

+ save save current configuration

+

+Additional arguments:

+ -h, --help show usage information and exit current platform

+ -l, --info-versions list available and default versions for <program> on current platform

+ -L, --info-all-versions list available and default versions for <program> on all platforms

+ --debug enable verbose logging

+sbgrid: error: too few arguments

+```

+

+### Installation on an external drive or USB key

+Currently the installer application installs the software tree in /opt/sbgrid and uses a symlink at /programs. This link is required for the software to work, but in principle the software can be located anywhere and linked to /opt/sbgrid. This functionality is not yet included in the SBGrid application, but can be set up manually with a symlink.

+

+An installation can be made on an external drive if you first do an install (into /opt/sbgrid), then move it and symlink to the new location.

+

+**Example:** 128Gb USB 'key' drives are available on Amazon for 30$ or less and are a nice way to supplement the SSDs that come in Mac laptops. To install on an external drive like this, mount it on your computer. For this example, the mount is */Volumes/sbgrid_installation*. Then, using the SBGrid installer, do an initial installation on the hard drive. To make life easy, just do one application. Then close the installer application.

+

+Next move */opt/sbgrid* to the USB key at */Volumes/sbgrid_installation*. You will likely need sudo for this.

+

+ $ sudo mv /opt/sbgrid /Volumes/sbgrid_installation/.

+

+Now we have */Volumes/sbgrid_installation/sbgrid*. Create a symlink from */opt/sbgrid* to */Volumes/sbgrid_installation/sbgrid*.

+

+ $ sudo ln -s /Volumes/sbgrid_installation/sbgrid /opt/sbgrid

+

+The symlink at */programs* still points to */opt/sbgrid*, and that is a link that points to the external location. Open the installer and add the desired applications. These will now install to the external drive.

+

+## General Usage

+The SBGrid command line installation manager takes subcommands and arguments to those commands to perform various tasks. These can be found in the usage info shown above. Each subcommand can also take a -h or --help argument to show more detailed usage info. For example, the 'install' subcommand can take several arguments :

+

+```

+$ ./sbgrid install --help

+usage: sbgrid install [-h] [--all-versions] title [title ...]

+

+Install package.

+

+positional arguments:

+title package name or package_name@version

+

+optional arguments:

+-h, --help show this help message and exit

+--all-versions install all versions for a package

+```

+

+### Activation

+To install the software, you must have valid credentials provided by SBGrid.

+

+Activate with the 'activate' subcommand

+```

+usage: sbgrid activate [-h] [--multibranch] site user key

+

+Activate new installation.

+

+positional arguments:

+ site site name

+ user user name

+ key activation key

+

+optional arguments:

+ -h, --help show this help message and exit

+ --multibranch enable installation for all architectures

+

+```

+

+The *--multibranch* option allows for installation of Linux or Mac software on server that should host both platforms, usually for access of NFS. This must be set at activation. Once set, Linux and Mac titles will be installed.

+

+### Listing available titles

+

+The *sbgrid list* command will show all available titles colored by their installation status. Installed titles are green, those with available updates are blue, and titles to be removed are red. Software is listed by 'Collection'.

+

+```

+$ ./sbgrid list

+-- Crystallography -------------------------------------------------------------------------------------------------------------------------

+3dna eden pdb_redo solveresolve

+adxv eiger2cbf pdb-validation-suite somore

+albula elves

+...

+-- NMR -------------------------------------------------------------------------------------------------------------------------------------

+aqua gamma nmrview remediator

+aria haddock pales shiftx2

+...

+

+-- Electron Microscopy ---------------------------------------------------------------------------------------------------------------------

+2dx particle

+ace2 pft3dr

+auto3dem phoelix

+bfactor powerfit

+bsoft priismive

+burnham-brandeis-helical-package python-macromolecular-library

+chimera refmac

+crop relion

+...

+

+```

+

+### Getting Information about titles

+

+Information about each title, including a description and links to documentation can be show with the *sbgrid info <title>* command. See example below.

+

+### Installing and removing

+

+Install and remove titles with the *sbgrid install <title>* and *sbgrid remove <title>* command. Each of these commands can take multiple titles with versions at one time.

+

+```

+ $ ./sbgrid info epmr

+Package: EPMR

+

+Available versions:

+ * 16.01 (installed)

+ * 16.04 (installed)

+ * 16.07.1 (installed, default)

+

+Grids(s): SBGrid

+Collection(s): Crystallography

+

+Description:

+ a program that finds crystallographic molecular replacement solutions

+using an evolutionary search algorithm. The program directly optimizes

+three rotational and three positional parameters for the search model with

+respect to the correlation coefficient between Fo and Fc.

+

+Links:

+ Website: http://www.epmr.info/

+ Manual: http://www.epmr.info/UsersGuide.html

+

+```

+```

+ $ ./sbgrid info adxv

+Package: adxv

+

+Available versions:

+ * 1.9.10

+ * 1.9.11

+ * 1.9.12 (installed, default)

+ * 1.9.7

+

+Grids(s): SBGrid

+Collection(s): Crystallography

+

+Description:

+ displays protein crystallography X-ray diffraction data. The data may

+be displayed as a 2-D image, 3-D wire mesh or as integer pixel values. Data

+files may be saved in tiff or postscript format.

+

+Technical notes:

+ Adxv will display data from most current detectors: ADSC ccd Mar

+ccd APS 3x3 ccd Mar image plate (old and new format) Raxis II & IV Fuji

+image plate Crystallographic Binary Format (CBF) XDS .pck files Raw

+binary 8, 16 & 32 bit integer data

+

+Links:

+ Website: http://www.scripps.edu/tainer/arvai/adxv.html

+ Manual: http://www.scripps.edu/tainer/arvai/adxv/AdxvUserManual.pdf

+```

+```

+ $ ./sbgrid install adxv epmr epmr@16.01

+adxv@1.9.12 installed

+epmr@16.07.1 installated

+epmr@16.01 installed

+Updating installation configuration...

+

+```

+When a version string is not specified, the default version is installed or removed.

+

+### Updating titles

+

+Show titles with a pending update with the *sbgrid updates* command. Updates can be applied with the *sbgrid update <title>* or *sbgrid update-all* commands.

+

+### Example : Installing Albula

+

+ $ sbgrid info albula

+

+```

+Package: ALBULA

+Name : albula

+

+Available versions:

+* 3.2.0-2 (default)

+* 3.1.0-13

+* 3.0.0-14

+* 2.2.12

+

+Collection(s): Crystallography

+

+Description:

+ consists of the standalone program ALBULA VIEWER, a fast and easy-to-

+use program that allows optimal visualization of PILATUS and EIGER data,

+and ALBULA API, a Python programming interface for displaying images and

+performing operations and calculations. The API enables you to easily

+integrate the viewer functionality into your beamline infrastructure or

+experimental setup.

+

+Links:

+* Website: https://www.dectris.com/Albula_Overview.html

+```

+

+To install:

+

+ $ sbgrid install albula

+

+```

+Installing: albula

+Updating installation configuration...

+Installation was successfull!

+```

+

+To get started, load the SBGrid environment :

+

+ $ source /programs/sbgrid.shrc

+

+```

+ Software Support by SBGrid (www.sbgrid.org)

+********************************************************************************

+

+...

+

+SBGrid installation last updated: 2016-10-21

+Please submit bug reports and help requests to: <bugs@sbgrid.org> or

+ <http://sbgrid.org/bugs>

+********************************************************************************

+```

+

+### Example : Removing Albula

+

+ $ sbgrid remove albula

+

+results in :

+

+```

+Removing: albula

+Updating installation configuration...

+Package removed!

+```

+

+### Version selection

+

+Default versions are installed by default for each application, though individual versions can be selected for each title.

+

+To do so, include the version after the title followed the version. To see what versions are available, use the *sbgrid info <title>* command. Let;s us the title epmr as an example here:

+

+ $ sbgrid info epmr

+

+```

+Package: EPMR

+Name : epmr

+

+Available versions:

+* 16.04 (default)

+* 16.01

+* 15.12

+* 15.04

+* 13.07

+* 11.02

+

+Collection(s): Crystallography

+

+Description:

+ a program that finds crystallographic molecular replacement solutions

+using an evolutionary search algorithm. The program directly optimizes

+three rotational and three positional parameters for the search model with

+respect to the correlation coefficient between Fo and Fc.

+

+Links:

+* Website: http://www.epmr.info/

+* Manual: http://www.epmr.info/UsersGuide.html

+```

+

+To install version 11.02, add the version string like so:

+

+ $ sbgrid install epmr@11.02

+

+which will produce :

+

+```

+Installing: epmr (11.02)

+Updating installation configuration...

+Installation was successfull!

+```

+

+Check which versions are installed with the sbgrid info command again

+

+ $ sbgrid info epmr

+

+```

+epPackage: EPMR

+Name slug: epmr

+

+Available versions:

+* 16.04 (default)

+* 16.01

+* 15.12

+* 15.04

+* 13.07

+* 11.02 (installed)

+

+...

+

+```

+

+Confirm with the *sbwhich* command

+

+ $ sbwhich epmr

+```

+/programs/i386-mac/epmr/11.02/epmr

+```

+

+Reload the sbgrid shell to use the new version ( or set the environment variable EPMR_M=11.02 ).

+

+### Software Version Management in the SBGrid environment

+If you have a single version of an application installed, explicit version selection in your environment is not needed.

+

+In the case of multiple installed versions, the *SBGrid Default* version will be the version available at the terminal when it is installed, unless configured otherwise in *~/.sbgrid.conf*.

+

+In the case of multiple non-default versions installed, the *latest release* will be version available in your shell. If you would like to have more than one version of a title installed, and prefer to use an older release or the non-default version when a default version is installed, you must set this explicitly in your *~/.sbgrid.conf* file. This is the same as in the standard SBGrid environment.

+

+**Version priority in the shell**

+ 1. *~/.sbgrid.conf*

+ 2. Installed single version

+ 3. Installed Default version

+ 4. Latest installed release

+

+There is more info on how to do that here --> [SBGrid version overrides](versions)

+

+### Running SBGrid software

+

+To use the software at the terminal in bash, open a new terminal and run

+

+ $ source /programs/sbgrid.shrc

+

+or in tcsh

+

+ $ source /programs/sbgrid.cshrc

+

+

+### Known Issues

+

+* **rsync required on 873 or 8080**. The application will fail if outbound port 873 and port 8080 are blocked by your institution or are otherwise not available. You can check if you can access [port 873 here](http://portquiz.net:873) and [port 8080 here](http://portquiz.net:8080)

+

+For help, email *bugs@sbgrid.org.*

+sbgrid-cli.md

+## SBGrid command line installation manager, sbgrid-cli

+

+### Installation

+The SBGrid software stack can be installed using our command line program for [Linux (CentOS/RHEL 7 or 8 recommended) or Apple OSX computers running MacOSX v10.13 - 10.15.](operatingsystems). CentOS 6 is no longer supported.

+

+macOS 10.15 "Catalina" and macOS 11.0 "Big Sur" can be used, but a `/etc/syntetic.conf` file is required to add the /programs path.

+See [here for more info :](catalina)

+

+The SBGrid installation manager requires an account. Set up an account by registering here : [SBGrid registration](https://sbgrid.org/registration/register/)

+

+### Requirements and recommendations

+

+ The SBGrid installation manager will install the software collection to `/opt/sbgrid` by default (though this can be changed). A symlink from `/programs` to the installation directory is required and this step does require admin priveleges. **Admin privileges are not required to run the applications**. This is only for the initial installation, specifically the creation of /opt/sbgrid (if desired) and for `/programs` (required).

+

+ The `sbgrid-cli` install manager uses 'sudo' for priveleged installation tasks. As such, it should be used from an account with sudo privileges if this functionality is desired. Alternatively, software installation can be competed without sudo and the `/programs` link can be added manually later. The software will not be functional without this path.

+

+ While not strictly required, we recommend a dedicated 'sbgrid' user account for software management, particularly on multiuser systems. This ensures the software can't be modified by user accounts and that data won't be mistakenly saved into the software stack and lost inadvertantly during software updates. The `sbgrid-cli` program will add and remove software. **If data files are accidentally saved into the software collection, they are likely to be lost.**

+

+### v2.1.3 download

+

+[LINUX : sbgrid-cli_2.1.3_linux.tar.gz](https://sbgrid.org/wiki/downloads/sbgrid-cli_2.1.3_linux.tar.gz)

+

+[macOS : sbgrid-cli_2.1.3_macos.tar.gz](https://sbgrid.org/wiki/downloads/sbgrid-cli_2.1.3_macos.tar.gz)

+

+## General Usage

+The SBGrid command line installation manager takes subcommands and arguments to those commands to perform various tasks. These can be found in the usage info shown above. Each subcommand can also take a -h or --help argument to show more detailed usage info. For example :

+

+

+```

+$ sbgrid-cli install --help

+```

+

+will produce the help info for the `install` subcommand.

+

+

+

+### Activation

+To install the software, you must activate your installation with valid credentials provided by SBGrid. This process is only required for the initial installation of the software and is not required to add/remove/upgrade titles.

+

+Activate with the `activate` subcommand

+

+```

+ $ ./sbgrid-cli activate --help

+

+ SBGrid Installer 2.1.3 f593932a17 —

+ _______ _____ _ __

+ / __/ _ )/ ___/___(_)__/ /

+ _\ \/ _ / (_ / __/ / _ /

+ /___/____/\___/_/ /_/\_,_/

+ C o n s o r t i u m

+

+

+ USAGE — activate

+

+ ▸ sbgrid-cli activate [site] [user] [key] [OPTIONS...]

+

+

+ ARGUMENTS

+

+ [site] The installation site provided in your activation

+ credentials

+ [user] The username provided in your activation credentials

+ [key] The activation key provided in your activation

+ credentials

+

+ OPTIONS

+

+ -k, --credential-key <key> Activate with a single credential key

+ --darwin Specify macOS as a platform

+ --no-link No symlink creation, no sudo prompt.

+ --linux Specify Linux as a platform

+ --skip-folder-checking Skips checking if a folder with programs already exists

+ -t, --target <target> Specify a custom installation target

+

+```

+

+Some useful options here are :

+

+**--no-link**

+

+Don't create a symlink at `/programs`. Useful for installs without sudo

+

+**--skip-folder-checking**

+

+Don't check if software is already installed. Will overwrite existing installations.

+

+**--target <target>**

+

+Set the install directory to a different path than `/opt/sbgrid`

+

+Trouble activating? See Troubleshooting options further down this page.

+

+### Restoring from a saved config - reactivate

+

+**reactivate** can restore from a saved config file. This config includes all titles and versions from a saved installation. Useful for moving installations or reproducing installations.

+

+```

+sbgrid-cli reactivate <configPath> [OPTIONS...]

+```

+

+### Listing available titles, status

+

+The `sbgrid-cli list` command will show all available titles. They are normally colored by their installation status.

+Available options :

+

+**list**

+

+```

+-a, --all-versions List all available versions for a title

+-c, --collections List the available software collections

+-d, --default-versions List only the default version for a title

+--long-format Use the long format to display the title list

+--one-column Format the output into a single column

+```

+

+**updates**

+

+`sbgrid-cli updates` Shows available updated titles and versions

+

+```

+$ sbgrid-cli updates

+------------------------------------------------------------------------------------

+info: Retrieving package metadata...

+The following installed packages have updates available (x86_64-linux):

+- cryodrgn@0.3.0b => 0.3.1 (new default)

+- imod@4.11.0 (patch for installed default version)

+- ligplotplus@2.2 (patch for installed default version)

+- r@3.6.2 (patch for installed version)

+```

+

+Updates are either new default versions (new default), or updates to an existing version (patch for installed version). The patch versions are usually bug or configuration fixes.

+

+**obsolete**

+

+Shows obsolete versions that will be removed.

+Obsolete versions are previously installed versions no longer included in the SBGrid installation.

+

+```

+sbgrid-cli obsolete [OPTIONS...]

+```

+

+### Getting Information about titles

+

+**info**

+

+The *info* subcommand shows information about each title, including a description and links to documentation can be show with the `sbgrid-cli info <title>` command. See example below.

+

+```

+sbgrid-cli info <title...> [OPTIONS...]

+```

+

+For example, info for RELION :

+

+```

+$ sbgrid-cli info relion

+------------------------------------------------------------------------------------

+Package information for relion (x86_64-linux):

+

+Package: RELION

+Name slug: relion

+Architecture: x86_64-linux

+

+Available version(s):

+ * 1.3 (installed) depends on: openmpi (1.8.4)

+ * 1.4 (installed) depends on: openmpi (1.8.4)

+ * 1.4b (installed) depends on: openmpi (1.8.4)

+ * 1.4-randomphase3d (installed) depends on: openmpi (1.8.4)

+ * 2.1_cu8.0 (installed) depends on: cuda (8.0), openmpi (2.1.2)

+ * 3.0.4_cu9.0 (installed) depends on: cuda (9.0), openmpi (2.1.2)

+ * 3.0.8 (installed) depends on: openmpi (2.1.3)

+ * 3.0.8_cu10.1 (installed) depends on: cuda (10.1), openmpi (2.1.2)

+ * 3.0.8_cu8.0 (installed) depends on: cuda (8.0), openmpi (2.1.2)

+ * 3.0.8_cu8.0_slurm20 (installed) depends on: cuda (8.0.44), openmpi (3.1.6_slurm-20.02.03)

+ * 3.0.8_cu9.0 (installed) depends on: cuda (9.0), openmpi (2.1.2)

+ * 3.0.8_cu9.2 (installed) depends on: cuda (9.2), openmpi (2.1.2)

+ * 3.1.0 (installed) depends on: openmpi (3.1.6)

+ * 3.1.0_cu10.2 (installed) depends on: cuda (10.2.89), openmpi (3.1.6)

+ * 3.1.0_cu8.0 (installed) depends on: cuda (8.0.44), openmpi (3.1.6_compat)

+ * 3.1.0_cu8.0_compat (installed) depends on: cuda (8.0.44), openmpi (3.1.6_compat)

+ * 3.1.0_cu8.0_slurm20 (installed) depends on: cuda (8.0.44), openmpi (3.1.6_slurm-20.02.03)

+ * 3.1.0_cu9.2 (installed) depends on: cuda (9.2.88), openmpi (3.1.6)

+ * 3.1.1 (installed) depends on: openmpi (3.1.6)

+ * 3.1.1_cu9.2 (installed, default) depends on: cuda (9.2.88), openmpi (3.1.6)

+

+Grid(s): sbgrid

+Collection(s): Electron Microscopy

+

+Description:

+(REgularised LIkelihood OptimisatioN) a stand-alone computer program for Maximum A Posteriori (MAP) refinement of (multiple) 3D reconstructions or 2D

+class averages in cryo-electron microscopy.

+

+Technical notes:

+## SBGrid Usage Info RELION versions > 2.0 are GPU-accelerated using Nvidia CUDA on Linux. For general information on running GPU accelerated applications from SBGrid, please see here : https://sbgrid.org/wiki/gpuCUDA builds of RELION re designated by a '_cu' suffix in the version of the application. For example, 3.1.0_cu9.2 is linked against CUDA v9.2 libraries. All builds are single precision on the GPU and can be run on 'consumer-grade' GPU hardware.RELION builds without CUDA support are compiled with Intel 2019.5 with accelation options and Intel math libraries. ### RELION and MPI versionsRELION uses the 'mpirun' executable to manage MPI "ranks" for parallel processing. SBGrid includes several OpenMPI versions which are matched to specific RELION versions. When called from the SBGrid capsule environment, the relion GUI is configured to use the correct version of OpenMPI to manage parallel processing. When calling RELION binaries from the command line, the `mpirun.relion` executable can be used. `mpirun.relion` is configured to used the correct version of OpenMPI for each version of RELION. The 3.1.* versions for RELION use the default configuration of OpenMPI (3.1.6 on Linux, 2.1.3 on macOS) and do not require the version to be defined. Older releases use OpenMPI 2.1.2 which should be specified in $HOME/.sbgrid.conf. To set the OpenMPI version, add : OPENMPI_X=2.1.2"to $HOME/.sbgrid.conf and open a new terminal to use the correct mpirun. As noted above, you can also use the `mpirun.relion` executable in place of `mpirun` to use the MPI that matches the currently configured version of RELION. In this case, no other configuration is needed.Version 3.1.0_cu8.0 is compiled to support legacy CPUs (pre-Haswell). OpenMPI 3.1.6_compat is also needed for this version.Versions 3.1.0_cu8.0_slurm20 3.1-beta_cu8.0_slurm20 and 3.0.8_cu8.0_slurm20 support Slurm v20 PMI library. ## Recent Changes20201111 : Add 3.1.1 RELION versions20200703 : Add 3.1.0 release version20200629 : reconfigure RELION gui to automatically use correct 'mpirun' in capsules.20200610 : rebuild of 3.1-beta releases with OpenMPI 3.1.6 from commit 5997001.

+

+## Known Issues20200610 : Empty values in GUI during autopicking can be interpreted as Text instead of Float values. ## Deprecated versionsThe following verions are deprecated and will be removed in a future SBGrid update.20200706: 3.0.8_cu10.1 3.0.8_cu9.2 3.0.8_avx2 3.1-beta_cu9.2 3.1-beta_cu10.1

+

+## (c) Copyright 2008, Structural Biology Grid (www.sbgrid.org)## Last Update to this document# Jason Key 0a6b896 2020-11-15 18:39:38 -0500

+

+Links:

+ Website: http://www2.mrc-lmb.cam.ac.uk/relion/index.php/Main_Page

+ Manual: http://www2.mrc-lmb.cam.ac.uk/relion/index.php/Main_Page

+ Forumhelp: https://www.jiscmail.ac.uk/cgi-bin/webadmin?A0=CCPEM

+```

+

+The `info` subcommand includes all version info, dependencies ( which are automatically installed), technical notes and relevant links.

+

+### Installing and removing

+

+Install and remove titles with the `sbgrid-cli install <title>` and `sbgrid-cli remove <title>` command. Each of these commands can take multiple titles with versions at one time.

+

+**install**

+

+```

+ sbgrid-cli install [title...] [OPTIONS...]

+

+ ARGUMENTS

+

+ [title...] The name(s) of the software title(s) to install. To

+ specify a non-default version, append @ and the version

+ number to the name of the title (e.g. xyz@1.2.3).

+

+ OPTIONS

+

+ --all-titles Installs all the available titles

+ --all-versions This will install all the available versions for a

+ specified title or collection

+ -c, --collection <title> The title of a software collection to install

+ --darwin Specify macOS as a platform

+ --linux Specify Linux as a platform

+ -j, --num-workers <num-workers> Run installation tasks in parallel

+ number, default: 1

+ --reinstall Force the reinstallation of already installed packages

+```

+

+Install examples :

+Install a single default version of an application, `adxv` :

+

+```

+$ sbgrid-cli install adxv

+ - Install adxv@1.9.14 (x86_64-linux)

+ - Installation setup (x86_64-linux).

+Continue? … yes

+info: (1/2) Installing adxv@1.9.14 (x86_64-linux)...

+info: Installation complete for adxv@1.9.14 (x86_64-linux)

+info: (2/2) Setting up your installation...

+$

+```

+

+Install a specific version of a adxv :

+

+```

+ $ sbgrid-cli install adxv@1.9.11

+```

+

+Install all versions of adxv :

+

+```

+ $ sbgrid-cli install adxv --all-versions

+```

+

+Install the 'Electron Microscopy' collection of titles (see above *list* command to list *collections*):

+

+```

+ $ sbgrid-cli install -c 'Electron Microscopy'

+```

+

+Install all default versions of all titles :

+

+```

+ $ sbgrid-cli install --all-titles

+```

+

+Install all versions of all titles ( The full collection):

+

+```

+ $ sbgrid-cli install --all-titles --all-versions

+```

+

+Note the `--reinstall` flag can be added to all commands to reinstall titles that have already been installed.

+

+**remove**

+

+Same options as install flag above.

+

+```

+sbgrid-cli remove [title...] [OPTIONS...]

+```

+

+### Updating titles

+

+Updates are performed when default titles change to a new version or bugs are fixed in existing verisons. To update, use the update flag.

+

+**update**

+

+```

+$ sbgrid-cli update relion

+```

+

+### Remove obsolete titles

+

+Use the clean subcommand to list or remove obsolete versions or titles

+

+**clean**

+

+```

+sbgrid-cli clean [OPTIONS...]

+```

+

+### Advanced modes

+

+**admin**

+

+Run periodic installation, update and removal. Installs all new titles, updates where appropriate and removes obsolete versions

+

+```

+sbgrid-cli admin

+```

+

+For example running

+

+```

+$ sbgrid-cli admin

+```

+

+will install all default, update all installed titles and remove all obsolete versions while

+

+```

+$ sbgrid-cli admin --all-versions

+```

+

+will install all versions of all titles, add any new titles, update any pending updates, and remove obsolete versions.

+This

+

+

+**rebuild**

+

+`rebuild` rebuilds the installation environment configuration files. Usually this step is automatic but can be run manually for troubleshooting.

+

+```

+$ sbgrid-cli rebuild

+```

+

+**crontab**

+

+Writes a basic script for crontab for *admin* functionality

+

+**save**

+

+The *save* flag saves the current configuration so it can be restored at a later stage or replicated on another machine or in the cloud.

+

+

+### Troubleshooting and diagnostics

+

+**check-connection**

+

+Provides network diagnostics for connectivity to SBGrid at Harvard Medical School.

+

+```

+ $ sbgrid-cli check-connection

+info: (1/1) Checking connection...

+info: Checking services...

+info: Checking sync2.sbgrid.org (port: 8080) ...

+info: Checking sync2.sbgrid.org (port: 873) ...

+info: Checking sync2.sbgrid.org (port: 27010) ...

+info: Checking sbgrid.org (HTTPS) ...

+info: Checking sbgrid.org (HTTP) ...

+info: Connectivity test succeeded, all remote services are reachable

+```

+

+**diag**

+Run troubleshooting and diagnostic tests for the software collection.

+

+**verify**

+Lists missing software versions and .rc files.

+

+### Installing software for multiple platforms

+On linux, add the --darwin command to install / remove for macOS .

+Conversely, use the --linux command to install / remove for Linux while on macOS.

+These flags can be added to many of the subcommands to limit to Linux or macOS.

+Useful for servers that share a software stack over NFS.

+

+```

+sbgrid-cli list --darwin

+```

+This will list all software available for macOS.

+The flag is implied for the platform used to install the software, i.e. on linux, `--linux` is redundant.

+

+### Software Version Management in the SBGrid environment

+If you have a single version of an application installed, explicit version selection in your environment is not needed.

+

+In the case of multiple installed versions, the *SBGrid Default* version will be the version available at the terminal when it is installed, unless configured otherwise in *~/.sbgrid.conf*.

+

+In the case of multiple non-default versions installed, the *latest release* will be version available in your shell. If you would like to have more than one version of a title installed, and prefer to use an older release or the non-default version when a default version is installed, you must set this explicitly in your *~/.sbgrid.conf* file. This is the same as in the standard SBGrid environment.

+

+**Version priority in the shell**

+ 1. *~/.sbgrid.conf*

+ 2. Installed single version

+ 3. Installed Default version

+ 4. Latest installed release

+

+There is more info on how to manage versions here --> [SBGrid version overrides](versions)

+

+### Running SBGrid software

+

+To use the software at the terminal in bash, open a new terminal and run

+

+ $ source /programs/sbgrid.shrc

+

+or in tcsh

+

+ $ source /programs/sbgrid.cshrc

+

+

+For more info on system configuration for SBGrid software, please check here ---> [Workstation setup](workstation_setup).

+

+### Known Issues

+

+ **rsync required on 873 or 8080**. The application will fail if outbound port 873 and port 8080 are blocked by your institution or are otherwise not available. You can check if you can access [port 873 here](http://portquiz.net:873) and [port 8080 here](http://portquiz.net:8080)

+

+

+### Deprecated releases

+

+for the [sbgrid-cli version 1, see here](cli_v1)

+

+For help or to report issues, please email *bugs@sbgrid.org.*