Install OpenClinica and OC Web Services on Linux.

by Saahyl

In this blog, we are going to learn how to install Openclinica and Openclinica Web Services on a linux machine. I’m going to refer the openclinica installation page plus providing important points that one is likely to miss out during the installation.

Search for “Note:” in this document to check for the steps to remember.

1. The following packages should be installed in your Operating System:

  • vim
  • unzip
  • tar

2. Determine if your system is running a 32-bit or 64-bit operating system:

In your Linux terminal,run command: 
uname -a
The display reports the version: 

  • If i386 or i686 displays, it is a 32-bit operating system.
  • If x86_64 displays, it is a 64-bit operating system.

OpenClinica and OpenClinica Web Services run and depend on several external software technologies: the Java Development Kit, the Apache Tomcat Servlet Container, and the PostgreSQL relational database. We must install them. 

Note: “Run all commands in the installation instructions using root-level permission.”

Create an OpenClinica directory on your system and make it the current directory:

mkdir -p /usr/local/oc/install
cd /usr/local/oc/install

3. Install Java:

# For Download

Visit “https://openclinica.app.box.com/v/oc-downloads/1/“, here under the linux folder open folder that matches the version of your operating system and download the Jdk into
/usr/local/oc/install
# To Extract java run:
tar -zxvf jdk-7*
# To make java available locally and create a symlink run :

mv jdk1* /usr/local/
ln -s /usr/local/jdk1* /usr/local/java

Note: After above steps, test java installed by typing java and javac. If the “command not found” error occurs, then you need to update the alternatives by following commands:

#To update java command alternatives
update-alternatives --install "/usr/bin/java" "java" "/usr/local/java/bin/java" 1
#To update javac command alternatives
update-alternatives --install "/usr/bin/javac" "javac" "/usr/local/java/bin/javac" 1
#To udate javaws command alternatives
update-alternatives --install "/usr/bin/javaws" "javaws" "/usr/local/java/bin/javaws" 1

4. Install Apache Tomcat:

#Change to this folder:
cd /usr/local/oc/install

#Download Tomcat
Visit “https://openclinica.app.box.com/v/oc-downloads/1/”, under the folder named common you will find Tomcat.

#Install Tomcat by running the following:
tar -zxvf apache-tomcat-*
mv apache-tomcat-* /usr/local/
ln -s /usr/local/apache-tomcat-7.0.52 /usr/local/tomcat
/usr/sbin/adduser tomcat

#Update the File Path parameter to the correct value
chown -R tomcat /usr/local/tomcat/*
chown -R tomcat /usr/local/apache-*
Tomcat is installed, we will start its service later.

5. Install PostgreSQL Database:

The OpenClinica software uses PostgreSQL as an underlying relational database management system.

Note: The openclinica installation page shows installation for postgresql-8.4.*. The newer versions of Openclinica may not be compatible with postgresql-8.4.* versions. So its recommended to install 9 or above versions of postgresql database.

#Install postgresql using apt-get,
apt-get install postgresql
Enter into the database to create a role and a database for openclinica,
#To connect to the localhost psql
psql -U postgres
If you get following error
“psql: FATAL: Peer authentication failed for user postgres”
then,

#Edit the /etc/postgresql/9.1/main/pg_hba.conf (using a text editor)
Change the Database administrative login by Unix domain socket
from,

local all postgres peer

to 

local all postgres md5

#Then restart the postgresql service,
service postgresql restart
sudo -i -u postgres
psql

Enter the password that is given at the time of installation.

Note: After restart if things do not still work or you have skip the password during installation and you are not able to login to postgresql terminal,

#Edit the /etc/postgresql/9.1/main/pg_hba.conf :

Change the Database administrative login by Unix domain socket from,

local all postgres md5/peer

to

local all postgres trust

Then restart the postgresql service. Now you may connect your postgres terminal without password,
psql -U postgres

#Create role clinica with password clinica
CREATE ROLE clinica LOGIN ENCRYPTED PASSWORD 'clinica' SUPERUSER NOINHERIT NOCREATEDB NOCREATEROLE;

#Create database openclinica
CREATE DATABASE openclinica WITH ENCODING='UTF8' OWNER=clinica;

#To change the password of ‘clinica’ role
ALTER USER clinica WITH PASSWORD 'newpassword';

#Exit the psql command prompt by typing
\q

6. Deploying OpenClinica within tomcat:

#Change to this folder:
cd /usr/local/oc/install

# Download the OpenClinica software from the OpenClinica
# website: “https://www.openclinica.com/community-edition-open-source-edc/
# To download the software, you need an OpenClinica community user account, its free to create, you will be required to log in to the account to download the OpenClinica software.

#Run the following commands. In the commands, v.x is your version of OpenClinica:
unzip OpenClinica-v.x*
cd OpenClinica-v.x*/distribution
unzip OpenClinica.war -d OpenClinica
cp -rf OpenClinica* /usr/local/tomcat/webapps

