These installation instructions have been verified on the following Windows Operating Systems versions:

  • Windows Server 2003 Standard Edition SP2
  • Windows Server 2003 Standard Edition SP1
  • Windows XP Professional Version 2002 SP2

These instructions are for installing version 3.1 of OpenClinica, and also apply to installing the maintenance releases of 3.1 for example 3.1.2. When you see v.x or v.x.y in the instructions, use your version number, e.g. 3.1.2.

Screenshots shown in these instructions might look different than the screens on your system because your operating system might not be the same. The screenshots might not correspond exactly with the written instructions. Where the screenshot differs from the written instruction, always follow the written instruction.

All characters in the installation commands are case sensitive. Also note that any additional white space between or after characters in commands could cause installation errors.

10.13.1 Overview of Installation on Windows Systems

Use the following process to acquire, install, and configure OpenClinca and its software dependencies. In each step, click the link to view detailed instructions for that step:

  1. Ensure your system complies with software dependencies and operating system requirements.
  2. Install Java
  3. Install the database you will use, PostgreSQL or Oracle:
    • Follow these instructions to install PostgreSQL.
    • If you are using Oracle, you will need to obtain the instructions to install it. OpenClinica does not provide instructions to install Oracle.
  4. Install Tomcat.
  5. Install the OpenClinica package.
  6. Set up the database you installed:
  7. Configure Tomcat
  8. Configure the OpenClinica application.
  9. Start Tomcat.
  10. Verify the installation.
  11. Configure Tomcat to use HTTPS: Follow the same instructions as for Linux systems.

After completing the OpenClinica installation, see the Overview of OpenClinica for instructions to start using the application. A good first step is to define one or more users (especially a Study Director), and then build a Study.

10.13.2 Software Dependencies and Operating System Requirements

Windows Configuration

Your Windows operating system must be configured to show file extensions by default. To configure this behavior:

  1. Open a Windows Explorer window.
  2. Select Tools > Folder Options.
  3. Click the View tab.
  4. In Advanced settings, clear the Hide extensions for known file types checkbox.
  5. Click Apply

Software Dependencies

OpenClinica runs on any Servlet/JSP container that implements the Servlet 2.4 and JavaServer Pages 2.0 specifications from the Java Community Process. OpenClinica was developed to run on and has been tested with Apache Tomcat 6.0.32.

OpenClinica runs on either the PostgreSQL relational database or an Oracle relational database. Using a
JDBC (Java Database Connectivity) driver, the database connects to the OpenClinica web application and provides the data to the user.

New installations require the following software, which is all open source. These installation instructions step you through the process of downloading, installing, and configuring it for use with OpenClinica:

  • Java 6 Standard Edition Development Kit 6.0 update 24 (Note: Java frequently changes its naming conventions.)
  • Tomcat 6.0.32
  • PostgreSQL 8.4.7.2 or Oracle 10g

Other Versions of Dependent Software

The software dependencies OpenClinica uses are open source, and frequently updated with minor versions and revisions. Sometimes only a matter of weeks separates the release of two adjacent versions. At the time of this OpenClinica release, the latest stable version of Java, Tomcat, and PostgreSQL were used in integrated testing (and are referenced in this document). In some cases, the revision number used is no longer available. In general, you should be able to use more recent minor versions and revisions of the software dependencies. For example, if the installation instructions refer to PostgreSQL 8.4.7.2, then PostgreSQL 8.4.8 should work successfully too (but not PostgreSQL 9).

Record the version or revision number of all the software you use. If you have concerns about a particular combination, post your question to the users@openclinica.com mailing list.

10.13.3 Install Java

The OpenClinica software is written in the Java programming language, so you must have Java installed on your system in order to run the OpenClinica application. Follow these instructions to install Java:

  1. OpenClinica 3.1 is designed to run on a Java 6 SDK 1.6.x platform. To avoid conflicts with other versions of Java, clear out any other Java installations on the system. Select Start > Control Panel > Add Remove Programs, then remove any Java JREs and SDKs.
  2. Create the directory c:ocinstall.
  3. From one of the following websites, download the Java 6 SE Development Kit 6.0 update 24 (jdk-6u24-windows-i586.exe) into c:ocinstall:

  4. Run c:ocinstalljdk-6u24-windows-i586.exe.
    The Open File – Security Warning message displays.
  5. Click Run.
    The Welcome to Java Installation Wizard opens.
  6. Click Next.
    The Custom Setup screen displays.
  7. Click Change….
  8. Change the path to c:ocjdk1.6.0_24, then click OK.
    The Custom Setup screen should now look like this:

    Java Installation Wizard - Custom Setup

  9. Click Next.
    The Setup Wizard installs the JDK. When setup completes, a screen to install JRE6 displays.
  10. Click Cancel, and then in the confirmation dialog box click Yes.
    The Install Success screen displays.
  11. Click Finish.
  12. A web browser window opens, presenting you with the option to register the JDK. Register, or close the window.

