Neuron Installation Guide

D.J. Jacob Brady Mathis

Before You Begin

Demonstration Only
This guide is intended to help set up a demonstration instance of the Neuron Health platform. While Neuron is capable of high-availability and high-volume implementations, following this guide will result in a small-scale version of the system. This smaller instance is not intended to be used to support any production applications.

Ready For Production?
If you are ready to spin up a production-caliber instance of Neuron, contact the team at Roberts-Hoffman (the main project sponsor). There are several additional configurations that need to be addressed in a production environment, and we would love to save you the pain of trial-and-error!

Under The Hood
The Neuron Health platform is an extension of the [Tolven Platform]. Consequently, this document is based heavily on the Tolven V2.1 Windows Quick Start Install Guide. We have leveraged our experience with Tolven to simplify and streamline this guide to get you up and running in Neuron as quickly as possible.

Using Medication Orders
The Neuron Health platform requires the Lexi-Data drug database from Lexicomp, Inc. for ordering medications. Trial access to the Lexi-Data database can be obtained by contacting Roberts-Hoffman Software at info@robertshoffman.com.

Step 1 - Download and unzip packages

  1. Download the Tolven snapshot zip
  2. Download the RHS snapshot zip
  3. Unzip the Tolven snapshot to c:\tolven
  4. Unzip the RHS snapshot to c:\tolven\snapshots
  5. Copy the file c:\tolven\snapshots\tolven-config-plugins.xml to c:\tolven\tolven-config and rename it plugins.xml

Step 2 - Download necessary components

Download the following files, placing them in c:\tolven\initial-tolven-components.

  1. PostgreSQL 32-bit or 64-bit
  2. Apache Ant
  3. Download the appropriate version of the Java JDK from Oracle here. You must accept the license agreement before you can download the file.
  4. JBoss Application Server v6
  5. OpenDS
  6. OpenSSL binary packages for Windows: OpenSSL-0.9.8za-x86 or OpenSSL-0.9.8za-x64
  7. PostgreSQL JDBC Driver

A note about Java: This demonstration install uses Java 6. For any production environment, you will need to upgrade the stack to Java 7.

Step 3 - Install prerequisite software

Install JDK
Run the jdk.exe file downloaded in the last step. Use the default values provided during the installation. After installations completes, test the installation by running the java -version command from the command prompt. The output should look like:

java version "1.6.0_45"
Java(TM) SE Runtime Environment (build 1.6.0_45)
Java HotSpot(TM) 64-Bit Server VM (build ??., mixed mode)

Install Apache Ant
Extract apache-ant-1.8.2-bin.zip file to c:\ant.

Install OpenSSL
Extract the OpenSSL zip file to c:\openssl

Install PostgreSQL
Note: These instructions are assuming that you are performing a new PostgreSQL install. If you already have PostgreSQL installed, you can use that instance, but be sure to check your database properties in the next step.

  1. Open the Services window (click the start button and search for services).
  2. Locate the Secondary Logon service, right click, and select Properties.
  3. Change the Startup type selection to Automatic and click OK.
  4. If the Secondary Logon service isn’t started, start it now by right clicking and selecting Start.
  5. Double click the postgresql-9.0.4 exe file in the initial-tolven-components directory to start the PostgreSQL installer.
  6. Proceed through the installer, setting the password to postgres and the locale to English, United States. Accept the default values for all other selections. You do not need to install any extra utilities.
  7. Once the installation completes, stop the postgres service in the services window.

Step 4 - Modify plugins.xml

  1. If you are installing to a location other than c:\tolven, you must change the rootDir property.
  2. The default domain is dev.example.com. To install to a different domain, add a tolvenDomain property.
  3. Check that your database name, port, user, and password match the corresponding properties.

Step 5 - Add Server Name to Hosts File

  1. Open Notepad as an administrator. You must start Notepad as an administrator to complete this step. To start Notepad as an administrator, right click the Notepad icon, then click Run as Administrator. Then click continue on the dialog box that pops up.
  2. Click Open, then in the Open dialog box, browse to C:\Windows\System32\Drivers\etc.
  3. Change the file filter drop down box from Text Documents (.txt) to All Files (.)
  4. Open the hosts file.
  5. Add the following entry to your hosts file:
    127.0.0.1 dev.example.com Or substitute your host/domain here
  6. Save the hosts file and exit Notepad.

