1. Components of PinDown Automatic Debugger

The PinDown automatic debugger has two components. A web interface and the actual automatic debugger executable. The web interface is powered by WaveMaker, which is based on Java servlet technology. Its runtime is provided by the Apache Tomcat servlet container. The debugger itself is also Java based. The persistence layer is PostgreSQL. That means you need Java, Tomcat, PostgreSQL and the Verifyter provided PinDownPackage.tar for a successful install.

Here are the tool version we currently support:

Tested Versions:

OpenJDK 6, 8

Oracle Java 6

Tomcat 7, 9

PostgreSQL 8.4, 9.0, 9.1, 9.2, 9.3, 9.5

2. Installing PostgreSQL DB

The PostgreSQL database is best installed systemwide. A systemwide install requires root access.

2.1. Red Hat

Here are the steps for this procedure on Red Hat 6 or 7. Call the Red Hat package manager to install PostgreSQL:

$ sudo yum install postgresql-server

This will install version 8.4 of PostgreSQL for Red Hat 6, or 9.2 for Red Hat 7. Next initialize PostgreSQL and enable autostart:

$ sudo service postgresql initdb
$ sudo chkconfig postgresql on

This will produce the data directory in /var/lib/pgsql/. Look for the files shown below and change the respective lines in each file like so:

If everything will be run on the same virtual machine listen_addresses can be 'localhost', otherwise it should be '*'.

For pg_hba_conf only add the second group of lines if access from the rest of the network is needed.

postgresql.conf:

listen_addresses = '*'

pg_hba.conf:

#IPV4 local connections
host  all  all  127.0.0.1/32  md5
#IPV4 network connections
host  all  all  0.0.0.0/0  md5

Next, start the DB:

$ sudo service postgresql start

And create a database called pindown:

$ sudo -u postgres createdb pindown

As user postgres add password:

$ psql pindown postgres
pindown=# ALTER USER postgres WITH PASSWORD 'myPassword';

And restart the DB.

2.2. Ubuntu

Here are the steps for this procedure on Ubuntu 14.04 LTS.

Call the Ubuntu package manager to install PostgreSQL:

$ sudo apt-get install postgresql

This will install version 9.3 of PostgreSQL and start it too. As user postgres, configure the DB. In directory /etc/postgresql/9.3/main look for the files shown below and change the respective lines in each file like so:

If everything will be run on the same virtual machine listen_addresses can be 'localhost', otherwise it should be '*'.

For pg_hba_conf only add the second group of lines if access from the rest of the network is needed.

postgresql.conf:

listen_addresses = '*'

pg_hba.conf:

#IPV4 local connections
host  all  all  127.0.0.1/32  md5
#IPV4 network connections
host  all  all  0.0.0.0/0  md5

Then create a database called pindown:

$ sudo -u postgres createdb pindown

And restart the DB to read the new settings:

$ sudo service postgresql restart

As user postgres add password:

$ psql pindown postgres
pindown=# ALTER USER postgres WITH PASSWORD 'myPassword';

And restart the DB.

Other commands available with service are stop/start/status, e.g. you should see this when checking status now:

$ sudo service postgresql status
9.3/main (port 5432): online

3. Installing Java

Tomcat 7 requires Java 6+. Either OpenJDK 6+ or Oracle Java 6+. Java is installed systemwide, requiring root access.

3.1. RedHat

On RedHat 6, you can install OpenJDK 6 using the package manager. You can refer to online instructions from RedHat for more details. In a nutshell:

$ sudo yum install java-1.6.0-openjdk-devel

Point environment variable $JAVA_HOME to the installation directory. Determine the correct value for JAVA_HOME. Red Hat Enterprise Linux installs OpenJDK 1.6 into either /usr/lib/jvm/java-1.6.0-openjdk-1.6.0.0/ or /usr/lib/jvm/java-1.6.0-openjdk-1.6.0.0.x86_64/, depending on whether your system is a 32-bit or 64-bit architecture. The JAVA_HOME should point to the directory containing a bin/java executable.

$ export JAVA_HOME="/usr/lib/jvm/java-1.6.0-openjdk-1.6.0.0.x86_64"

3.2. Ubuntu

On Ubuntu 14.04, you can install OpenJDK 6 using the package manager:

$ sudo apt-get install openjdk-6-jdk
$ sudo update-alternatives --config java

Point environment variable $JAVA_HOME to the installation directory:

$ export JAVA_HOME="/usr/lib/jvm/java-6-openjdk-amd64"

4. Installing Apache Tomcat

4.1. Local Project Directory

Tomcat is best installed in the local project area. No root access required. Local install is quick and offers more flexibility.

The local project directory is any directory where you want to install Tomcat and PinDown. This is typically a project area with sufficient disk space. The local folder will contain all binaries and the actual PinDown projects. This folder will be referred to as $PINDOWN_FOLDER from now on.

Note If you want to keep temporary files separate from Tomcat and PinDown project configuration files, you can do so by mapping the checkout areas to any other desired area. This can later be configured on a project by project basis by the project owner.

4.2. Tomcat

The Tomcat servlet container can be installed from the binary distribution by any user. No root access required. Download Tomcat 7.0 from http://tomcat.apache.org. Go to Download Tomcat 7.0 on the left menu. Download the latest binary distribution in tar.gz format, e.g. at time of writing this was 7.0.68. Place the downloaded file apache-tomcat-7.0.68.tar.gz in the PinDown folder.