7. Configure the OpenClinica Application:

There is only one property in the configuration file, datainfo.properties , that you may need to change in order for OpenClinica to start. There are other properties in the configuration file you will probably want to modify for your system.

Open the configuration file:
/usr/local/tomcat/webapps/OpenClinica/WEB-INF/classes/datainfo.properties

  1. Edit values for the properties in the datainfo.properties file. You must change the value for dbPass to the password you selected in Set Up the PostgreSQL Database. Change the values for any other properties, then save the file.

Example Database Configuration,

  • dbType=postgres
  • dbUser=clinica
  • dbPass=”newpassword”
  • db=openclinica
  • dbPort=5432
  • dbHost=localhost

2. Update the filePath parameter to the right value.

  • filePath=/usr/local/tomcat/webapps/openclinica.data/

Note : Consequent configuration changes shall also be made to file
/usr/local/tomcat/openclinica.config/datainfo.properties

8. Set Tomcat to Start:

You can set Tomcat to automatically start when you start your system, or you can start and stop Tomcat manually by issuing commands.

To set Tomcat to start automatically on system startup, run the following:
cp /usr/local/oc/install/OpenClinica-v.x*/install-docs/linux/tomcat /etc/init.d/
cd /etc/init.d
chmod a+x /etc/init.d/tomcat

/sbin/chkconfig –add tomcat (Note: This command is only for Red Hat Linux. For other operating systems, see the operating system instructions for adding an init script.)

#To stop and start Tomcat manually by issuing commands, run the following:
/usr/local/tomcat/bin/shutdown.sh (stops Tomcat)
/usr/local/tomcat/bin/startup.sh (starts Tomcat)

9. Verify Access to OpenClinica Application:

At this point, Java, Tomcat, PostgreSQL, and OpenClinica application are installed and set up.
access OpenClinica at the following URL:
http://localhost:8080/OpenClinica
The Log In page should display.

default username : root
default password : 12345678

After creating a user the password is shown under alerts&messages left panel.
To verify your set-up, try to access OpenClinica from another computer by running the same url from that computer, but replace localhost with the server’s IP or hostname.

10. Deploying OpenClinica Web Services within Tomcat:

Web Services are optional. Do not install them if you are not planning to use them.

# Download the OpenClinica-ws software from the OpenClinica
# website: https://www.openclinica.com/community-edition-open-source-edc/
# To download the software, you need an OpenClinica community user account,its free to create, you will be required to log in to the account to download the OpenClinica-ws software.
#Change to this folder:
cd /usr/local/oc/install
#Run the following commands. In the commands, v.x is your version of OpenClinica, e.g. 3.11:

unzip OpenClinica-ws-v.x*
cd OpenClinica-ws-v.x*/distribution
unzip OpenClinica-ws.war -d OpenClinica-ws
cp -rf OpenClinica* /usr/local/tomcat/webapps
OpenClinica web services are now deployed for use with the database.

11. Configure the OpenClinica Web Services:

Open the configuration file: /usr/local/tomcat/webapps/OpenClinica-ws/WEB-INF/classes/datainfo.properties

Edit the datainfo.properties file like you did for Openclinica Application but one property value would differ i.e org.quartz.threadPool.threadCount

  • Update the filePath parameter to the right value.

filePath=/usr/local/tomcat/webapps/openclinica-ws.data/

  • You may change the sysURL parameter.

sysURL=http://localhost:8080/OpenClinica-ws/MainMenu

  • Note: Change threadCount to org.quartz.threadPool.threadCount= 0

Note:threadCount should be set to 0 (zero) on web services modules. While on OpenClinica Application its value is 1.

Note : Consequent configuration changes shall also be made to the file /usr/local/tomcat/openclinica-ws.config/datainfo.properties, otherwise the web services will not start.

12. Verify Access to OpenClinica Web Services:

Access OpenClinica Web Services at the following URL:
http://localhost:8080/OpenClinica-ws

The Welcome page should display. It indicates that web services are up and ready to use. There is no login for web services.
To verify your set-up, try to access OpenClinica Web Services from another computer by running the same url from that computer, but replace localhost with the server’s IP or hostname.

13. Troubleshooting:

If you think that Openclinica services are not starting, you can check them in the Tomcat Manager app.

For Tomcat 7 and Tomcat 8 :
Tomcat users are defined in the file – /usr/local/tomcat/conf/tomcat-users.xml, by default, there is NO user, it means no one can access the Tomcat manager page.
To enable users to access the Tomcat manager page, add a user as the role manager-gui.
Edit /usr/local/tomcat/conf/tomcat-users.xml

tomcat-users.xml

Saved it and restart Tomcat, now you should able to access the default manager page (http://localhost:8080/manager) with user = “admin” and password = “admin”

You are ready to get going with Openclinica and some of the other stuff.

Keep coming back for more…

Leave a Reply

Your email address will not be published. Required fields are marked *

Tools & Practices

Tools and Technologies we use at Applied

Contact us now

Popular Posts