Step 6 - Set System Variables

  1. Go to Control Panel-->System and Security-->System and click Advanced System Settings on the left.
  2. Select the Advanced tab if it is not already selected.
  3. Click Environment Variables.
  4. Under System Variables, click New.
  5. Enter the variable name as JAVA_HOME.
  6. Enter the variable value as the installation path for the Java Development Kit. If your Java installation directory has a space in its path name, you should use the shortened path name in the environment variable. In this example, it would be one of the following:
    C:\Progra~1\Java\jdk1.6.0_45 – For Program Files.
    C:\Progra~2\Java\jdk1.6.0_45 – For Program Files(x86).
  7. Click OK.
  8. Under System Variables, click New.
  9. Enter the variable name as JRE_HOME.
  10. Enter the variable value as the installation path for the JRE (in this example, it is C:\Progra~1\Java\jre6).
  11. Click OK.
  12. Under System Variables, click New.
  13. Enter the variable name as ANT_HOME.
  14. Enter the variable value as the installation path for the Ant (in this example, it is C:\ant\apache-ant-1.8.2).
  15. Click OK.
  16. Under System Variables, click New.
  17. Enter the variable name as POSTGRES_HOME.
  18. Enter the variable value as the PostgreSQL installation path (in this example, it is C:\Progra~1\PostgreSQL\9.0).
  19. Click OK.
  20. Under System Variables, click New.
  21. Enter the variable name as PGDATA.
  22. Enter the variable value as the PostgreSQL data folder (in this example, it is C:\Progra~1\PostgreSQL\9.0\data).
  23. Under System Variables, click New.
  24. Enter the variable name as OPENSSL_HOME.
  25. Enter the variable value as the OpenSSL installation path (in this example, it is either C:\openssl\openssl-0.9.8za-x86 or C:\openssl\openssl-0.9.8za-x64).
  26. Click OK.
  27. Under the System Variables section, locate the PATH variable and double click it to bring up the editor.
  28. At the end of the line, paste the following (specific to your installation path), making sure that you have the semicolons (;) separating the values.
    ;%JAVA_HOME%\bin;%ANT_HOME%\bin;%JRE_HOME%\bin;%POSTGRES_HOME%\bin;%OPENSSL_HOME%\bin
  29. Click OK.
  30. Click OK three times to exit out.
  31. Restart Windows to load the system variables and restart the PostgreSQL service.

Summary of Environmental Variables and Values

Variable Name Default Value
JAVA_HOME C:\Progra~1\Java\jdk1.6.0_45
JRE_HOME C:\Progra~1\Java\jre6
ANT_HOME C:\ant\apache-ant-1.8.2
POSTGRES_HOME C:\Progra~1\PostgreSQL\9.0
PGDATA C:\Program Files\PostgreSQL\9.0\data
OPENSSL_HOME C:\openssl\openssl-0.9.8za-x??
PATH (append) ;%JAVA_HOME%\bin;%ANT_HOME%\bin;%JRE_HOME%\bin ;%POSTGRES_HOME%\bin;%OPENSSL_HOME%\bin

Step 7 - Create SSL Keystore

Copy the file JAVA_HOME\jre\lib\security\cacerts to your tolven\initial-tolven-components folder.

Open a command line window as administrator and execute the following two commands. These will generate most of the required keystores/truststores in the initial-tolven-components directory and leave the command window open when you are done:

cd C:\tolven\snapshots\V21_YYYYMMDD_snapshot\tolven-installer
ant generate-keystores

Confirm that the following files were created in the initial-tolven-components folder:

cacerts.jks
cert.cer
keystore.jks
keystore.p12
tolvendev-mdbuser.p12

Step 8 - Configure PostgreSQL for SSL

1. Create Key
From the initial-install-components directory create keys for PostgreSQL, using tolven as the default password, as follows:

cd C:\tolven\initial-tolven-components
keytool -importkeystore -srckeystore keystore.jks -destkeystore keystore.p12 -srcstoretype JKS -deststoretype PKCS12 -srcstorepass tolven -deststorepass tolven -noprompt

2. Export Key and Cert
Export the postgresql SSL server.key from the keystore.p12 (when prompted for Import Password and PEM pass phrase, enter tolven):

openssl pkcs12 -in keystore.p12 -out server.key -nocerts
openssl pkcs12 -in keystore.p12 -out server.crt -nokeys

3. Copy Cert
Make a copy of server.crt and call it root.crt:

copy server.crt root.crt