Decompress and untar the file:

$ cd $PINDOWN_FOLDER
$ gunzip apache-tomcat-7.0.68.tar.gz
$ tar xvf apache-tomcat-7.0.68.tar

This will create local directory apache-tomcat-7.0.68 containing a usable installation. To make this path shorter, move it:

$ mv apache-tomcat-7.0.68 tomcat

Your Tomcat installation is now in $PINDOWN_FOLDER/tomcat.

5. Installing PinDown

In this final step the PinDown debugger and PinDown servlet (called TestHub) are deployed with Tomcat. You will need a set of PinDown specific files, provided by Verifyter in the tar file PinDownPackage.tar:

PinDown Installation Files:
PinDownPackage.tar: pindown (edit)
PinDownPackage.tar: pindown.jar
PinDownPackage.tar: launchPinDown.sh
PinDownPackage.tar: curlProjectStart.sh
PinDownPackage.tar: tomcat/.pindown/pindown.properties (edit)
PinDownPackage.tar: tomcat/.pindown/launchPinDownTesthub.sh (edit)
PinDownPackage.tar: tomcat/webapps/PinDown.war
PinDownPackage.tar: lib/
Note Contact Verifyter support at support@verifyter.com if you don’t have this file.

Place PinDownPackage.tar in $PINDOWN_FOLDER and extract its contents:

$ cd $PINDOWN_FOLDER
$ tar xvf PinDownPackage.tar

This package contains two sets of files. One set is specific to TestHub, the other set is specific to the debugger.

5.1. Installing PinDown TestHub

Extraction has created these files for you:

tomcat/.pindown/pindown.properties
tomcat/.pindown/launchPinDownTesthub.sh

Both of these files need editing to reflect your local setup for PostgreSQL, TestHub and email. Below listing shows an example setup for these two files:

pindown.properties:

location = localhost
database = pindown
username = postgres
password = myPassword
pindownFolder = /home/chrisg/work/Demos/pilot_pd
testHubUrl = http\://localhost\:8080/PinDown
mail.server = localhost
mail.author = chrisg
mail.port = 25
Note Escape any colons in pindown.properties.

launchPinDownTesthub.sh:

#!/bin/sh
unset DISPLAY
TOMCAT_BIN="/home/chrisg/work/Demos/pilot_pd/tomcat/bin"
TESTHUB_URL="http://localhost:8080/PinDown"
...
Note TestHub does require a dedicated machine as host. Here the setup is done for localhost.
Note You need to replace the absolute path /home/chrisg/work/Demos/pilot_pd in the example with your absolute path to your $PINDOWN_FOLDER.

5.2. Installing PinDown Debugger

The PinDown debugger files are actually already all in place if PinDownPackages.tar was extracted as described above. In your PinDown folder $PINDOWN_FOLDER you should see these files and directories:

pindown
pindown.jar
curlProjectStart.sh
launchPinDown.sh
lib (directory)

Open pindown and edit the absolute paths. You need to replace the absolute path /home/chrisg/work/Demos/pilot_pd in the example with your absolute path to your $PINDOWN_FOLDER.

pindown:

#!/bin/sh
# To install, set these two paths to where you place the pindown.jar-link and the lib directory:
jar="/home/chrisg/work/Demos/pilot_pd"
lib="/home/chrisg/work/Demos/pilot_pd/lib"
# Running pindown using the paths above
classpath="$jar/pindown.jar:$lib/*"
arguments=$@
eval "java -classpath \"$classpath\" com.verifyter.pindown.main.MainClass $arguments"

5.3. Installing PinDown license

The default license mechanism for PinDown is flexlm. If you have a flexlm license from Verifyter you only need to point to your flexlm license server from a PinDown project. This guide does not cover setup of PinDown projects. Refer to your PinDown training for setting up and configuring PinDown projects.

As an alternative Verifyter might have provided a short term proprietary evaluation license. If you have received such license place it inside the tomcat/.pindown folder and restart PinDown TestHub (shutdown and launch again) to activate the license.

6. Launching PinDown TestHub

Launch PinDown TestHub by calling launchPinDownTesthub.sh from the .pindown directory:

$ cd tomcat/.pindown
$ launchPinDownTesthub.sh
...
Tomcat started.
PinDown TestHub is up and running.

Open PinDown TestHub on the host machine, e.g. go to http://localhost:8080/PinDown. Any error message encountered during an unsuccessful launch will also display here. To shut down Tomcat, if required, go to tomcat/bin and call shutdown.sh.

You are now ready to create a PinDown project. Refer to your PinDown training for setting up and configuring PinDown projects.

7. Appendix A: PinDown Secure Setup

For increased security, only the user running PinDown should have access to the virtual machine, and everything should be run there (see Figure 1).

Access to project specific files such as pindown_config.txt should be stored locally on the virtual machine and restricted to the user running PinDown.

To allow for user control install and setup Apache HTTPD with authentication and forward the connection to PinDown TestHub on the same machine using ProxyPass. PinDown TestHub runs as a servlet on the Apache Tomcat server.

Both Apache HTTPD and Apache Tomcat server should be setup to only allow https traffic.

PostgreSQL should be setup locally on the virtual machine and to only allow connections from localhost.

All connections except remote shell (ssh) and web traffic (Apache HTTPD) should be blocked by a firewall from other hosts.

Figure 1. PinDown Secure Setup