OpenClinica User Manual/InstallationCheckList

Checklist for installation problems

introduction

If you followed the installation-instructions and the results are not as expected, this could have a number of reasons. A large number. Before you post a mail to the OpenClinica-mailinglist, saying "my installation did not work: why not?" it is good to check the list of points below. It helps a lot if you can narrow down the problem, for example to "the creation of the Postgres-db was not succesfull".

check that you have the correct version of OpenClinica

The Download OpenClinica page offers several different versions of OpenClinica. If you are just starting off, you will most likely want the latest stable version that looks like OpenClinica-n.n.n (the regular OpenClinica release), rather than OpenClinica-ws-n.n.n (the web services release) or OpenClinica-ws-caBIG-n.n.n (web services with caBIG).

check the versions of the software you are running

Compare the versions of the software you are running to the requirements listed in the requirements section of the Download OpenClinica page. Sometimes the latest versions of software (Tomcat or Postgres) are not compatible with the latest version of OpenClinica (e.g. OpenClinica 3.1.4.x isn't compatible with Tomcat 7+ or Postgres 9.0+).

non-obvious effects of using non-supported versions

Even though your installation appears to be running OK, there can be some bugs that are related to using a non-supported version that aren't apparent until after you've built your first study.

For example with OpenClinica 3.1.4 and 3.1.3.1 (and presumably earlier versions), using Tomcat 6.0.36 instead of the recommended 6.0.32 results the display of an inactive 'Begin New Thread' link in the discrepancy notes pop-up window, both on Linux and Windows systems (see this mail list thread). This bug prevents more than one discrepancy note being (easily) added to each item in the study, and therefore prevents more than one edit being saved for an item on a CRF that was marked complete, where 'Forced Reason for Change During Administrative Data Entry' is active for the study.

check Tomcat is running OK

To check this, open a web browser, such as Firefox or Internet Explorer. Type the address of the server you installed Tomcat on, followed by the portnumber you specified. If you took all defaults this is port 8080. You can use ip-address or the name, so http://www.myserver.org:8080 or http://[ip-address]:8080.

If you installed Tomcat on your local machine, use http://localhost:8080

You should now see a page of the Apache Software Foundation saying "If you're seeing this page via a web browser, it means you've setup Tomcat successfully. Congratulations!"

If you don't see such a page, check your Tomcat log files, you may see an error about Tomcat not being able to allocate memory. You can either reduce the amount Tomcat is trying to allocate (e.g. reduce the Maximum memory pool value on Windows), or increase the amount available.

check Tomcat recognizes OpenClinica

To check if Tomcat recognizes OpenClinica correctly, you can use the Tomcat manager-page. But before you can access this page, you must add a user with the tomcat-manager-role to the file tomcat-users.xml This file is located under the Tomcat-directory structure in conf/tomcat-users.xml Add two lines to it:
<role rolename="manager"/>
<user username="tomcat" password="s3cret" roles="manager"/>

Shutdown and startup Tomcat. Go to the default page, described above, http://www.myserver.org:8080 or localhost:8080 If you are on the first page of Tomcat, click on the link in the lefthand corner labeled "Tomcat Manager". In the page that opens, you see a list of all applications. In this list you should see an entry for "OpenClinica 3.0"

check OpenClinica is running

In the Tomcat Web Application Manager, described above, go to the line with "OpenClinica" and check the third column "Running": this should be "true". If it is "false", click "Start" in the fourth column. If this is the first time for OpenClinica to run, give it time! Tomcat has to go through the archive file, the war, and deploy it. On a slow machine this can take 10 minutes or more. If the status of OpenClinica is True/Running, then click on the link if the left column to get the OpenClinica login-screen.

check Postgres is running

For Linux type "ps -u postgres" and if there is output, you're OK. For Windows, goto Configuration-System-Services and look for PostgreSQL and then check the status.

check user clinica and database openclinica exist in Postgres

Open psql. Type "\du". You get a listing of all users and (super)user "clinica" should be on it. Next type "\l" This will give a list of all databases and one of them should be "openclinica", owner "clinica", encoding "UTF8"

check your datainfo.properties

This is the obvious one: check every line you changed and/or commented out! Especially the username and password of the postgres-user. Starting from OpenClinica 3.4 there's a strange, but expected behaviour: at first the file datainfo.properties is created in /usr/local/tomcat/webapps/OpenClinica/WEB-INF/classes. But then after restarting the application, the file is moved to /usr/local/tomcat/openclinica.config Make sure that you edit the right datainfo.properties

Writing a mail to the OpenClinica community

After you've gone through the above list and you know better what to ask, sum up the specifications of your system and the versions of:

1. Operating System
2. Tomcat
3. Postgres/Oracle
4. OpenClinica
5. everything else you think is important

Then shutdown Tomcat. Go to your log file directory and delete all files. Now startup Tomcat, wait until the error happens again. Shutdown Tomcat. Zip all the log files. As a last step: add datainfo.properties (webapps\OpenClinica\WEB-INF\classes) to the zip-file. You may need to remove any senstivie information from this file, such as database username and password.

Now you are ready to write a mail to the mailing list, with your installation-problem, your specifications, the things you checked and the zip with the log files.