4. Move Files
Copy the files server.key, server.crt, and root.crt to your PostgreSQL data sub-folder:

copy server.key "%PGDATA%"
copy server.crt "%PGDATA%"
copy root.crt "%PGDATA%"

5. Modify Key
Execute the following from the command line using tolven as the pass phrase:

cd "%PGDATA%"
openssl dsa -in server.key -out server-nopasswd.key

Remove or rename server.key.

Rename server-nopasswd.key to server.key.

Set the permissions on server.key to read-only.

6. Server Properties
Locate the postgresql.conf file in the data sub-folder of your PostgreSQL installation folder, and open it in a text editor like Notepad. Set the following:

ssl = on (Uncomment this line and set it to on.)
listen_addresses = ‘*’
max_prepared_transactions = 10 (Uncomment this line and ensure that the value is 10 or the installation process will fail.)

Save the postgresql.conf file.

7. Network Access
To allow network access to the database, locate the pg_hba.conf file in the PostgreSQL data sub-folder. JDBC, even from localhost, requires network access to the database. Documentation is included in that file. Open the file in a text editor like Notepad. The uncommented line should look something like this:

# TYPE   DATABASE    USER        CIDR-ADDRESS          METHOD
hostssl  postgres    postgres    127.0.0.1/32          md5

You are done with the pg_hba.conf file, although remember to change this file if you need to access postgreSQL from clients not on localhost. You can also change the TYPE from hostssl to host, which will allow connections via non-ssl clients, but this is not recommended.

Save the pg_hba.conf file.

8. Restart to Apply
Stop and restart the PostgreSQL service. You can either use the service manager or use the following commands from the command prompt run as administrator. The PostgreSQL service name is either postgresql-9.0 or postgresql-x64-9.0:

sc stop postgresql-x64-9.0
sc start postgresql-x64-9.0

Step 9 - Install Tolven

At this point in the install procedure, it is advisable to make a backup copy of the tolven folder, including its sub-folders, before you execute the install command. If you are installing Tolven on a virtual machine, you can take a snapshot of the machine.

Open a command prompt window as administrator and navigate to C:\tolven\snapshots\V21_YYYYMMDD_snapshot\tolven-installer.

Execute the following command:

ant install-config-tolven

You should get a BUILD SUCCESSFUL message after a successful install. It is advisable to capture the details of the install script for troubleshooting by piping the output to a file, like this:

ant install-config-tolven > ant.log

This facilitates much easier debugging of the install process should things not go smoothly.

Note
This process can take a while to complete. On a Windows 7 VM with 1 GB and 1 CPU it can run for 15 to 20 minutes before completing. Also note that when OpenDS and the JBoss server start up, the Windows firewall will ask if you want to grant these programs access to the network; please do so.

After the install completes, you should now have the following sub-folders in the tolven folder:

initial-tolven-components
snapshots
tolven-config
tolven-jboss6
tolvenOpenDS

Troubleshooting Notes
If you are going to have trouble with the install, it will likely happen here. See Troubleshooting below for troubleshooting tips.

Step 10 - Activate Vocabularies

Note: Some of the vocabularies are quite large, and loading them can take some time. For a development environment, you can limit the vocabulary loading to 100 entries per vocabulary. This will significantly shorten the time required to load the vocabularies. If you don’t want to limit the download, skip over these steps

To Limit the Vocabulary Upload

  1. Open the C:\tolven\snapshots\V21_YYYYMMDD_snapshot\tolven-V2.1\bin\tpf.bat file with a text editor.
  2. To limit the download, add the following property option just after where it says java:
    -Dtolven.client.load.uploadLimit=100
    (Make sure that you include the dash before the D. You can change the value 100 to any value that you want.)
  3. Save the tpf.bat file.

Activate Vocabulary Plugins
These commands must be executed one at a time, in sequence from C:\tolven\snapshots\V21_yyyymmdd_snapshot\tolven-V2.1\bin.

tpf -plugin org.tolven.growthchart
tpf -plugin org.tolven.orders.imageorders
tpf -plugin org.tolven.orders.laborders
tpf -plugin org.tolven.deploy.problems
tpf -plugin org.tolven.deploy.rxnorm
tpf -plugin org.tolven.deploy.cvximmunization
tpf -plugin org.tolven.deploy.substancemanufacturer
tpf -plugin org.tolven.deploy.icd9procedures
tpf -plugin org.tolven.deploy.reportablediagnosisLoader
tpf -plugin org.r-hsoftware.lab
tpf -plugin org.r-hsoftware.radiology
tpf -plugin org.r-hsoftware.diagnoses.ICD9
tpf -plugin org.r-hsoftware.notes.Therapy
tpf -plugin org.r-hsoftware.occupationalTherapyProcedure
tpf -plugin org.r-hsoftware.respiratoryTherapyProcedure
tpf -plugin org.r-hsoftware.speechTherapyProcedure

