Standalone installation

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.


Dependencies - Before installation

Before installing JAQPOT3 you need to install and set up the following :

  1. MySQL server
  2. Java Virtual Machine
  3. Maven2
  4. Git

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):

mysql> CREATE USER 'jaqpot'@'localhost' IDENTIFIED BY 's3cret';

and

mysql> 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:

  1. Domain Name: jaqpot_domain. An assigned domain name for the running services. You can use localhost or your server's IP if no domain name is available.
  2. The database name: jaqpot.database.name. By default set to toxotisdb unless you know what you're doing.
  3. MySQL server port: jaqpot.database.mysqlport. Usually this is 3306.
  4. Database account credentials: jaqpot.database.user and jaqpot.database.password.
  5. Whether you need your services protected with A&A: jaqpot.doAuthentication (admissible values are true and false)
  6. If available, define your GA account ID: google-analytics.

An example file can be found here.

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-1.6.0.24/;

You are now ready to proceed with the installation of JAQPOT3.


Compile, Build and Run Jaqpot

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-1.6.0.24/;
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

 


Maintain & Upgrade

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:

  1. You will need to backup your server's database regularly to avoid loss of data. For that you can use the following shell script (can be also downloaded from here)
  2. Inspect the logs of your server for errors especially when you have a bug report. The logs are found under jaqpot3/jaqpot3-servlet/logging.
  3. Check out the Java Melody page of your server at http://your-server-name:8080/monitoring.

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 can be downloaded from here). This is as simple as:

bash ./stop.sh;
cd jaqpot3/;
git pull origin master;
cd ..;
bash ./run.sh;