Skip Headers

Oracle® Health Sciences Empirica Healthcare Analysis Installation Guide Release 1.0.1 E57001-01 |
| Contents

Previous | Next |

# 3 Preparing the database and application servers

This chapter includes the following topics:

- Required privileges for the database server

- Required privileges for the application server

- Requirements and assumptions for the Linux accounts

- Preparing the installation staging area

- Downloading the Toolbox.zip file

- Configuring the connection to the Oracle database

- Setting up the application database account

- Preparing the environment on the application server

- Starting WebLogic and the Node Manager

## Required privileges for the database server

You must have access to the following types of accounts:

- A user account that allows the user to start and stop the Oracle database.

  This account should not have sudo privileges.

  This document refers to this user account as the non-privileged user account.

- A user account with sudo privileges. This user executes certain steps as root.

  This document refers to this user account as the privileged user account.

## Required privileges for the application server

You must have access to the following types of user accounts:

- A user account that allows the user to start and stop the WebLogic server.

  This account should not have sudo privileges.

  This document refers to this user account as the non-privileged user account.

  Unless otherwise specified in this document, the non-privileged user should perform all activities.

- A user account that has sudo privileges. This user executes certain steps as root.

  This document refers to this user account as the privileged user account.

## Requirements and assumptions for the Linux accounts

This section discusses the requirements and assumptions for the Linux accounts.

### Setting the default file creation umask

Perform this step as the non-privileged user on the application server.

- Edit the `~/.login` file, and add the following command to the file:

  `umask 027`

  The command sets the default file creation umask, so that by default, files you create give read-only access to other users in your group and no permissions to users outside the group.

## Preparing the installation staging area

This section discusses the steps to unpack the Empirica Healthcare Analysis installation files.

### Downloading the Toolbox.zip file

1. Navigate to the following URL:

   `http://www.drugepi.org/toolbox-archive/`

2. Download the archived Pharmacoepidemiology Toolbox including High-dimensional Propensity Score (hd-PS) package, version 2.4.11.

   This guide refers to this package as `Toolbox.zip`.

### Unpacking the installation files into the installation directory

Choose an installation directory that is on the application server and that is accessible to the WebLogic software, such as `/u01/stage`. The installation directory stores Empirica Healthcare Analysis components during the installation process.

1. Log in to the application server as the non-privileged user.

2. Using a tool such as the tar command, unpack the `Healthcare_Install.tar.gz` to the `/u01/stage` directory. For example, use the following command:

   `$ cd /u01/stage/`

   `$ tar xvf /u01/stage/Healthcare_Install.tar.gz`

   The `/u01/stage/Healthcare_Install` directory is created.

   Note: In this document, `<`INSTALL_DIR`>` refers to the folder created in this step, such as `/u01/stage/Healthcare_Install`. This document assumes that you are installing to this directory.

3. Using a tool such as unzip, unpack the `Healthcare-1_0_1_0_XXX.zip` file into the `<`INSTALL_DIR`>/Healthcare` directory.

4. Unpack the `Database.zip` file:

   1. Create the following directory:

      `/u01/stage/Database`

   2. Using a tool such as unzip, unpack the contents of the `Database.zip` file into the directory.

5. Using a tool such as unzip, unpack the contents of the `Toolbox.zip` file that you downloaded in Downloading the Toolbox.zip file into the following directory:

   `/u01/stage`

   A directory named toolbox is created within the `/u01/stage` directory.

## Configuring the connection to the Oracle database

This section includes the following topic:

- Adding the database TNSNAMES entry

### Adding the database TNSNAMES entry

Perform these steps using the non-privileged user account.

1. On the application server, open the `tnsnames.ora` file, located in the following directory:

   `<`ORACLE_HOME`>/network/admin/`

   If the file does not exist, create it.

2. Add an entry that points to the database, using the information found in the `TNSNAMES.ORA` file on the database server. For more information, see Information to collect before you begin.

## Setting up the application database account

Perform these steps as the non-privileged user on the application server.

1. In a command shell, use the following command to navigate to the `/u01/stage/`Database directory:

   `$ cd /u01/stage/Database`

2. Review the `1_create_healthcare_tablespaces_linux.sql` file:

   1. Edit the `1_create_healthcare_tablespaces_linux.sql` file. For example:

      `$ vi 1_create_healthcare_tablespaces_linux.sql`

   2. To create the data files in a location other than the default location of your database, specify the alternate location in the datafile_path variable. The path must end in a forward slash (/). For example:

      `DEFINE datafile_path = '/u01/app/oracle/oradata/<sid>/'`

   3. Save the file, and exit the vi editor.

