cli_beta.md
... ...
@@ -0,0 +1,333 @@
1
+## SBGrid command line installation client - v2 beta release
2
+
3
+## How do I get it?
4
+
5
+email accounts@sbgrid.org with your info and we'll hook you up.
6
+
7
+## Supported OSes
8
+[Linux (CentOS/RHEL 6 or 7 recommended) or Apple OSX computers running MacOSX v10.11 - 10.14.](operatingsystems)
9
+
10
+### Pre-installation requirements
11
+**Admin access required on your computer.**
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
+```
15
+ $ ./sbgrid
16
+Usage: sbgrid [command] [options]
17
+
18
+Commands:
19
+ help [command] command-specific help
20
+
21
+ activate [options] <site user key> | <credential-key> activate a new installation
22
+ reactivate [options] <configFilePath> [packagesPath] reactivate installation using config or package list
23
+
24
+ install [options] [title] [otherTitles...] install package(s)
25
+ remove|uninstall [options] [title] [otherTitles...] remove package(s)
26
+ reinstall [options] [title] [otherTitles...] reinstall package(s)
27
+ update|upgrade [options] [title] [otherTitles...] update package(s) to the latest release/version
28
+
29
+ list [options] [title] list available software titles
30
+ installed list installed software titles
31
+ updates list available updates
32
+ pending list pending installations
33
+ obsolete list obsolete software titles
34
+ search <query> search availble titles
35
+ collections list available package collections
36
+ grids list available software trees
37
+ info [options] [title] print title information
38
+ shell start SBGrid Shell
39
+
40
+ clean [options] remove obsolete software versions and titles
41
+ admin [options] run periodic installation, update and clean up
42
+ rebuild rebuild installation environment
43
+ crontab [options] basic script for crontab
44
+ save [filename] save current configuration
45
+
46
+ check-connection connectivity checks
47
+ diag [options] troubleshooting and diagnostics
48
+ verify list missing software versions and .rc files
49
+
50
+ Options:
51
+ -V, --version version
52
+ --verbose verbose output
53
+ --quiet disable output
54
+ -h, --help usage information
55
+ --linux specify linux as platform
56
+ --darwin specify macOS as platform
57
+ --no-color disable output colors
58
+```
59
+
60
+## General Usage
61
+The SBGrid command line installation client takes subcommands and arguments to those commands to perform various tasks. These can be found in the usage info shown above.
62
+Each subcommand can also take a -h or --help argument to show usage info.
63
+
64
+### Activation
65
+To install the software, you must have valid credentials provided by SBGrid.
66
+
67
+Activate with the 'activate' subcommand
68
+
69
+```
70
+Usage: activate [options] [site] [user] [key]
71
+
72
+activate new installation using credentials provided
73
+(credentials are sent via email and can either be a single credential-key, or a site username key triplet)
74
+
75
+Options:
76
+ -k, --credential-key <credential-key> activate with activation key
77
+ -h, --help output usage information
78
+```
79
+
80
+Trouble activating? See Troubleshooting options further down this page.
81
+
82
+### Listing available titles, status
83
+
84
+The *sbgrid list* command will show all available titles. They are normally colored by their installation status.
85
+Available options :
86
+
87
+list
88
+
89
+```
90
+Usage: list [options] [title] [otherTitles...]
91
+
92
+list available software titles
93
+
94
+Options:
95
+ -a, --all-versions list all available software versions
96
+ -d, --default-versions list default software versions
97
+ -c, --collections list available collections
98
+ -o, --one-column list software in one column
99
+ -l, --long-format list software versions in long format
100
+ -h, --help output usage information
101
+```
102
+
103
+**updates**
104
+See available updates
105
+
106
+```
107
+./sbgrid updates
108
+```
109
+
110
+**obsolete**
111
+See obsolete versions
112
+```
113
+./sbgrid obsolete
114
+```
115
+
116
+### Getting Information about titles
117
+
118
+**info**
119
+
120
+Information about each title, including a description and links to documentation can be show with the *sbgrid info <title>* command. See example below.
121
+
122
+```
123
+Usage: info [options] [title] [otherTitles...]
124
+
125
+print software title(s) metadata
126
+
127
+Options:
128
+ -v, --versions list available and default versions for <title> on current platform
129
+ -c, --collections list available collections with software count
130
+ -h, --help output usage information
131
+```
132
+
133
+For RELION :
134
+
135
+```
136
+ $ ./sbgrid info relion
137
+Fetching requested info...
138
+------------------------------------------------------------------------------------
139
+Package information for relion (i386-mac):
140
+
141
+Package: RELION
142
+Title: relion
143
+Architecture: i386-mac
144
+
145
+Available version(s):
146
+ * 1.3 (installed) depends on: openmpi (1.8.4)
147
+ * 1.4 (installed) depends on: openmpi (1.8.4)
148
+ * 2.1 (installed) depends on: openmpi (2.1.2)
149
+ * 3.0.6 (installed) depends on: openmpi (2.1.3)
150
+ * 3.0.7 (installed) depends on: openmpi (2.1.3)
151
+ * 3.0.8 (installed, default)
152
+ * 3.1-beta (installed)
153
+
154
+Grid(s): SBGrid
155
+Collection(s): Electron Microscopy
156
+
157
+Description:
158
+(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.
159
+
160
+Technical notes:
161
+**GPU-accelerated RELION : ** RELION versions > 2.0 are GPU-accelerated using Nvidia CUDA on Linux.
162
+For general information on running GPU accelerated applications from SBGrid, please see here : https://sbgrid.org/wiki/gpu</a>
163
+
164
+CUDA builds of RELION are designated by a '_cu<cuda_version>' suffix in the version of the application.
165
+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.
166
+
167
+**RELION and MPI : **
168
+RELION uses the 'mpirun' executable to manage MPI ranks. SBGrid includes two OpenMPI versions, 2.1.2 (default) and 1.8.4 (legacy).
169
+The OpenMPI mpirun executable must match the version of OpenMPI used to build RELION.
170
+For example, RELION versions 2.1_cu*.0 use OpenMPI version 2.1.2 and must use mpirun from 2.1.2.
171
+
172
+Older RELION versions require an override in $HOME/.sbgrid.conf to set the older OpenMPI version to 1.8.4. Add
173
+
174
+OPENMPI_X=1.8.4"
175
+
176
+to $HOME/.sbgrid.conf and open a new terminal to use the correct mpirun.
177
+You can also use the 'mpirun.relion' executable in place of mpirun to use the MPI that matches the currently configured version of RELION.
178
+
179
+Links:
180
+ Website: http://www2.mrc-lmb.cam.ac.uk/relion/index.php/Main_Page
181
+ Manual: http://www2.mrc-lmb.cam.ac.uk/relion/index.php/Main_Page
182
+ Forumhelp: https://www.jiscmail.ac.uk/cgi-bin/webadmin?A0=CCPEM
183
+```
184
+
185
+### Installing and removing
186
+
187
+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.
188
+
189
+**install**
190
+
191
+```
192
+install software title(s)
193
+
194
+Options:
195
+ -d, --all-default install all default versions of all available software titles
196
+ -a, --all-versions install all versions of all available software titles
197
+ -c, --collection <collection> install all software titles from collection
198
+ title@all install all versions of a software title
199
+ title@x.y.z install "x.y.z" version of a software title
200
+ -p, --progress-bar show progress bar during installation
201
+ -y, --yes continue without confirmation
202
+ -h, --help output usage information
203
+```
204
+
205
+Install a single default version of an application :
206
+
207
+```
208
+./sbgrid install relion
209
+```
210
+
211
+Install a specific version of a title :
212
+
213
+```
214
+ ./sbgrid install relion@3.0.8
215
+```
216
+
217
+Install all versions of a titles :
218
+
219
+```
220
+ ./sbgrid install relion@all
221
+```
222
+
223
+Install a collection of titles :
224
+
225
+```
226
+ $ ./sbgrid install -c 'Electron Microscopy'
227
+```
228
+
229
+Install all default versions of all titles :
230
+
231
+```
232
+ ./sbgrid install --all-defaults
233
+```
234
+
235
+Install all versions of all titles :
236
+
237
+```
238
+ ./sbgrid install --all-versions
239
+```
240
+
241
+**remove**
242
+
243
+Same options as install
244
+
245
+```
246
+remove software title(s)
247
+
248
+Options:
249
+ -d, --all-default remove all default versions of all installed software titles
250
+ -n, --non-default remove all non-default versions of all installed software titles
251
+ -a, --all-versions remove all versions of all installed software titles
252
+ -c, --collection <collection> remove all software titles from collection
253
+ title@all remove all installed versions of a software title
254
+ title@x.y.z remove "x.y.z" version of a software title
255
+ -y, --yes continue without confirmation
256
+ -h, --help output usage information
257
+```
258
+
259
+### Updating titles
260
+
261
+**update**
262
+
263
+```
264
+./sbgrid update relion
265
+```
266
+
267
+## Advanced modes
268
+
269
+**clean**
270
+
271
+Removes all obsolete software versions and titles
272
+
273
+**admin**
274
+
275
+run periodic installation. Install all new, update all and clean up all obsolete versions
276
+
277
+**rebuild**
278
+
279
+rebuild installation environment
280
+
281
+**crontab**
282
+
283
+Writes a basic script for crontab
284
+
285
+
286
+**save**
287
+
288
+save current configuration
289
+
290
+
291
+## Troubleshooting and diagnostics
292
+
293
+**check-connection**
294
+connectivity checks
295
+
296
+**diag**
297
+troubleshooting and diagnostics
298
+
299
+**verify**
300
+list missing software versions and .rc files
301
+
302
+
303
+### Software Version Management in the SBGrid environment
304
+If you have a single version of an application installed, explicit version selection in your environment is not needed.
305
+
306
+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.
307
+
308
+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.
309
+
310
+**Version priority in the shell**
311
+ 1. *~/.sbgrid.conf*
312
+ 2. Installed single version
313
+ 3. Installed Default version
314
+ 4. Latest installed release
315
+
316
+There is more info on how to do that here --> [SBGrid version overrides](versions)
317
+
318
+### Running SBGrid software
319
+
320
+To use the software at the terminal in bash, open a new terminal and run
321
+
322
+ $ source /programs/sbgrid.shrc
323
+
324
+or in tcsh
325
+
326
+ $ source /programs/sbgrid.cshrc
327
+
328
+
329
+### Known Issues
330
+
331
+* **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)
332
+
333
+For help, email *bugs@sbgrid.org.*