Project

General

Profile

Start with existing ANY Linux flavor OS » History » Version 29

Amber Herold, 03/17/2010 03:23 PM

1 1 Amber Herold
h1. Start with existing ANY Linux flavor OS
2
3 3 Amber Herold
{{>toc}}
4
5 1 Amber Herold
*Appion Install Manual Referenced to Leginion Installation*
6
7
=====================
8
9
_The Appion Team_
10
11
email: *appion@scripps.edu* for any help you need.
12
13 2 Amber Herold
h2. 1. Introduction 
14 1 Amber Herold
15 2 Amber Herold
This document describes a general installation of Appion, concentrating on the installation and setup on the database and web servers.  Most sections refer to the Leginon installation documentation since the two share the same general architecture.   If you want to run real Leginon on the microscope, you just need to follow the additional installation starting from "Processing Server Window Installation Chapter of Leginon installation manual":http://emg.nysbc.org/documentation/leginon/bk02ch04s08.php.
16 1 Amber Herold
17 15 Amber Herold
h2. 2 Setup MySQL databases 
18 2 Amber Herold
19 28 Amber Herold
h3. see "Leginon database server-side installation manual":http://emg.nysbc.org/documentation/leginon/bk01ch04s07.php  for details, including how to increasing cache size. 
20 2 Amber Herold
21
h3. Preliminary steps if you have an existing project database from a previous installation 
22
23 1 Amber Herold
We need to remove a table in the project database called "install".  This will allow the new default tables to be defined when we set up on the web-server side.
24 2 Amber Herold
25
<pre>
26 1 Amber Herold
$ mysql projectdata -u usr_object
27
mysql> drop table install;
28
mysql> exit
29 2 Amber Herold
</pre>
30
31
32
h3. Additional work 
33
34 1 Amber Herold
You need to decide what prefix you will use for the processing databases.  We will be creating them on the fly later.  Our default is *ap* followed by a project id number.  More about this later.
35
At this point, you need to do the following to grant privileges to users for any database whose name starts with *ap*
36 2 Amber Herold
37
<pre>
38 1 Amber Herold
$ mysql -u root -p
39 2 Amber Herold
</pre>
40
41 1 Amber Herold
Note: If you didn't set a mysql root password, don't use -p option.
42 2 Amber Herold
43
<pre>
44 1 Amber Herold
mysql> GRANT ALL PRIVILEGES ON `ap%`.* TO usr_object@"%";
45
mysql> exit
46
</pre>
47 2 Amber Herold
48 16 Amber Herold
h2. 3 Web server side installation 
49 3 Amber Herold
50 29 Amber Herold
[[Web Server Installation]]
51
52
*TODO:* The following steps are most likely no longer needed here:
53
54 3 Amber Herold
h3. Follow instructions in "Leginon Database server-side installation manual":http://emg.nysbc.org/documentation/leginon/bk01ch04s07.php. 
55 2 Amber Herold
56 3 Amber Herold
h3. Continue with the instructions in "Leginon Web server set up and Installation":http://emg.nysbc.org/documentation/leginon/bk02ch04s08.php. 
57 1 Amber Herold
58 29 Amber Herold
59 26 Amber Herold
60 2 Amber Herold
h3. Additional work 
61 3 Amber Herold
62 4 Amber Herold
* Edit project`_`1`_`2/config.php to assign the same prefix to your processing db as defined in your MyQL setup.
63 2 Amber Herold
64
<pre>
65 1 Amber Herold
$DEF_PROCESSING_PREFIX = "ap";
66 2 Amber Herold
</pre>
67
68 4 Amber Herold
* Enable the processing plug-in by uncommenting out the following line in the file`dbem_1_5_1/config.php`
69 2 Amber Herold
70
<pre>
71 1 Amber Herold
addplugin("processing");
72 2 Amber Herold
</pre>
73
74 4 Amber Herold
* Copy `dbem_1_5_1/processing/config_processing.php.template` to `dbem_1_5_1/processing/config_processing.php`
75
* Edit `dbem_1_5_1/processing/config_processing.php`
76 2 Amber Herold
77
<pre>
78 1 Amber Herold
$PROCESSING_DB_HOST = "your_db_host";
79
$PROCESSING_DB_USER = "usr_object";
80
$PROCESSING_DB_PASS = ""; 
81
$PROCESSING_DB = "";
82
</pre>
83 2 Amber Herold
84
    Remember that the last line should be kept empty as this will be set dynamically.