3. Create the application tablespace:

   1. Execute the `1_create_healthcare_tablespaces_linux.sql` script from the Oracle system account.

      For example, type:

      `$ sqlplus system@`<TNS_Name`> @1_create_healthcare_tablespaces_linux.sql`

   2. When prompted, type the Oracle system account password.

4. Create the application Oracle user and schema:

   1. Type the following text:

      `$ sqlplus sys@<`TNS_Name`> as sysdba @2_create_healthcare_oracle_user.sql`

   2. When prompted, type the Oracle sys account password.

   3. When prompted a second time, create a password for the Empirica Healthcare Analysis database account. Retype the password to verify it.

      Note: Remember this password for later in this procedure.

   4. When prompted, create a password for the empirica_admin account.

   5. Retype the password to verify it.

      Note: Remember this password.

5. Populate the application schema:

   1. Execute the `3_create_all SQL` script from the Empirica Healthcare Analysis database account (not the sys or system accounts). For example:

      `$ sqlplus healthcare@<`TNS_name`> @3_create_all.sql`

   2. When prompted, type the Healthcare database account password that you created in the previous step.

## Preparing the environment on the application server

This section includes the following topics:

- Installing unlimited strength encryption Java libraries

- Installing and configuring Xvfb

- Modifying the default WebLogic Configuration

### Installing unlimited strength encryption Java libraries

Perform these steps using the privileged user account on the application server.

1. Copy the following files from the installation directory to the JDK installation directory:

   - `local_policy.jar`

   - `US_export_policy.jar`

   For example, using the privileged user account, execute the following commands in a command shell, updating the path to match the location of your JDK:

   `$ sudo su - root`

   `# cp -f <`INSTALL_DIR`>/java/*.jar /usr/java/jdk1.7.x_xx/jre/lib/security/`

   `# exit`

2. If you are prompted to overwrite files, type y and press Enter.

3. Ensure that the two files have the same ownership and permissions as the rest of the files in the destination directory.

### Installing and configuring Xvfb

The following instructions are for installing Xvfb, the X Windows Virtual Frame Buffer.

These procedures are required on the application server for the creation of graphs.

#### Determining whether Xvfb is installed

Perform these steps using the privileged user account.

1. Execute the following command in a command shell:

   `$ which Xvfb`

2. If the following response or some other path to Xvfb appears, Xvfb is already installed. Continue to Configuring Xvfb.

   `/usr/bin/Xvfb`

#### Installing Xvfb

Prerequisites: Yum must be installed and configured with an appropriate configuration file. Additionally, your system must be able to connect to the Yum repositories. For more information on configuring Yum for an Oracle Linux 6 system, see `http://public-yum.oracle.com/`.

If Xvfb is not installed, perform the following steps using the privileged user account.

1. If Xvfb is not installed, type the following command:

   `$ sudo yum install Xvfb`

2. If you are prompted for your password after typing this command, type your password, not the password of root.

3. When prompted, type Y, and press Enter.

#### Configuring Xvfb

Perform these steps using the privileged user account.

1. Execute the following commands in a command shell:

   `$ sudo su - root`

   `# cp <`INSTALL_DIR`>/service/xvfb /etc/rc.d/init.d`

   `# /sbin/chkconfig --add xvfb`

2. Execute the following command. This command verifies that the installation was successful.

   `# /sbin/chkconfig --list xvfb`

   The following response appears:

   `xvfb 0:off 1:off 2:off 3:on 4:off 5:on 6:off`

3. Manually start Xvfb by executing the following command:

   `# /etc/rc.d/init.d/xvfb start`

   The following response appears:

   Starting X Virtual Frame Buffer

4. Type exit to stop running as root.

### Modifying the default WebLogic Configuration

Make the following modifications in the WebLogic domain bin directory, such as `/u01/app/oracle/Middleware/user_projects/domains/empirica/bin`.

1. Using the non-privileged user account, open the file `setDomainEnv.sh` in a text editor, such as vi.

2. Type the following text at the bottom of the file. If you are not using UTC for the time zone, adjust the time zone in the text accordingly:

       # Local Customization
       export TZ=UTC
       export LANG=en_US.UTF-8
       export DISPLAY=localhost:99.0

3. In the `setDomainEnv.sh` file, search for instances of `ojdbc6dms.jar`:

   - If no instances exist, continue to step 4.

   - If at least one instance exists, replace all instances with `ojdbc6.jar` from the `$ORACLE_HOME` folder.

   For example, edit the following text:

   to look like the following text:

   Note: In the previous examples, the text highlighted in green replaces the yellow text.