10.13.4 Install PostgreSQL Database

The OpenClinica software uses an underlying relational database management system, either PostgreSQL or Oracle. Complete these instructions if you will be using the PostgreSQL database. If you will be using the Oracle database, install Oracle instead of completing these instructions. Note: we do not provide instructions for installing Oracle.

  1. From this location http://svn.akazaresearch.com/oc/software/OpenClinica-3.1/windows/, download postgresql-8.4.7-2-windows.exe to c:ocinstall.
  2. Run:
    c:ocinstallpostgresql-8.4.7-2-windows.exe
    The
    Open File Security Warning message displays.
  3. Click Run.
    The PostgreSQL Installation Wizard opens.
  4. Click Next.
    The Installation directory screen displays.
  5. Click Next to accept the default values.
    The Data directory screen displays.
  6. Click Next to accept the default values.
    The Password screen displays.
  7. Enter a password for the Postgres superuser. Record the password for use later in the installation process. Re-enter the password, and click Next.
    The Port screen displays.
  8. Click Next to accept the default value (5432).
    The Advanced Options screen displays.

    Postgres Installation - Advanced Options

  9. Complete the screen as follows:
    1. For Locale, select “Default locale”.
    2. Clear the Install pl/pgsql in template1 database? checkbox.
    3. Click Next.

    The Ready to install screen displays

  10. Click Next to start the installation.
    When the installation finishes, the Completing the PostgreSQL Setup Wizard screen displays.
  11. Clear the Launch Stackbuilder at exit checkbox, then click Finish.

10.13.5 Install Tomcat

  1. From either of the following websites, download the Windows Service Installer Version, apache-tomcat-6.0.32.exe, and save it to c:ocinstall:
  2. Run
    c:ocinstallapache-tomcat-6.0.32.exe

    The Apache Tomcat Setup Installation Wizard opens.
  3. When the Open File – Security Warning message displays, click Run.
  4. On the Welcome screen of the Apache Tomcat Setup Installation Wizard, click Next.
    The License Agreement screen displays.
  5. Click I Agree to accept the agreement.
    The Choose Components screen displays.
  6. Click Next to accept the default values.
    The Configuration screen displays.
  7. Click Next to accept the default values.
    The Java Virtual Machine screen displays.
  8. Click , then select the path you installed the JDK into:
    c:ocjdk1.6.0_24
    The screen now should look like this:

    Tomcat Installation - JVM Path Selection

  9. Click Next.
    The Choose Install Location screen displays.
  10. Edit the Destination Folder to be c:octomcat. The screen should look like this:

    Apache Tomcat Installation - Location

  11. Click Install to start the installation.
    When the installation is finished, the Completing the Apache Tomact Setup Wizard screen displays.
  12. Complete the screen as follows:
    1. Clear the Run Apache Tomcat checkbox.
    2. Clear the Show Readme checkbox.

    The screen should now look like this:

    Tomcat Wizard Completion

  13. Click Finish.
  14. Create the directory c:octomcatoldwebapps.
  15. Move the web apps provided with Tomcat that OpenClinica does not need by moving the contents of c:octomcatwebapps to c:octomcatoldwebapps.

10.13.6 Install OpenClinica Package

  1. Download the OpenClinica software, OpenClinica-v.x.y.zip, from the OpenClinica website location, https://community.openclinica.com/project/openclinica. To download the software, you need a community account, which is free to create; you will be required to log in to the account to download the OpenClinica software.

    After downloading the OpenClinica software, move it to the directory with the other software dependencies you downloaded:
    c:ocinstall.

  2. Right-click OpenClinica-v.x.y.zip and select Extract All.
    The Extraction Wizard opens.
  3. Click Next.
  4. In the next screen, change the directory to c:ocinstall, and click Next.
  5. In the next screen, clear the Show Extracted Files checkbox, and click Finish.
  6. Copy c:ocinstallOpenClinica-v.x.ydistributionOpenClinica.war to c:octomcatwebapps.