Step 11 - Set up Lexi-Data drug database

For demonstration purposes, trial access to the Lexi-Data drug database can be obtained by contacting Roberts-Hoffman Software at info@robertshoffman.com. Roberts-Hoffman will provide instructions on how to configure the Neuron Health platform to access the trial database. You can also find information in the [System Administration Guide].

Step 12 - Load RHS Server properties

This step will load a set of default server properties. To view and change properties before loading them, see c:\tolven\snapshots\rhs-server-properties.xml

In the same location as the previous step (C:\tolven\snapshots\V21_yyyymmdd_snapshot\tolven-V2.1\bin), execute the following command to load default server properties.

tpf -plugin org.tolven.appserverproperties -load

Step 13 - Create User and Log into Neuron

Required User Attributes

Field Description
Realm Select the tolven realm.
First Name The first name of the user.
Last Name The last name of the user.
A unique user id A unique user ID to be used for Neuron login
Email Address The user’s email address.
Organization Unit Name A higher-level organizational group name to which the user belongs.
Organization Name The name of the organization to which the user belongs.
State or Province The state or province where the user works.
  1. Browse to https://dev.example.com:8443/gatekeeper/html/login/login.jsf.
  2. Enter admin as the user and sysadmin as the password.
  3. Click Create User to create a demo user.
  4. Enter data in the required fields (above).
  5. Enter admin as the user and sysadmin as the password.
  6. Click Activate. Neuron generates a password for the user that is displayed in a message below. Make sure to write down the password for later use.
  7. Click Home Page.
  8. Click Logout.
  9. Click the TolvenGateKeeper link.
  10. Sign on again using the username you created and the password Neuron generated in order to verify that the user was created.
  11. You may optionally follow the Manage Login Password link to change the password on your newly created account.
  12. Click Logout.

You can also find more detailed information about users, roles, permissions, and security in the [System Administration Guide].

Step 14 - Log into Neuron and create an account.

  1. Browse to https://dev.example.com:8443/Tolven
  2. Log in with the username and password you created previously.
  3. Click Create a new clinical or personal account.
  4. Select Clinician Health Record as the Account Type, and enter an Account Title.
  5. Select the timezone if desired, and choose whether or not to add demo data.
  6. Click Create Account. This will take you back to the Account Selection screen.
  7. Click Login beside the account you just created.

Troubleshooting

Important Files for Troubleshooting

Installation Log - C:\tolven\snapshots\V21_YYYYMMDD_snapshot\tolven-installer\install.log

Ant script output (see Step 9) - C:\tolven\snapshots\V21_YYYYMMDD_snapshot\tolven-installer\ant.log

JBoss Boot log - c:\tolven\tolven-jboss6\server\tolven\log\boot.log

JBoss Server log - c:\tolven\tolven-jboss6\server\tolven\log\server.log

The issues listed here include those that can occur during the installation or the configuration.

Install fails right away
If your install fails at the very beginning and does not recognize the ant command, you may have not specified the ant installation variable and listed it in your path, or you specified it incorrectly. See Step 6.

Session/Transaction Timeout
During the install and configuration, certain processes can fail if the transactions take too long to complete. You may find that ant install-config-tolven returns BUILD SUCCESSFUL as the output, but that you are unable to load vocabularies or create an account (the account type selection is empty). If you observe these symptoms, you may need to take special installation steps to increase the system performance or increase the transaction timeout.

Performance Considerations
If you install Neuron on a demonstration machine with limited resources, you may encounter the Session/Transaction Timeout problem. On a server-caliber Linux Operating System, you will be able to install the Neuron demo with 1 CPU and 1 GB of memory. However, a Windows OS will require more resources for a successful install. If you have the symptoms of the transaction timeout, consider adding resources to the system.