4. Search for any instance of setting the JVM option java.awt.headless to true:

   - If no instances exist, continue to the next step.

   - If an instance exists, either remove or disable the instance.

   For example, replace the following text:

       EXTRA_JAVA_PROPERTIES="${EXTRA_JAVA_PROPERTIES} -Dem.oracle.home=/u01/app/oracle/Middleware/oracle_common -Djava.awt.headless=true"

   with the following text:

       #EXTRA_JAVA_PROPERTIES="${EXTRA_JAVA_PROPERTIES} -Dem.oracle.home=/u01/app/oracle/Middleware/oracle_common -Djava.awt.headless=true"
       EXTRA_JAVA_PROPERTIES="${EXTRA_JAVA_PROPERTIES} -Dem.oracle.home=/u01/app/oracle/Middleware/oracle_common"

5. Save the file, and exit the editor.

## Starting WebLogic and the Node Manager

Perform these steps on the application server using the non-privileged user account.

1. In a command shell, navigate to the WebLogic default domain bin directory, using a command such as the following:

   `$ cd /u01/app/oracle/Middleware/user_projects/domains/empirica/bin`

2. If WebLogic is running, execute the command:

   `$ ./stopWebLogic.sh`

3. To start WebLogic, execute the following command:

   `$ nohup ./startWebLogic.sh > /dev/null &`

   Note: Information messages might appear. You might need to press Enter to see the prompt.

4. Identify the process ID for the Node Manager service. For example, use the following command:

   `pgrep -f "java.+NodeManager -v$"`

5. Stop the Node Manager. For example, use the following command:

   `kill -9 <process_id_for_the_Node_Manager_service``>`

   such as:

   `kill -9 15318`

6. Start the Node Manager:

   1. Navigate to $WL_HOME/server/bin directory, such as:

      `/u01/app/oracle/Middleware/wlserver_10.3/server/bin`

   2. Execute the following command:

      `$ nohup ./startNodeManager.sh > /dev/null &`

7. Verify that the Node Manager can be reached:

   1. In an internet browser, enter the URL for the WebLogic Administration Console, such as the following:

      `https://<`servername`>:7002/console`

   2. Log in to the WebLogic Administration Console using the WebLogic administrator credentials provided to you by the system administrator.

   3. In the left pane, expand Environment, and select Machines.

      The Summary of Machines page appears.

   4. In the list of machines, select EHCMachine.

      The Settings for EHCMachine page appears.

   5. Select the Monitoring tab.

   6. Confirm that the status is Reachable. If status is Inactive, the Node Manager is not running.

8. Exit the command shell.

9. In the Domain Structure section on the left, expand Environment, and select Servers.

10. In the table of servers, select EHCServer.

    The Settings for EHCServer page appears.

11. Select the Configuration tab, and select the Server Start sub-tab.

12. In the Change Center section on the left, click Lock & Edit.

13. In the Arguments field, type the following text:

    `-Xms256m -Xmx2048m -XX:MaxPermSize=1024m`

    Note: `-XmxNNNNm` and `-XX:MaxPermSize` are memory parameters that control the amount of memory used by the Empirica Healthcare Analysis application. You might need to adjust the parameters upwards to achieve appropriate performance. The numbers to use depend on the size of the data set installed and the number of users expected to access the system simultaneously.

14. Click Save.

15. In the Change Center section on the left, click Activate Changes.

    Your changes are activated. This might take a few moments.

16. On the left, select Servers.

17. Select the Control tab.

18. Start or restart the EHCServer:

    1. In the table of servers, if the State of the EHCServer is SHUTDOWN, proceed to step d.

    2. In the table of servers, if the State of the EHCServer is RUNNING, select the check box for the server, expand the Shutdown drop-down menu, located above and below the table, and select Force Shutdown Now.

       You are prompted to confirm the shutdown.

    3. Click Yes.

    4. Wait until the State of the server changes to SHUTDOWN. The page does not refresh automatically. To refresh the page, click the refresh button, located above the table, or click the refresh button for your browser.

    5. In the table of servers, select the check box for the EHCServer, and click Start, located above and below the table.

       You are prompted to confirm the start.

    6. Click Yes.

    7. Wait until the State of the server changes to STARTING and then RUNNING. The page does not refresh automatically. To refresh the page, click the refresh button, located above the table, or click the refresh button for your browser.