Instructions on how to install JAQPOT3 as a standalone web application. The standalone installation is usually preferred over the use of the deployed instance of the services at opentox.ntua.gr:8080 either when one needs extra security (having the whole OpenTox network running on a local network or even on a single machine that is disconnected from the Internet) or for testing, debugging and development.
Here we provide an easy-to-follow guide on how to install and run JAQPOT3 locally. Briefly, what one needs to have installed is a MySQL server and a Java Virtual Machine. Maven2 proves to be very useful in order to compile, build and run JAQPOT3. Additionally the installation of a git client facilitates the download of the source code of JAQPOT3.
The installation guide that follows refers to Unix-based systems. In particular this tutorial has been tested on Debian, Ubuntu and Mac OS X operating systems. Jaqpot3 can also run on Windows but it has not been tested yet.
Before installing JAQPOT3 you need to install and set up the following :
Installation of MySQL5 server and client on Ubuntu is done using the repositories; we only need to install the packages mysql-server and mysql-client. Using aptitude, this is done with the command:
$ sudo apt-get install mysql-server mysql-client
Start the database server using:
$ sudo /etc/init.d/mysql stop $ sudo /etc/init.d/mysql start
And check that the server is indeed running using:
$ sudo netstat -tapn | grep mysql
You should be able to see something like the following:
tcp 0 0 127.0.0.1:3306 0.0.0.0:* LISTEN 1630/mysqld
Notice here that the SQL server is up and accepts connections on port 3306. Once you have installed mysql, you need to add a root account and an account that will be used by JAQPOT3 to connect to the database. The root account is created using the command:
$ sudo mysqladmin -u root -h localhost password 'mypassword'
You can now use the root account to connect to the mysql database server. Type:
$ mysql -u root -p
and you will be prompted to enter the root password. You should then be able to see the mysql console. Create a privileged user using the command (assume that the username is jaqpot and the password is s3cret):
CREATE USER 'jaqpot'@'localhost' IDENTIFIED BY 's3cret';
GRANT ALL PRIVILEGES ON *.* TO 'jaqpot'@'localhost' WITH GRANT OPTION;
You can now logout and login again using the above mentioned credentials. You should now create the database that will be used by JAQPOT3. Run the following:
$ wget https://github.com/alphaville/ToxOtis/raw/master/ToxOtis-db/src/main/resources/databaseCreation.sql --no-check-certificate $ mysql -u username -p < databaseCreation.sql
This will create a new database named 'toxotisdb' which will be used by JAQPOT3 to save tasks, models and other information.
Finally you should consider configuring/optimizing your MySQL server. The configuration file is usually located at
/etc/mysql/my.cnf. In my opinion, this is an interesting discussion on MySQL configuration.
As a second step you will need to install Maven. For that use the command:
$ sudo apt-get install maven2
You now need to configure your installation and define some Jaqpot3-specific parameters. In particular you need to modify the file settings.xml which is located in the folder ~/.m2/. In case it does not exist you need to create it:
$ touch ~/.m2/settings.xml
This file contains global system-wide settings that will be used by maven. In this you should create a profile and include the following properties:
An example file is the following:
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd"> <profiles> <profile> <id>JaqpotDb</id> <activation> <activeByDefault>true</activeByDefault> </activation> <!-- ***** DATABASE ***** --> <properties> <!--Domain name of the service Default value: localhost--> <jaqpot_domain>localhost</jaqpot_domain> <!--Database name Default value: toxotisdb--> <jaqpot.database.name>toxotisdb</jaqpot.database.name> <!--MySQL server port Default value: 3306--> <jaqpot.database.mysqlport>3306</jaqpot.database.mysqlport> <!--Database user Which user is used to access the database Default value: root--> <jaqpot.database.user>root</jaqpot.database.user> <!--Password for accessing your MySQL database server Default value: opensess@me [CHANGE IT!!!]--> <jaqpot.database.password>opensess@me</jaqpot.database.password> <google-analytics>UA-XXXXXX-X</google-analytics> <jaqpot.doAuthentication>true</jaqpot.doAuthentication> </properties> </profile> </profiles> </settings>
You now only need to download sun-java6-jdk and git. Simply run:
$ sudo apt-get install sun-java6-jdk git-core
Export the JAVA_HOME variable properly. For example:
$ export JAVA_HOME=/usr/lib/jvm/java-6-sun-18.104.22.168/;
You are now ready to proceed with the installation of JAQPOT3.
We will first use git to download the source code of Jaqpot3 from https://github.com/alphaville/jaqpot3. The source code of Jaqpot3 will be downloaded (the latest version) from the online CVS. This will create a new folder named 'jaqpot3'. We'll show write away how to compile it and run the web application on your computer. In order to download the latest version, run:
$ git clone git://github.com/alphaville/jaqpot3.git
This will create a folder 'jaqpot3' and download the source code and the pom.xml file where all Maven dependencies are defined. The following commands will compile Jaqpot3 and will start it using in Tomcat:
#!/bin/bash cd jaqpot3/jaqpot3-standalone/; mvn clean install; cd ../jaqpot3-servlet/ ; rm -r ./src/main/webapp/WEB-INF/classes/ ; mvn clean tomcat:run ;
The first time you run this it will take some time because your local Maven repository needs to be updated but after that it will be much faster. If everything is as expected you should be able to have Jaqpot running on port 8080 (check out http://localhost:8080 ).
The script we are using to start the server is a bit more elaborate as it includes some configuration of the JVM. We publish it here to for the users that want to do some JVM optimization and for completeness as well.
#!/bin/bash export export MAVEN_OPTS=... # YOUR JVM options here export JAVA_HOME=/usr/lib/jvm/java-6-sun-22.214.171.124/; cd jaqpot3/jaqpot3-standalone/; mvn -DskipTests=true clean install ; cd ../ ; cd jaqpot3-servlet/ ; rm -r ./src/main/webapp/WEB-INF/classes/ ; mvn clean tomcat:run ;
The script we are using for opentox.ntua.gr:8080 can be downloaded from here. These are the JVM options we use:
-Xmx2048m -Xms2048m -Xmn788m -Xss256k -XX:+UseLargePages -XX:LargePageSizeInBytes=1m -XX:ParallelGCThreads=4 -XX:+UseConcMarkSweepGC -XX:+UseParNewGC -XX:SurvivorRatio=8 -XX:TargetSurvivorRatio=90 -XX:MaxTenuringThreshold=15 -XX:+UseBiasedLocking -XX:+AggressiveOpts -XX:CompileThreshold=1500 -XX:+UseFastAccessorMethods -XX:MaxPermSize=128m -Xverify:none -Djava.net.preferIPv6Addresses=false -Djava.net.preferIPv4Stack=true
You will now need to create policies for certain resources. Open a web browser and navigate to http://your-server-name:8080/login and login using your account credentials (e.g. username guest and password guest). Then go to http://your-server-name:8080/iface/policy and create a policy that determines which individuals and/or groups have the right to access the resource http://your-server-name:8080/shutdown which is used to shut down the server for maintenance. An example policy can be found here
For your brand new server you should take into account that you should do the following in order to minimize the downtime and avoid data loss:
This is the script you can use to back up your database:
export now=`date +%Y-%h-%d@%H:%M:%S`; mysqldump --user=your_username --password=your_password --databases toxotisdb > temp.sql; zip BACKUP_$now.zip temp.sql; rm temp.sql; mv BACKUP_$now.zip ./sql-backups
Copy the generated file to an external storage device, mail it to your self or copy it to some other machine over SSH.
In order to upgrade your running instance of jaqpot3 to the latest version you need to create first of all a script that stops the current instance. This is as simple as:
bash ./stop.sh; cd jaqpot3/; git pull origin master; cd ..; bash ./run.sh;