10.13.7 Install OpenClinica Web Services Package

Web Services are optional. Please do not install them if you are not planning on using web services.

  1. Download the OpenClinica-ws software, OpenClinica-ws-v.x.y.zip, from the OpenClinica website location, https://community.openclinica.com/project/openclinica. To download the software, you need a community account, which is free to create; you will be required to log in to the account to download the OpenClinica software. After downloading the OpenClinica-ws software, move it to the directory with the other software dependencies you downloaded: c:ocinstall.
  2. Right-click OpenClinica-ws-v.x.y.zip and select Extract All.
  3. The Extraction Wizard opens.
  4. Click Next.
  5. In the next screen, change the directory to c:ocinstall, and click Next.
  6. In the next screen, clear the Show Extracted Files checkbox, and click Finish.
  7. Copy c:ocinstallOpenClinica-ws-v.x.ydistributionOpenClinica-ws.war to c:octomcatwebapps.

10.13.8 Set Up the PostgreSQL Database

Complete these instructions if you will be using the PostgreSQL database. If you will be using the Oracle database, instead use the Oracle setup instructions.

  1. Select Start > Programs > PostgreSQL 8.4 > pgAdminIII.
  2. The pgAdminIII window opens. Right-click the PostgreSQL 8.4 (localhost:5432) icon, and select Connect, as shown here:

    Postgres Setup - pgAdminIII

  3. Log in to the database server using the password you set up during the PostgreSQL installation.
  4. Create the database openclinica and the database user clinica, which OpenClinica uses to connect to the database:
    1. Expand the databases, and select postgreSQL.
    2. Select Tools > Query tool.
      The Query window opens.
    3. In the SQL Editor box, delete all the text.
    4. In the SQL Editor box, type the following:
      CREATE ROLE clinica LOGIN ENCRYPTED PASSWORD ‘clinica’ SUPERUSER NOINHERIT NOCREATEDB NOCREATEROLE;
    5. Select Query > Execute, which runs the SQL query.
      When the query completes, a message displays in the History window.
    6. In the SQL Editor box, delete all the text.
    7. In the SQL Editor box, type the following:
      CREATE DATABASE openclinica WITH ENCODING=’UTF8′ OWNER=clinica;
    8. Select Query > Execute.
      When the query completes, a message displays in the History window.
    9. Close the Query window, and click No when prompted to save changes.
  5. The database password is set to clinica by default, which is not a secure password. Change the password as follows:
    1. In the pgAdminIII window, expand and select Login Roles.
    2. Select View > Refresh.
      The clinica database user is listed.
    3. Right-click the clinica user account and select Properties.
    4. In the Login Role for clinica box that displays, enter the new password and re-enter it, then click OK. Record the password for future use.

10.13.9 Configure Tomcat

  1. Select Start > Apache Tomcat 6.0 > Configure Tomcat.
    The Apache Tomcat 6 Properties window opens.
  2. Click the Java tab, then complete the Java page as follows:
    1. For Maximum memory pool, enter 1280.
    2. In the Java Options text box, add this line at the end:

-XX:MaxPermSize=180m

Please note that this setting is based upon the number of war files deployed. The web war needs a 180m of PermGen and the ws war needs a 90m of PermGen memory settings.

  1. The window should now look like this:

    Tomcat 6 Properties

  2. Click Apply, which completes the configuration of Tomcat.
  3. Start Tomcat:
    1. Click the General tab.
    2. On the General page, click Start.
  4. In about five minutes, Tomcat will be fully started. Verify it is fully started by opening the file c:octomcatlogscatalina.out, and looking for this line:
    INFO: Server Startup in XXXXX ms
  5. After verifying Tomcat has fully started, in the General page of the Apache Tomcat 6 Properties window, click Stop.
  6. Wait two minutes for Tomcat to stop, then delete OpenClinca.war from c:octomcatwebapps.

10.13.10 Configure OpenClinica for better Performance

Under stress test, OpenClinica has performed well with the following JVM settings: 

Please click the Java Options tab described in the ‘Configure Tomcat’ section and add the following 

 -XX:+UseParallelGC
-XX:ParallelGCThreads=n
-XX:MaxPermSize=180m
-XX:+CMSClassUnloadingEnabled

 On Java Console use ‘Maximum Pool Size’ to 1280.

