client_CLI_install.md
... ...
@@ -0,0 +1,127 @@
1
+## SBGrid installation client CLI
2
+
3
+This page is for the SBGrid CLI (command line interface) software installation client for computers running Linux (CentOS/RHEL 6 or 7 recommended) or Apple OSX computers running MacOSX v10.9 - 10.12.
4
+
5
+A GUI version is also available for MacOS / OSX - [installation instructions can be found here](client_install).
6
+[GUI usage info is here](client_usage).
7
+
8
+### Pre-installation requirements
9
+
10
+**Admin access required on your computer.**
11
+ The SBGrid installation client 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 .
12
+
13
+**Existing SBGrid installations must be renamed or removed.**
14
+ If you have previously installed SBGrid software on your computer at /programs or at /opt/sbgrid, these directories should be removed or renamed. The client will create these on first run.
15
+
16
+**Hard Drive Space**
17
+ Depending on what you install, ensure you have enough free hard drive space on your machine.
18
+
19
+**For large packages (Phenix, Rosetta, CCP4), a wired connection is recommended.**
20
+ Some packages are quite large and can be slow to download, especially over WiFi.
21
+
22
+**pip**
23
+ pip is a package management system used to install and manage software packages written in Python. The software installation client is installable by pip. This may not be on you machine by default, instructions for adding it are included here.
24
+
25
+### pip - Mac Installation
26
+
27
+ On mac, pip is available from [macports](https://www.macports.org/), [homebrew](http://brew.sh/), and [fink](http://finkproject.org/). It also can be added using **easy_install**. easy_install will install pip into your system python.
28
+
29
+ $ sudo easy_install pip
30
+
31
+###pip - Linux Installation
32
+
33
+ On CentOS6, you can install pip from the EPEL repository (yum -y install python-pip) or as [per these directions](https://pip.pypa.io/en/stable/installing/)
34
+
35
+## CLI client - Installation and activation
36
+**1. Download the latest SBGrid installation client from here.**
37
+
38
+ [--> SBGrid CLI client download <-- ](downloads/SBGrid_Installer-1.0b2.dev412-py2.py3-none-any.whl)
39
+
40
+**2. Install / Upgrade with pip**
41
+
42
+ $ sudo pip install SBGrid_Installer-1.0b2.dev412-py2.py3-none-any.whl
43
+
44
+ Which should produce output similar to :
45
+
46
+```
47
+Unpacking ./SBGrid_Installer-1.0b2.dev412-py2.py3-none-any.whl
48
+Requirement already satisfied (use --upgrade to upgrade): pyasn1 in /nfs/programs-dev/i386-mac/python/2.7.5/lib/python2.7/site-packages (from SBGrid-Installer==1.0b2.dev412)
49
+Downloading/unpacking requests (from SBGrid-Installer==1.0b2.dev412)
50
+ Downloading requests-2.11.1.tar.gz (485kB): 485kB downloaded
51
+ Running setup.py egg_info for package requests
52
+
53
+ warning: no files found matching 'test_requests.py'
54
+Installing collected packages: SBGrid-Installer, requests
55
+ Running setup.py install for requests
56
+
57
+ warning: no files found matching 'test_requests.py'
58
+Successfully installed SBGrid-Installer requests
59
+Cleaning up...
60
+```
61
+
62
+The *sbgrid* command will produce this usage info :
63
+
64
+ $ sbgrid
65
+
66
+```
67
+usage:
68
+sbgrid <command> [<command_args>]
69
+
70
+Available commands are:
71
+ activate Activate new installation
72
+ list List available packages
73
+ info Print package metadata
74
+ install Install single package
75
+ install-all Install all packages from collection
76
+ installed List installed packages
77
+ remove Remove installed package
78
+ resume Resume interrupted installations
79
+ upgrades List available upgrades for installed packages
80
+ upgrade Upgrade package to latest version
81
+ upgrade-all Upgrade all packages to latest version
82
+ version Print package version string
83
+sbgrid: error: too few arguments
84
+
85
+```
86
+
87
+**4. Activate the installation**
88
+Enter your site and key which you should have received these by email. This key will expire at the end of the trial.
89
+
90
+ $ sbgrid activate <site name> <user name> <activation key>
91
+
92
+You may be prompted for your sudo password to create /programs and /opt/sbgrid.
93
+
94
+**5. On successful activation, list software titles.**
95
+
96
+ $ sbgrid list
97
+
98
+ If activation continues to fail, you may have an old SBGrid installation at /programs or /opt/sbgrid. These should be removed.
99
+
100
+You may also be blocked from accessing SBGrid servers on port 873 and port 8080 by your institution's firewall. You can check if you can access [port 873 here](http://portquiz.net:873) and [port 8080 here](http://portquiz.net:8080)
101
+
102
+For help, email *bugs@sbgrid.org.*
103
+
104
+### Installation on an external drive or USB key
105
+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.
106
+
107
+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.
108
+
109
+**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_client_install*. 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.
110
+
111
+Next move */opt/sbgrid* to the USB key at */Volumes/sbgrid_client_install*. You will likely need sudo for this.
112
+
113
+ $ sudo mv /opt/sbgrid /Volumes/sbgrid_client_install/.
114
+
115
+Now we have */Volumes/sbgrid_client_install/sbgrid*. Create a symlink from */opt/sbgrid* to */Volumes/sbgrid_client_install/sbgrid*.
116
+
117
+ $ sudo ln -s /Volumes/sbgrid_client_install/sbgrid /opt/sbgrid
118
+
119
+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.
120
+
121
+[SBGrid install client -- Usage info](client_usage)
122
+
123
+### Known issues
124
+
125
+* **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.
126
+
127
+* **Activation Failed**. In some cases the Authorization dialog for admin privileges does not appear during activation. This causes the client activation to fail. This is usually due to a previously existing /programs directory or symlink from a prior installation. This must be removed for activation to be successful. Other users have reported successful activation after a restart.
client_CLI_usage.md
... ...
@@ -0,0 +1,255 @@
1
+## SBGrid installation client - Usage
2
+
3
+This page is for the SBGrid CLI software installation client for computers running Linux (CentOS/RHEL 6 or 7 recommended) or Apple OSX computers running MacOSX v10.9 - 10.12.
4
+
5
+A GUI version is also available for mac - [installation instructions can be found here](client_install).
6
+[GUI usage info is here](client_usage).
7
+
8
+**Make sure you have installed the SBGrid software installation client according to the instructions here** --> [Installation Instructions](client_CLI_install).
9
+
10
+### General
11
+The SBGrid software installation client is a command line-based installer for the SBGrid software collection. The application allows for selected applications to be installed in the familiar SBGrid environment.
12
+
13
+The client displays software 'Collections' as a list.
14
+
15
+ $ sbgrid list
16
+
17
+```
18
+Crystallography
19
+ 3dna
20
+ adxv
21
+ albula
22
+ autoproc
23
+ ...
24
+
25
+NMR
26
+ aqua
27
+ aria
28
+ cara
29
+ ccpnmr
30
+ ccpnmr-chembuild
31
+ ...
32
+
33
+Electron Microscopy
34
+ 2dx
35
+ ace2
36
+ auto3dem
37
+ bfactor
38
+ bsoft
39
+ burnham-brandeis-helical-package
40
+ chimera
41
+ ...
42
+
43
+Structure Visualization & Analysis
44
+ 3dna
45
+ anaconda
46
+ apbs
47
+ aqua
48
+ bobscript
49
+ caver
50
+ caver-analyst
51
+ ccp4mg
52
+ chimera
53
+ ...
54
+
55
+Computational Chemistry
56
+ ambertools
57
+ apbs
58
+ appion
59
+ autodock
60
+ autodock-vina
61
+ avogadro
62
+ concoord
63
+ dock
64
+ gromacs
65
+ ...
66
+
67
+Other
68
+ a2ps
69
+ abyss
70
+ aline
71
+ amigos-ii
72
+ amps
73
+ assemble2
74
+ bamtools
75
+ ...
76
+```
77
+
78
+Information about each title, including a description and links to documentation can be show with the *sbgrid info <title>* command.
79
+
80
+### Example : Installing Albula
81
+
82
+ $ sbgrid info albula
83
+
84
+```
85
+Package: ALBULA
86
+Name slug: albula
87
+
88
+Available versions:
89
+* 3.2.0-2 (default)
90
+* 3.1.0-13
91
+* 3.0.0-14
92
+* 2.2.12
93
+
94
+Collection(s): Crystallography
95
+
96
+Description:
97
+ consists of the standalone program ALBULA VIEWER, a fast and easy-to-
98
+use program that allows optimal visualization of PILATUS and EIGER data,
99
+and ALBULA API, a Python programming interface for displaying images and
100
+performing operations and calculations. The API enables you to easily
101
+integrate the viewer functionality into your beamline infrastructure or
102
+experimental setup.
103
+
104
+Links:
105
+* Website: https://www.dectris.com/Albula_Overview.html
106
+```
107
+
108
+To install:
109
+
110
+ $ sbgrid install albula
111
+
112
+```
113
+Installing: albula
114
+Updating installation configuration...
115
+Installation was successfull!
116
+```
117
+
118
+To get started, load the SBGrid environment :
119
+
120
+ $ source /programs/sbgrid.shrc
121
+
122
+```
123
+ Software Support by SBGrid (www.sbgrid.org)
124
+********************************************************************************
125
+
126
+...
127
+
128
+SBGrid installation last updated: 2016-10-21
129
+Please submit bug reports and help requests to: <bugs@sbgrid.org> or
130
+ <http://sbgrid.org/bugs>
131
+********************************************************************************
132
+```
133
+
134
+### Example : Removing Albula
135
+
136
+ $ sbgrid remove albula
137
+
138
+results in :
139
+
140
+```
141
+Removing: albula
142
+Updating installation configuration...
143
+Package removed!
144
+```
145
+
146
+### Version selection
147
+
148
+Default versions are installed by default for each application, though individual versions can be selected for each title.
149
+
150
+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:
151
+
152
+ $ sbgrid info epmr
153
+
154
+```
155
+Package: EPMR
156
+Name slug: epmr
157
+
158
+Available versions:
159
+* 16.04 (default)
160
+* 16.01
161
+* 15.12
162
+* 15.04
163
+* 13.07
164
+* 11.02
165
+
166
+Collection(s): Crystallography
167
+
168
+Description:
169
+ a program that finds crystallographic molecular replacement solutions
170
+using an evolutionary search algorithm. The program directly optimizes
171
+three rotational and three positional parameters for the search model with
172
+respect to the correlation coefficient between Fo and Fc.
173
+
174
+Links:
175
+* Website: http://www.epmr.info/
176
+* Manual: http://www.epmr.info/UsersGuide.html
177
+```
178
+
179
+To install version 11.02, add the version string like so:
180
+
181
+ $ sbgrid install epmr 11.02
182
+
183
+which will produce :
184
+
185
+```
186
+Installing: epmr (11.02)
187
+Updating installation configuration...
188
+Installation was successfull!
189
+key@key-mbp [20161021-21:05:56] ~/Downloads
190
+```
191
+
192
+Check which versions are installed with the sbgrid info command again
193
+
194
+ $ sbgrid info epmr
195
+
196
+```
197
+epPackage: EPMR
198
+Name slug: epmr
199
+
200
+Available versions:
201
+* 16.04 (default)
202
+* 16.01
203
+* 15.12
204
+* 15.04
205
+* 13.07
206
+* 11.02 (installed)
207
+
208
+...
209
+
210
+```
211
+
212
+Confirm with the *sbwhich* command
213
+
214
+
215
+ $ sbwhich epmr
216
+```
217
+/programs/i386-mac/epmr/11.02/epmr
218
+```
219
+
220
+Reload the sbgrid shell to use the new version ( or set the environment variable EPMR_M=11.02 ).
221
+
222
+### Software Versions Management in the SBGrid environment
223
+If you have a single version of an application installed, explicit version selection in your environment is not needed.
224
+
225
+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*.
226
+
227
+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.
228
+
229
+**Version priority in the shell**
230
+ 1. *~/.sbgrid.conf*
231
+ 2. Installed single version
232
+ 3. Installed Default version
233
+ 4. Latest installed release
234
+
235
+There is more info on how to do that here --> [SBGrid version overrides](versions)
236
+
237
+### Running SBGrid software
238
+
239
+To use the software at the terminal in bash, open a new terminal and run
240
+
241
+ $ source /programs/sbgrid.shrc
242
+
243
+or in tcsh
244
+
245
+ $ source /programs/sbgrid.cshrc
246
+
247
+### Questions, Problems and Known Issues
248
+For questions or problems, the Help menu will direct to the SBGrid help page. Or just email *bugs@sbgrid.org*.
249
+If relevant, please include a screenshot of the GUI if possible (command + shift + 4) and please include the ~/Library/Application Support/SBGrid/sbgrid.log file with your report.
250
+
251
+**Known issues**
252
+
253
+* The application will fail if outbound port 873 and port 8080 are blocked by your institution or are otherwise not available.
254
+
255
+* In some cases the prompt for admin credentials fails to appear on activation. Be sure there is no prior SBGrid install on your machine at /programs or /opt/sbgrid.
client_install.md
... ...
@@ -0,0 +1,73 @@
1
+## SBGrid installation client
2
+
3
+This page is for the SBGrid GUI installation client for Apple OSX computers running MacOSX v10.9 - 10.12 .
4
+
5
+A command line version is also available for mac and linux - installation instuctions can be found here : [CLI installation](client_CLI_install).
6
+
7
+Usage info for the GUI and command line clients can be found here : [GUI Usage](client_usage) and here : [CLI usage](client_CLI_usage) respectively.
8
+
9
+### Pre-installation
10
+
11
+**1. Admin access required.**
12
+ The SBGrid installation client 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 .
13
+
14
+**2. Existing installations must be renamed or removed.**
15
+ If you have previously installed SBGrid software on your computer at /programs or at /opt/sbgrid, these directories should be removed or renamed. The client will create these on first run.
16
+
17
+**3. Ctrl-click or Allow Applications from 'Anywhere'.**
18
+ While the SBGrid installer will eventually be signed with the appropriate Apple developer's certificate, the initial builds are not. To run these, you need to give MacOSX's GateKeeper permission to run the application. You can either 'Ctrl-click' the icon and select 'Open' and then approve the application (see below), or permit your Mac to run applications from Anywhere in Preferences. You can do this under 'Preferences' -> 'Security and Privacy'. You may need admin privileges to change this setting.
19
+
20
+ ![GateKeeper](images/gatekeeper.png)
21
+
22
+**4. Hard Drive Space**
23
+ Depending on what you install, ensure that you have enough free hard drive space on your machine.
24
+
25
+**5. For large packages (Phenix, Rosetta, CCP4), a wired connection is recommended.**
26
+ Some packages are quite large and can be slow to download, especially over WiFi.
27
+
28
+### Installation and activation
29
+
30
+**1. Download the latest SBGrid installation client from here.**
31
+
32
+ [--> SBGrid MacOSX client download <-- ](downloads/SBGrid_Installer-21c46a9.dmg)
33
+
34
+**2. Mount the .dmg disk image on your Mac.** Copy the 'SBGrid installer.app' to a convenient location - it does not need to be in /Applications. The .app bundle can be run directly from the mounted dmg image with no installation if desired.
35
+
36
+**3. Run the SBGrid installer application. You may need to ctrl-click (or right-click) and select 'Open' to satisfy GateKeeper settings.**
37
+
38
+![ctrl-click](images/ctrl-click.png)
39
+![ctrl-click](images/client_permit.png)
40
+
41
+**4. Enter your site, user name, and key.** You should have received these by email.
42
+
43
+![activation](images/client_activation.png)
44
+
45
+On activation you will be prompted to provide admin credentials for your mac. This is to create the /opt/sbgrid directory and /programs symlink.
46
+
47
+![activation](images/client_permissions.png)
48
+
49
+**5. On successful activation, you should see the client populate with software titles.** If not, please close the application and try again. If activation continues to fail, you may have an old SBGrid installation at /programs or /opt/sbgrid. These should be removed. You may also be blocked from accessing SBGrid servers on port 873 and port 8080 by your institution's firewall. You can check if you can access [port 873 here](http://portquiz.net:873) and [port 8080 here](http://portquiz.net:8080)
50
+For help, email *bugs@sbgrid.org.*
51
+
52
+### Installation on an external drive or USB key
53
+Currently the installer application installs the software tree in /opt/sbgrid and uses a symlink at /programs. The /programs link is required for the software to work, but in principle the software can be anywhere by linking /opt/sbgrid to the desired installation point. This functionality is not yet included in the SBGrid application, but can be set up manually post-install with a symlink. First do an install (into /opt/sbgrid), then move it to the desired localtion. Then symlink to the new location from /opt/sbgrid.
54
+
55
+**Example:** 128Gb USB 'key' drives are available on Amazon for 30$ or less and are a nice way to supplement the small SSDs that come in Mac laptops. To install on an external drive in this way, first mount it on your computer. For this example, the mount is */Volumes/sbgrid_client_install*. 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.
56
+
57
+Next move */opt/sbgrid* to the USB key at */Volumes/sbgrid_client_install*. You will likely need sudo for this.
58
+
59
+ sudo mv /opt/sbgrid /Volumes/sbgrid_client_install/.
60
+
61
+Now we have */Volumes/sbgrid_client_install/sbgrid*. Create a symlink from */opt/sbgrid* to */Volumes/sbgrid_client_install/sbgrid*.
62
+
63
+ sudo ln -s /Volumes/sbgrid_client_install/sbgrid /opt/sbgrid
64
+
65
+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.
66
+
67
+[SBGrid install client -- Usage info](client_usage)
68
+
69
+### Known issues
70
+
71
+* **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.
72
+
73
+* **Activation Failed**. In some cases the Authorization dialog for admin privileges does not appear during activation. This causes the client activation to fail. This is usually due to a previously existing /programs directory or symlink from a prior installation. This must be removed for activation to be successful. Other users have reported successful activation after a restart.
client_usage.md
... ...
@@ -0,0 +1,85 @@
1
+## SBGrid installation client - Usage
2
+
3
+This trial is currently only for Apple OSX computers running MacOSX v10.9 - 10.12.
4
+
5
+**Make sure you have installed the SBGrid software installation client according to the instructions here** --> [Installation Instructions](client_install)
6
+
7
+### General
8
+The SBGrid software installation client is a GUI-based installer for the SBGrid software collection. The application allows for selected applications to be installed in the familiar SBGrid environment.
9
+
10
+ ![installed](images/client_install.png)
11
+
12
+The client GUI is displays software 'Collections' on the right panel with folder icons under the 'Packages' heading. These Collections control the list of titles displayed in the center 'main' panel.
13
+
14
+The first of two of these 'Collections' are shortcut meta-collections of the local machine. The first is the currently installed titles. The second icon, Updates, shows updates available from SBGrid. 'Pending' is a collection of pending installs and removals. Below these shortcuts are packages are grouped by primary scientific uses. Installation status is also indicated in theses collections.
15
+
16
+Information about each title, including a description and links to documentation are shown in the upper right panel when that title is selected in the main pane.
17
+
18
+Once packages have been configured for installation and/or removal by selecting their checkbox, clicking the 'Apply Changes' button will perform update the titles, adding pending installations and removing pending deletions.
19
+
20
+### Example : Installing Albula
21
+Check the box to select Albula, then click the 'Apply Changes' button.
22
+Notice the text turns green for pending installations. Pending updates are Orange.
23
+![apply](images/client_apply2.png)
24
+
25
+### Example : Removing Albula
26
+Uncheck the box for Albula. Removals are shown in red text.
27
+![apply](images/client_remove1.png)
28
+
29
+Click apply changes. Albula will be removed.
30
+![apply](images/client_remove2.png)
31
+
32
+### Version selection
33
+
34
+Default versions are installed by default for each application, though individual versions can be selected for each title. To do so, show the version pane by selecting **"Show all package versions"** from the **"View"** menu. Then, in the bottom right, select a desired version with the check boxes. Multiple versions of a given title can be installed and are indicated in the main panel.
35
+
36
+Enable version panel
37
+![all](images/client_versions1.png)
38
+
39
+Check old/non-default versions
40
+![all](images/client_versions2.png)
41
+
42
+
43
+### Versions and the SBGrid environment
44
+If you have a single version of an application installed, explicitly version selection in your environment will not be needed. In the case of multiple installed versions, the *SBGrid Default* version will be the version available at the terminal when installed, unless configured otherwise in *~/.sbgrid.conf*.
45
+
46
+If you have 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 either an older release or the non-default version when a default version is installed, you must set this explicitly in your *~/.sbgrid.conf* file as in the standard SBGrid environment.
47
+
48
+**Version priority in the shell**
49
+ 1. *~/.sbgrid.conf*
50
+ 2. Installed Default version
51
+ 3. Latest installed release
52
+
53
+You can do open the configuration file by selecting the *"Edit Configuration File"* from the *"SBGrid Installer"* menu.
54
+
55
+![all](images/client_config1.png)
56
+
57
+This will open a text editor with a sample configuration file, or your *~/.sbgrid.conf* file if you have one already.
58
+
59
+![all](images/client_config2.png)
60
+
61
+There is more info on how to do that here --> [SBGrid version overrides](versions)
62
+
63
+
64
+### Running the software
65
+
66
+To run the software, you can click the "SBGrid Shell" button for an initialized bash shell.
67
+
68
+You may also run the software from another terminal on your machine.
69
+To use the software at the terminal in bash, open a new terminal and run
70
+
71
+ source /programs/sbgrid.shrc
72
+
73
+or in tcsh
74
+
75
+ source /programs/sbgrid.cshrc
76
+
77
+### Questions, Problems and Known Issues
78
+For questions or problems, the Help menu will direct to the SBGrid help page. Or just email *bugs@sbgrid.org*.
79
+If relevant, please include a screenshot of the GUI if possible (command + shift + 4) and please include the ~/Library/Application Support/SBGrid/sbgrid.log file with your report.
80
+
81
+**Known issues**
82
+
83
+* The application will fail if outbound port 873 and port 8080 are blocked by your institution or are otherwise not available.
84
+
85
+* In some cases the prompt for admin credentials fails to appear on activation. Be sure there is no prior SBGrid install on your machine at /programs or /opt/sbgrid.