85 1 Amber Herold
86
We will not include the processing host or cluster registration now. It is covered in the last part of this document.
87
88 16 Amber Herold
h2. 4 Create a test project and processing database
89 2 Amber Herold
90
h3. Follow the instructions on "how to create new project":http://emg.nysbc.org/documentation/leginon/bk02ch06.php in the Leginon Manual.
91
92
h3. Additional work 
93
94
# Click on a project name on the webpage `http://your_host/project_1_2/project.php`. This will take you to a new webpage `http://your_host/project_1_2/getproject.php?pId=1`.  The number following "pId=" depends on the project id automatically assigned to the project.
95
# At the end of the Info table, you should see:
96
97
<pre>
98 1 Amber Herold
processing db*: not set (create processing db) *db name* ap1
99 2 Amber Herold
</pre>
100
101 7 Amber Herold
You can create the default numbered style database ap... or give it a new name with the same prefix.  If you want to specify a database name that does not use the default prefix, please note that your db user specified in the config.php in project_1_2 needs to have the necessary privileges for that database.  You may additionally want to change the value assigned to $DEF_PROCESSING_PREFIX in project_1_2/config.php if you want to use your new prefix all the time.
102 6 Amber Herold
# Enter the processing database name and click "create processing db".
103 2 Amber Herold
# The page should refresh and display the linked database like this:
104
105
<pre>
106 1 Amber Herold
processing db: ap1
107 2 Amber Herold
</pre>
108 1 Amber Herold
109 7 Amber Herold
See next section on trouble shooting if you get the original page instead.
110
111 1 Amber Herold
* *Repeat the above process for all your projects.*
112
113
If you want all your processing databases combined in one single database (not recommended, as this becomes large very fast), just use the same name for all your projects.
114
115
The above procedure not only creates the database, but also create some of the tables that you need to start processing.
116 2 Amber Herold
117
h3. Trouble Shooting 
118
119 1 Amber Herold
If the 'getproject.php' webpage remains unchanged, your processing database link is not accepted.  This is usually
120
caused by an incorrect setting such as:
121 2 Amber Herold
# The mysql user does not have the privileges to create the named database.
122 7 Amber Herold
    See Section-5.3 on what you should do.  To try it again after your mysql correction, you should repeat Section-5.2 to allow reinitialization from the project_1_2 web page and then try 7.2 again.
123 2 Amber Herold
# You have accessed an earlier version of project web page after you reinitialized the install table in your existing project database.
124 1 Amber Herold
    The install table in the project database is set to deny further changes once any project web page is accessed.  As a result, required table property changes and new table insertion would fail.
125
    Here is how to fix it:
126 2 Amber Herold
# Repeat Seciont-5.2 to allow reinitialization.
127
# Try Section-7.2 again.
128 1 Amber Herold
129 14 Amber Herold
h2. 5 Processing server side installation 
130 2 Amber Herold
131
h3. Follow "Leginon processing-server-side installation on Linux":http://emg.nysbc.org/documentation/leginon/bk02ch04s05.php 
132
133
h3. Additional work 
134
135 4 Amber Herold
* Go to your Leginon installation directory (typically /usr/lib/python2.4/site-packages/Leginon/)
136 2 Amber Herold
* Edit project.py. Change line 5 to:
137
138
<pre>
139 1 Amber Herold
use_processingdb_table = True
140 2 Amber Herold
</pre>
141
142
* Add the appionData module to sinedon.cfg, which you have already modified during the Leginon installation.
143
144
<pre>
145 1 Amber Herold
[appionData]
146
user:	usr_object
147 2 Amber Herold
</pre>
148
149 17 Amber Herold
150
*[Note]* The module names in brackets are case sensitive and need to be exact.
151 1 Amber Herold
The user name needs to match the name for which privileges have been granted on the `ap%` databases.
152
153 17 Amber Herold
154 2 Amber Herold
h3. Download and install pyappion 
155 1 Amber Herold
156 19 Amber Herold
h4. Install prerequisite processing packages that are not included in the Leginon installation
157
158
Find a list of these packages [[Appion_Installation_Manual#Packages-not-included-in-the-Leginon-installation|here]]. 
159 2 Amber Herold
160 1 Amber Herold
h4. "Download pyappion":http://appion.googlecode.com/files/pyappion-0.5.3-r3665.tgz 
161 2 Amber Herold
162 21 Amber Herold
h4. [[Start_with_existing_CentOS_installation#5-Compile-and-setup-Appion-python-programs|Compile and Setup Instructions]] 
163 1 Amber Herold
164 2 Amber Herold
h3. Install external packages 
165 17 Amber Herold
166 1 Amber Herold
Follow instructions for the individual packages.
167 22 Amber Herold
Instruction for compiling Xmipp for OpenMPI is [[Start_with_existing_CentOS_installation#8-Install-external-packages|here]].
168 1 Amber Herold
169 22 Amber Herold
h2. 6 Initialize Leginon with its admin tools 
170 2 Amber Herold
171
h3. DO NOT follow Leginon administration tool instructions.  We only need to upload images for appion processing, which is much simpler.
172
173
# Go to the webpage `http://your_host/dbem_1_5_1/addinstrument.php`
174
# Create a fake TEM instrument like this:
175
176
<pre>
177 1 Amber Herold
name: my_scope
178
hostname: whatever
179
type: Choose TEM
180 2 Amber Herold
</pre>
181
182
# Create a fake CCDCamera instrument like this:
183
184
<pre>
185 1 Amber Herold
name: my_scope
186
hostname: whatever
187
type: Choose CCDCamera
188
</pre>
189 2 Amber Herold
190 22 Amber Herold
*[Note]* If you use Leginon, and still want to upload non-Leginon images, make sure that you create a pair of fake instruments like these on a host solely for uploading.  It will be a disaster if you don't, as the pixelsize of the real instrument pair will be overwritten by your upload.
191 1 Amber Herold
192 17 Amber Herold
h2. 7 Start your first Appion session from the web 
193 2 Amber Herold
194
h3. Upload Images to a new session 
195 4 Amber Herold
196 11 Amber Herold
# Go to webpage `http://your_host/dbem_1_5_1/`  This is the general starting point for Leginon.
197
# Follow the link for the Project DB (bottom right)
198
# Select your test project, click on the name.  This takes you to the same page you created for the processing database.
199
# Below the experiment heading you will find a link that says "upload images to new session".  This takes you to your first Appion processing page, where you can use the web gui and instruction to upload your images.
200
# Once all fields are filled in click on "Just Show Command", which will bring you to a page that displays a command line.  Copy, paste, and execute this command into your text terminal, which will use the processing server programs and the database behind it.
201 22 Amber Herold
*[Note]* All images uploaded in an experiment session should have the same pixel size because they cannot easily be divided into groups during processing.
202 1 Amber Herold
203
h3. Good starting point for future reference 
204 4 Amber Herold
205 11 Amber Herold
* If you have been successful so far, the image you uploaded will show up in the viewers.  You may choose one of
206 22 Amber Herold
the viewers provided by dbem_1_5_1 as your starting point to select your session, to view the images, and to start processing by following the link at the top-left corner called "processing".
207 1 Amber Herold
208 24 Amber Herold
h2. 8 Remote Appion Processing through ssh
209 4 Amber Herold
 
210 1 Amber Herold
A more advanced way to run appion script is done through an ssh session.  This is equivalent of having you ssh into a computer and starting the appion processes.
211
212
There are two kinds of appion processes.  The first is a single-node process that can be run on a stand-alone workstation or the head-node of a computer cluster without PBS.  The second is a multiple-node process that requires PBS to run on the cluster.  When you use "Just Show Command" option, it is always a single-node process, but if you run through ssh it could be either, depending on the demand of the process.  For example,
213
imageuploader.py is always run as single-node process while maxlikeAlignment.py is either run on single-node with "Just Show Command" or as a PBS job submission when you run through ssh.
214
215 2 Amber Herold
h3. Install and setup ssh2 extension for php at your web-server 
216
217 1 Amber Herold
This enables an ssh session initialized from appionweb
218 11 Amber Herold
# Download and install the ssh2 extension for php as instructed at its download site:
219
* http://www.php.net/manual/en/ssh2.installation.php
220 1 Amber Herold
    Install openssl and compile libssh first before compiling php-ssh2 extension. Once you get the final ssh2.so, add it in your php.ini
221
222
The extension module is added to php in the same way as does the php-mrc module we distribute for the viewing mrc images through php.  To check whether it worked and for alternative way to make php recognize the module used in newer php, see http://emg.nysbc.org/documentation/leginon/bk02ch04s07.php under the section *Check php information* and *Alternative approach if mrc module does not show up in info.php output*
223
224 2 Amber Herold
h3. configuration at web server side 
225
226 25 Amber Herold
*IMPORTANT*: What we refer here as _your_cluster.php_ should not be taken literally.  For example, if you access your cluster through network with a name "bestclusterever", you should name your cluster configuration php file *bestclusterever.php*, not _your_cluster.php_.
227 23 Amber Herold
# Go to your_dbem_1_5_1/processing directory
228 25 Amber Herold
# Copy *default_cluster.php* to _your_cluster.php_
229 23 Amber Herold
# [[ClusterPhpSettings|Edit your_cluster.php]] to correspond to your cluster configuration.
230 25 Amber Herold
# Edit *config_processing.php* to add your cluster and, if desired, a stand-alone workstation as processing_host and register the _your_cluster.php_ you just created.
231 2 Amber Herold
232
<pre>
233 1 Amber Herold
$PROCESSING_HOSTS[]="your_stand-alone_processing_workstation";
234 23 Amber Herold
$PROCESSING_HOSTS[]="your_cluster";
235 1 Amber Herold
$CLUSTER_CONFIGS= array (
236 23 Amber Herold
  'your_cluster'
237 1 Amber Herold
);
238 2 Amber Herold
</pre>
239
240
241
h3. Setting up PBS on processing server side 
242
243 22 Amber Herold
Follow these [[Start_with_existing_CentOS_installation#9-Install-a-PBS-job-submission-system|instructions to set up PBS on your processing server]].
244 1 Amber Herold
245 2 Amber Herold
h3. Testing 
246
247
h4. Testing php-ssh2 installation
248
249 1 Amber Herold
Check your info.php as you did with mrctool installation.  Corrected installed extension should show up in the output of info.php.  Reference http://emg.nysbc.org/documentation/leginon/bk02ch04s07.php under the section *Check php information* and *Alternative approach if mrc module does not show up in info.php output*.
250 2 Amber Herold
251
h4. Testing ssh log in 
252
253 1 Amber Herold
Use the top right form on the processing page to log in as if doing an ssh session. The page will acknowledge that you have been logged in if the setup is correct.  You will be able to edit description of a run and to hide failed runs when logged in. The option for submitting the job appears at the bottom of the processing form whenever available.
254 2 Amber Herold
255
h4. Testing simple appion processing job submission 
256
257 1 Amber Herold
Upload template is a good example to try:
258 11 Amber Herold
# Create a small mrc image as your template to be uploaded.
259
# Select Upload template in Import tools in the appionweb processing menu of an existing session.
260
# Type in the needed information.
261
# When you finish filling the form, instead of clicking on "Just show command", choose your processing host and run the job by clicking "Upload Template".
262
# For simple process such as this, the webpage will take a little while to refresh until the job is completed.
263
# If you get the message "Template is uploaded", the process is successful and if you refresh the page you will find the template in the available list. 
264 2 Amber Herold
265
h4. Testing PBS-required appion processing job submission 
266
267 1 Amber Herold
Particle selection such as DogPicker is a good example to try:
268 11 Amber Herold
# Click on DoG Picking under Particle Selection menu
269
# Enter the required parameters
270
# When you finish filling a form for an appion processing, choose your processing host and run the job.  Pages for monitoring the job become available after the job is queued and subsequently begins running. If the status appears as "Running or Queued" at first, the setup is likely correct.
271
# After a while, the process will be completed and the status becomes "Done" when you click to have the Status updated on the page.
272 2 Amber Herold
273 25 Amber Herold
h4. Check _your_cluster.php_ setup 
274 2 Amber Herold
275 25 Amber Herold
For reconstructions involving iterations of different parameters such as EMAN reconstruction by refinement, the _your_cluster.php_ is used to generate the script.  Examine the script created on the web form and modify _your_cluster.php_  You can copy the script to your cluster and test run/modify it until it is correct.