-
Notifications
You must be signed in to change notification settings - Fork 5
/
INSTALLATION
200 lines (139 loc) · 8.64 KB
/
INSTALLATION
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
System Requirements
-------------------
The current version of multi-Genome Synteny Viewer was only tested on Ubuntu 10.04 OS. The minimum requirements include:
- Apache 1.3 or higher (http://www.apache.org)
- PHP 5.3.3 or higher (http://www.php.net/)
- MySQL 5.0 or higher (http://dev.mysql.com/)
- GD library. (http://php.net/manual/en/book.image.php)
Section I: Install Prerequisites
--------------------------------
On our Ubuntu OS, Apache, PHP, GD library, and MySQL were installed using apt-get. The commands are listed below. You can also use yum, rpm, dpkg, etc., depending on the operating system- speak to your systems administrator about it.
shell> sudo apt-get install apache2
shell> sudo apt-get install php5
shell> sudo apt-get install libapache2-mod-php5
shell> sudo apt-get install mysql-server
shell> sudo apt-get install php5-mysql
Section II: MySQL Database Setup
--------------------------------
mGSV requires a MySQL database to store data. Listed below are steps to create a user, database, and one table within the database.
1. Log into MySQL, replace <password> with root password
shell> mysql -u root -p <password>
2. Create 'mgsv' database
mysql> CREATE DATABASE mgsv;
3. Create a user 'mgsv_user'
mysql> CREATE USER 'mgsv_user'@'localhost' IDENTIFIED BY 'mgsvpass';
4. Set privileges to 'mgsv_user' to use database
mysql> GRANT SELECT, INSERT, CREATE, DROP ON mgsv.* TO 'mgsvuser'@'localhost';
5. Create table "userinfo" in 'mgsv' database by executing the following MySQL command
mysql> use mgsv;
mysql> CREATE TABLE IF NOT EXISTS `userinfo` (
`id` int(10) NOT NULL AUTO_INCREMENT,
`email` text NOT NULL,
`hash` text NOT NULL,
`synfilename` text NOT NULL,
`annfilename` text NOT NULL,
`url` text NOT NULL,
`session_id` text NOT NULL,
`annImage` int(5) NOT NULL,
`create_on` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
PRIMARY KEY (`id`)
) ENGINE=MyISAM DEFAULT CHARSET=latin1 AUTO_INCREMENT=3 ;
If you use different database settings, please refer to the MySQL document for instructions on how to configure the database.
Section III: Set up the multi-Genome Synteny Viewer
---------------------------------------------------
1. Download the source code from the mGSV website http://cas-bioinfo.cas.unt.edu/mgsv/software.php
2. Unzip the file mgsv.v2.1.tar.gz. This should create a folder called 'mgsv'.
shell> tar zxvf mgsv.v2.1.tar.gz
3. Move the folder 'mgsv' to DocumentRoot of Apache web server. By default, the DocumentRoot of Apache is /var/www/ (speak to the system administrator to know the exact DocumentRoot).
shell> mv mgsv /var/www/.
4. Enter 'mgsv' directory and you should see another directory called 'syn'. Execute Linux commands to create and change permission for 'tmp' folder. It has to be world accessible to store the uploaded files.
shell> cd /var/www/mgsv
shell> mkdir tmp
shell> chmod -R 777 tmp
5. If you have set up the MySQL database name, user and password as mentioned in STEP II, you can skip this step. However, if your MySQL setting is different, you must open the file 'settings.php' in 'mgsv/lib/' directory with any text editor you are comfortable with (e.g., pico, emacs, or vi), and modify lines 4, 5, 6, and 7 to change the variables $database_name, $database_user, $database_pass, and $database_host.
6. Under 'mgsv' folder you should see a file called 'Arial.tff'. Copy it to '/usr/share/fonts/truetype/.'. You may need the sudo privilege- talk to your system administrator if necessary.
shell> cp Arial.ttf /usr/share/fonts/truetype/.
7. Cleanup scripts are provided to drop database synteny and annotation tables, remove entries from database table 'userinfo' and delete the folder containing image files which are older than 60 days. This task is accomplished by cron job to run the cleanup script every day. To create a cron job, use the command below:
shell> crontab -e
At the last line of crontab, copy and paste the line below, and provide the exact path to mgsv/lib/cleanup.php
30 04 * * * /var/www/mgsv/lib/cleanup.php
The script cleanup.php will be executed at 4:30 AM every morning.
8. mGSV uses the mail function from PHP to send email to users. Speak to your system administrator to provide required information in the PHP configuration file called 'php.ini'.
9. When installation completes, you can now open Install/index.php (i.e., http://<YOUR_SERVER_DOMAIN_NAME>/mgsv/Install/), which verifies prerequisites, database setup, and installation. YOUR_SERVER_DOMAIN_NAME refers to the domain name of your server.
Section IV: Web Service (optional)
----------------------------------
1. Web service is an optional component of mGSV.
The goal of this part of the installation are to:
- Install Web Service using source or binary files that comes with mGSV distribution.
- Run or Stop Web Service as a background job
- Verify following artefacts are available for client or software developers to use the Web Service
a. WSDL File (XML Based Specification for web Service)
- Needed for developers to create helper classes and know the method signature for web service.
- After successful installation and running this file is available at:
http://<YOUR_SERVER_DOMAIN_NAME>:8081/MGSVService?wsdl
b. An url where client can connect to consume the web service
- Needed for developers to connect and use the web service.
- Needed for client application user to connect and upload synteny data
- Available at
http://<YOUR_SERVER_DOMAIN_NAME>:8081/MGSVService
c. A reference documentation that explains the services
- Software developement reference guide for client developers.
- Explains the service in detail
- available at:
http://<YOUR_SERVER_DOMAIN_NAME>/ws/client-reference.txt
All three urls in (a,b,c) can be verified by visiting them using browser.
a. XML File
b. Small note or a blank screen
d. Documentation file
2. Installation from binary.
2.A. Required (Java 1.6 or higher)
- To check whether you have the required JDK installed execute following command
shell> java -version
If "No command 'java' found ... ", java is not installed or not configured properly. To install java
shell> apt-get install openjdk-6-jdk
If java version is less than 1.6, upgrade java using
shell> apt-get install openjdk-6-jdk
2.B. Edit configuration file to specify your mGSV server
- Configuration file has the format of key:value and is present in the same directory as ws-server-1.0RC1-jar-with-dependencies.jar
shell> cd /var/www/mgsv/ws
shell> echo "mgsv_upload_url=http://<YOUR_SERVER_DOMAIN_NAME>/mgsv" > config.properties
shell> echo "ws_publish_url=http\://<YOUR_SERVER_DOMAIN_NAME>\:8081/MGSVService" >> config.properties
2.C. Run Web Service
shell> cd /var/www/mgsv/ws
shell> java -jar ws-server-1.0RC1-jar-with-dependencies.jar &
2.D. To stop the web service
shell> ps aux | grep ws-server-1.0RC1-jar-with-dependencies.jar
*Note the process id from the output*
shell> kill -9 <process id>
3. Installation from source.
3.A. Required.
- Java 1.6 or higher
- Maven 3.0 or higher
shell> mvn --version
If "No command 'mvn' found ... ", Maven is not installed or not configure properly. To install Maven
shell> cd /tmp
shell> wget http://apache.mirrors.hoobly.com/maven/binaries/apache-maven-3.0.4-bin.tar.gz
shell> tar zxvf apache-maven-3.0.4-bin.tar.gz
3.B. Decompress server source
shell> cd /var/www/mgsv/ws
shell> tar -xzf ws-server-src.tar.gz
Note: Structure of the source folder (/var/www/mgsv/ws-server)
src/ : Source folder
config.properties : Configuration file
pom.xml : Maven Build Configuration file
Note: src/edu/unt/mgsv/MGSVService.java is the main java file that contains the Web Service
implementation. Code is extensively documented to incoperate changes. The Archetecture guide
has further information about inner working of this file.
3.C. Compile source using Maven.
shell> cd /var/www/mgsv/ws-server
shell> /tmp/apache-maven-3.0.4/bin/mvn package
* This command downloads required dependencies and creates a executable
binary, a java jar file, (ws-server-1.0RC1-jar-with-dependencies.jar) under folder 'target'. This
file is stand alone binary and contains all the necessary libraries. Only requirement to run this
binary would be a JDK 1.6+
3.D. Copy binary file and continue from Section IV.2.A.
shell> cp -f /var/www/mgsv/ws/mgsv-ws-server/target/ws-server-1.0RC1-jar-with-dependencies.jar /var/www/mgsv/ws/.
Section V: Additional notes
---------------------------
1. For troubleshooting, please use the contact details at http://cas-bioinfo.cas.unt.edu/mgsv/contact.php
2. Refer to the ARCHITECTURE.txt file to understand the architecture of mGSV.