Increasing the Transaction Timeout
Note: This troubleshooting step only applies to systems that demonstrate the characteristics described in the Session/Transaction Timeout section. If you are getting the message BUILD FAILED, you are not ready to try this step.

  1. Do NOT reset the install by deleting folders. You should be able to adjust the timeout and carry on from where you are now.
  2. Locate c:\tolven\tolven-jboss6\server\tolven\deploy\transaction-jboss-beans.xml and open it in a text editor.
  3. Locate the property <property name="defaultTimeout">300</property>
  4. Increase the setting (in minutes). A value of 900 is 15 minutes and has been found to be sufficient to allow transactions to complete, but increase this value more if you need more.
  5. Save and close the file.
  6. Navigate to C:\tolven\snapshots\V21_yyyymmdd_snapshot\tolven-V2.1\bin
  7. Run configPhase3.bat

This batch file is the final step of ant install-config-tolven, and is the step that fails when the transactions take too long to complete. Re-running this step should complete the install process and you can resume loading vocabularies in step 10.

Can't find the host in the browser
If you see errors saying that there are problems with finding dev.example.com (or your name of choice), make sure that you made the proper entry in your HOSTS file. If you use something other than dev.example.com, you also have to specify that in plugins.xml file. Be absolutely sure you make no typographic errors in HOSTS or in plugins.xml.

Database connection errors
If there are errors that indicate trouble connecting to the database, make sure the database service is started. If you are using PostgreSQL, be sure that you followed the steps in the Configure PostgreSQL step above. If you have to make changes to the PostgreSQL configuration files, you will need to stop and restart the PostgreSQL service for those changes to take effect.

Java errors
If you encounter Java errors that indicate that it can’t find the Java resources required, you may not have specified the JAVA_HOME and JDK_HOME variables and listed them in your path, or you specified them incorrectly. See Step 6.

If you get the following warning message:
WARN [loggerI18N] [com.arjuna.ats.internal.jta.resources.arjunacore.norecoveryxa] [com.arjuna.ats.internal.jta.resources.arjunacore.norecoveryxa] Could not find new XAResource to use for recovering non-serializable XAResource...
open the postgres.conf file in a text editor and change the max_prepared_transactions property to be greater than zero. 10 is recommended. Uncomment and change the following:
max_prepared_transactions = 10 # zero disables the feature
Stop and restart the PostgreSQL service.

Other possibilities
Make sure that all of the versions of the components you placed in the initial-tolven-components folder match the versions as listed in this guide.

JVM Memory Settings
The out-of-the-box configuration of the JVM is restricted to 1 GB of working memory. To adjust this setting, modify c:\tolven\tolven-jboss6\bin\startTolvenJBoss.bat. This batch file has the following memory configuration property on the first line: -Xmx1024m. Adjust this property up to increase total memory available to the JVM; adjust this property down to lower the memory limit and reduce the impact of the JVM on the system resources.

Restarting the Install

After making any adjustments to your settings or files, do the steps below to re-start the install.

If your install failed during the config-tolven step, you will have to re-do the install as well. Follow the same steps below.

  1. Shutdown JBoss by opening the command prompt as Administrator and executing the following from the tolven\tolven-jboss6\bin folder:
    stopTolvenJBoss.bat
  2. Shut down OpenDS by executing the following from the tolven\tolvenOpenDS\bat folder:
    stop-ds
  3. Delete the tolven-jboss6 and tolvenOpenDS folders. Open the tolven-config folder. Delete the build, credentials, devLib, repositoryLocal, and repositoryRuntime folders. Delete the boot.properties file.
  4. If you’re using PostgreSQL, you will need to drop the PostgreSQL schemas that were automatically created during the install. Open pgAdmin III. The .exe file for it is in your PostgreSQL bin sub-directory.
  5. Connect to your local db instance by using the password and port number that you specified during setup:
    Suggested password: postgres
    Suggested port: 5432
  6. Expand to the following level in the tree: Servers -> PostgreSQL X -> Databases ->postgres.
  7. Select the postgres database and expand the Schemas.
  8. Run the following SQL to drop the existing schemas:

Schemas to drop

drop schema app cascade;
drop schema core cascade;
drop schema doc cascade;
drop schema gen cascade;
drop schema provider cascade;
drop schema public cascade;

The schemas will be automatically created again when you run the install.

Re-start the install process again.


Related

Wiki: Home
Wiki: System Administration Guide
Wiki: Technical Guides
Wiki: Tolven Platform

Get latest updates about Open Source Projects, Conferences and News.

Sign up for the SourceForge newsletter:





No, thanks