5c14baa9f276e45239f8fbfde8e003f519fca7a7
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.* |