Please note that the bare minimum ram requirement is 1280 MB of memory for these settings, so the CPU is expected to have much higher RAM available.

Where n is the number of cores of your CPU.  There should be no spaces before or after each entry, Also each entry should be in a new line. The MaxPermSize value depends on the number of war files that you are deploying. For instance, if you deploy web and web servics, XX:MaxPermSize should be set to 360m. 

 -XX:ParallelGCThreads = # of cores of your CPU, as long as the number of processors on your CPU are lesser than 8.   The Window should look like this for a 4 core processor:

After the above settings have been applied, start Tomcat

10.13.11 Configure the OpenClinica Application

If you followed all the previous instructions exactly, 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, however.

  1. Using WordPad, open the configuration file:
    c:octomcatwebappsOpenClinicaWEB-INFclassesdatainfo.properties
  2. 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.

    The datainfo.properties file for Windows is the same as for Linuxsee more information at Description of datainfo.properties File.
  3. When you finish making changes, save the file.
  4. You may also need to configure OpenClinica for internationalization should you wish to utilize OpenClinica in different languages. Also, if you need to use some UTF-8 characters in your application, you may need to modify your default connecter configuration. For more information regarding configuring OpenClinica for internationalization and using UTF-8 characters, please refer to https://docs.openclinica.com/3.1/technical-documents/openclinica-and-internationalization

10.13.12 Configure the OpenClinica Web Services

If you followed all the previous instructions exactly, there is only one property in the configuration file, datainfo.properties, that you may need to change in order for OpenClinica Web Services to start. There are other properties in the configuration file you will probably want to modify for your system, however.

Note: Most of the properties are not needed or used for Web Services, see Description of datainfo.properties File for Web Services for more information on what settings are actually used.

  1. Using WordPad, open the configuration file:
    c:octomcatwebappsOpenClinica-wsWEB-INFclassesdatainfo.properties
  2. Edit values for the properties in the datainfo.properties file. You must change all values from Database Configuration section of datainfo.properties file to reflect your settings in datainfo.properties file for OpenClinica application. Change the values for any other properties. 

    The datainfo.properties file for Windows is the same as for Linuxsee more information at Description of datainfo.properties File for WebServices.

  3. If you are installing Web Services for OpenClinica 3.1.2 and early please edit adminEmail property (section 5 – adminEmail) if you would like e-mail to be send through ‘Contact’ link from Web Services welcome page.
  4. Other properties that can be configured for web services are:
    1. Section 11 – Logging configuration
  5. When you finish making changes, save the file.

10.13.13 Start Tomcat

Start Tomcat using any one of these methods:

  • From the Apache Tomcat 6 Properties window:
    1. Select Start > Apache Tomcat 6.0 > Configure Tomcat to open the window.
    2. Click the General tab.
    3. On the General page, click the Start button to start Tomcat.
  • Using the Windows run command:
    1. Select Start > Run.
    2. In the Run box, type cmd, then click OK.
    3. At the new command prompt, start Tomcat by typing
      net start tomcat6

      then press Enter.

      When you need to stop Tomcat, type
      net stop tomcat6

      then press Enter.

  • Via the Windows Services Microsoft Management Console (MMC), if you are familiar with it.

10.13.14 Verify the Installation

At this point, Java, Tomcat, PostgreSQL, and OpenClinica are installed and set up. Verify the installation was successful by following these steps:

  1. Open a web browser and access OpenClinica at the following URL:

    http://localhost:8080/OpenClinica

    The OpenClinica Log In page should display.

  2. Log in to OpenClinica using the default user name, root, and password 12345678. You will be forced to change the password for the user “root” to a secure password. See Update User Profile if you need more information.
  3. The user “root” is assigned to a default Study named “Default.” Create a user account for youself, with the User Type set to “technical administrator” and the User Role set to Data Manager: for instructions to create the user account, see Create a New User.

     

10.13.15 Verify the Installation of OpenClinica Web Services

  1. Point your web browser to the OpenClinica Web Services welcome page: http://<<server url>>:8080/OpenClinica-ws. The OpenClinica Web Services Welcome page should be display.
  2. Verify the version number is v.x.x-Community, where v.x.x is the version number you upgraded OpenClinica Web Services to. The version number is displayed in the lower right corner of the page.

Web Services should have the same version as OpenClinica application.