Karush Logo
BlogAbout

i2b2 Installation

Install i2b2 Software (i2b2.org) on Windows Server 2016

I was recently asked to install the software for i2b2 (i2b2.org), which is a web tool for health care clinical research.

As I've found with most documentation for large, open sources projects the documentation is incomplete or out of date, and the official i2b2 install documentation is no exception. The official documentation for the i2b2 install process is found here.

This document will summarize the key steps for installing i2b2 on Windows Server. The steps should be completed in order.

Note that details I've omitted are either common knowledge for a Windows user, can be easily searched, or should possibly be handled by your IT Operations. Contact me if you think I've left significant gaps.

Prerequisites:

  • Spin up a Windows Server 2016 VM somewhere and make sure you can log in and have administrative rights. I used Microsoft Azure to create a test server in the cloud. Note that your IT Operations group will probably handle this in a production environment, but this will be a trial install - practice before the production install.
  • Install SQL Server 2017 Express Edition. Again you probably already have a production SQL Server instance, but this document geared toward a trial install.
  • Install SQL Server Management Studio so you can access and configure databases as needed.

Here we go...

  • Make a folder: C:\DATA. This is where we are going to put everything. This becomes important later when we need to reference the paths of various things.
  • Make a sub folder called install (C:\DATA\install). Put everything you download in here. Also extract the various .zip files right into this folder.
  • I2B2 is based on Java, so download and install the Java JDK - Java SE 8u251.
  • I'm running 64-bit Windows Server so I installed 64-bit Java (jdk-8u251-windows-x64.exe)
  • You will probably have to create an Oracle account to download
  • Defaults are fine during install

Install Wildfly

  • A lot of the official documentation references "JBoss", which is a Java application server, similar to Microsoft IIS. However that is no longer used and "Wildfly" is used in the place of "JBoss".
  • Download i2b2 Core Software from here, under "Download Binary Distribution", named i2b2core-new-1712a.zip. Exact name/version may vary. This is the official supported package for i2b2. There is a folder for Wildfly in here.
  • Copy the downloaded .zip file to C:\DATA\install and extract the files/folders.
  • In the extracted folders fine the folder "wildfly-17.0.1.Final". Copy the contents of that folder to C:\DATA\wildfly
  • Modify C:\DATA\wildfly\standalone\configuration\standalone.xml and make sure it has these exact values (near the bottom, change the port numbers):
	<socket-binding name="http" port="${jboss.http.port:9090}"/><socket-binding name="ajp" port="${jboss.ajp.port:9009}"/>
  • Set a Windows environment variable for "JAVA_HOME"
    • Search for Environment Variables then select Edit the system environment variables
    • Click the Environment Variables button
    • Under System Variables, click New.
    • In the Variable Name field, enter JAVA_HOME
    • In the Variable Value field, enter C:\Program Files\Java\jdk1.8.0_251 (ie. location of where you installed Java earlier)
    • Click Ok
  • Now we are going to configure Wildfly to run as a Windows Service
    • Copy the service directory from here C:\DATA\wildfly\docs\contrib\scripts\service to C:\DATA\wildfly\bin
    • Open Powershell as an administrator and navigate to the service folder C:\DATA\wildfly\bin\service
    • Run ".\service.bat install". You should see a success message
    • Reboot
    • Open Windows Service Manager and find Wildfly. Change it to Autostart. Start the service.
    • Go to this URL and confirm the service is running: http://localhost:9090/

Install IIS

  • Server Manager -> Manage -> Add Roles and Features -> Web Server (IIS)
  • Accept the defaults during the install process. Your IT Operations may have other specific requirements for IIS configuration.
  • Create a folder C:\DATA\i2b2. Open notepad and create a file called index.htm and put the text "hello world" in the file. Save it to C:\DATA\i2b2.
  • Open Internet Information Services (IIS) Manager
  • Delete the default website.
  • Create a new website called i2b2 and point it to this folder: C:\DATA\i2b2
  • Go to this URL and confirm that you see the text "hello world": http://localhost

Install PHP

  • Open Internet Information Services (IIS) Manager
  • Select the top node in the tree view that contains the server name
  • Click on "Get New Web Platform Components" under Actions on the right. Click "Install this Extension" and install.
  • Close and reopen IIS Manager. There will be a new node under Management called "Web Platform Installer". Run that.
  • Search for "PHP". Order by release date, descending. Select PHP 7.4.1 (x64) or similar version. Click Add. Click Install. Accept defaults. A few unnecessary items may fail to install. That's Ok.
  • Open notepad. Create a text file called "phpinfo.php" and put it in the folder C:\DATA\i2b2.
  • Add this text to the file:
	<?php phpinfo(); ?>
  • Go to this URL and confirm that you see a web page showing various PHP configuration details: http://localhost/phpinfo.php

Install i2b2 Web Server Software

  • The folder you need for this step was downloaded in the earlier Wildfly step (i2b2 Core Software). Find the folder "webclient" in the extracted folders.
  • Copy the "webclient" folder to C:\DATA\i2b2
  • Go to this URL and confirm that you see an I2B2 web page: http://localhost/webclient/ (note: you won't be able to login yet).
  • Reboot the server. The will cause a number of ".war" files in C:\DATA\wildfly\standalone\deployments to become deployed.
  • Go to this URL and confirm that you see a web page that says "Available Services" : http://localhost:9090/i2b2/services/listServices
  • These are the backing web services used by the I2B2 web site. We'll connect these to the database(s) later.

Install Apache Ant

  • This utility will be used in the following step to run the database creation scripts.
  • Download Apache Ant from here. This is the official supported version for I2B2.
  • The .zip file will extract to the folder "apache-ant-1.9.6-bin". Copy the contents of that folder to C:\DATA\apache-ant

Data Installation

  • Create the following databases, named exactly as follows: i2b2demodata, i2b2hive, i2b2imdata, i2b2metadata, i2b2pm, and i2b2workdata. 100 MB data file and 10 MB log file is fine to start.
  • Create a SQL Server account called "app_i2b2". Give it an appropriate password and add the account to the "sysadmin" role. You could create multiple accounts like the official i2b2 documentation suggests. "sysadmin" role can be reduced to "db_owner" on each database after Data Installation.
  • Make sure TCP/IP is enabled for SQL Server (disabled by default) and, at least in a test environment, disable any local Windows firewalls (enabled by default).
  • Download the data setup files from here under Download Source Code -> i2b2createdb-1712a.zip (version may differ)
  • I believe you can also use the "edu.harvard.i2b2.data" folder downloaded in the earlier Wildfly step (i2b2 Core Software).
  • The .zip file will extract to the folder "i2b2-data-1.7.12a.0001". Copy the contents of that folder to C:\DATA\install\i2b2-data-1.7.12a.0001

Data Installation - CRC Data

  • Open this file in notepad: C:\DATA\install\i2b2-data-1.7.12a.0001\i2b2-data-1.7.12a.0001\edu.harvard.i2b2.data\Release_1-7\NewInstall\Crcdata\db.properties
  • Set the contents of the file to be the following:

File Contents:

db.type=sqlserver
db.username=app_i2b2
db.password=[password you picked for app_i2b2]
db.driver=com.microsoft.sqlserver.jdbc.SQLServerDriver
db.url=jdbc:sqlserver://[your server IP address];database=i2b2demodata
db.project=demo
  • Open Powershell and cd to: C:\DATA\install\i2b2-data-1.7.12a.0001\i2b2-data-1.7.12a.0001\edu.harvard.i2b2.data\Release_1-7\NewInstall\crcdata>
  • Run this command: c:\data\apache-ant\bin\ant.bat -f data_build.xml create_crcdata_tables_release_1-7
  • Tables will then be built in the "i2b2demodata" database. You might get an error about a "full text index". Ignore it.
  • Run this to create the stored procedures: c:\data\apache-ant\bin\ant.bat -f data_build.xml create_procedures_release_1-7
  • Run this to load database with demo data: c:\data\apache-ant\bin\ant.bat -f data_build.xml db_demodata_load_data

Data Installation - Hive Data

  • Open this file in notepad: C:\DATA\install\i2b2-data-1.7.12a.0001\i2b2-data-1.7.12a.0001\edu.harvard.i2b2.data\Release_1-7\NewInstall\Hivedata\db.properties
  • Set the contents of the file to be the following:

File Contents:

db.type=sqlserver
db.username=app_i2b2
db.password=[password you picked for app_i2b2]
db.driver=com.microsoft.sqlserver.jdbc.SQLServerDriver
db.url=jdbc:sqlserver://[your server IP address];database=i2b2hive
  • Open Powershell and cd to: C:\DATA\install\i2b2-data-1.7.12a.0001\i2b2-data-1.7.12a.0001\edu.harvard.i2b2.data\Release_1-7\NewInstall\hivedata>
  • Run this command: c:\data\apache-ant\bin\ant.bat -f data_build.xml create_hivedata_tables_release_1-7
  • Tables will then be built in the "i2b2hive" database.
  • Run this to load database with demo data: c:\data\apache-ant\bin\ant.bat -f data_build.xml db_hivedata_load_data

Data Installation - IM Data

  • Open this file in notepad: C:\DATA\install\i2b2-data-1.7.12a.0001\i2b2-data-1.7.12a.0001\edu.harvard.i2b2.data\Release_1-7\NewInstall\Hivedata\db.properties
  • Set the contents of the file to be the following:

File Contents:

db.type=sqlserver
db.username=app_i2b2
db.password=[password you picked for app_i2b2]
db.driver=com.microsoft.sqlserver.jdbc.SQLServerDriver
db.url=jdbc:sqlserver://[your server IP address];database=i2b2imdata
  • Open Powershell and cd to: C:\DATA\install\i2b2-data-1.7.12a.0001\i2b2-data-1.7.12a.0001\edu.harvard.i2b2.data\Release_1-7\NewInstall\imdata>
  • Run this command: c:\data\apache-ant\bin\ant.bat -f data_build.xml create_imdata_tables_release_1-7
  • Tables will then be built in the "i2b2imdata" database.
  • Run this to load database with demo data: c:\data\apache-ant\bin\ant.bat -f data_build.xml db_imdata_load_data

Data Installation - Metadata Data

  • Open this file in notepad: C:\DATA\install\i2b2-data-1.7.12a.0001\i2b2-data-1.7.12a.0001\edu.harvard.i2b2.data\Release_1-7\NewInstall\metadata\db.properties
  • Set the contents of the file to be the following:

File Contents:

db.type=sqlserver
db.username=app_i2b2
db.password=[password you picked for app_i2b2]
db.driver=com.microsoft.sqlserver.jdbc.SQLServerDriver
db.url=jdbc:sqlserver://[your server IP address];database=i2b2metadata
db.project=demo
  • Open Powershell and cd to: C:\DATA\install\i2b2-data-1.7.12a.0001\i2b2-data-1.7.12a.0001\edu.harvard.i2b2.data\Release_1-7\NewInstall\metadata>
  • Run this command: c:\data\apache-ant\bin\ant.bat -f data_build.xml create_metadata_tables_release_1-7
  • Tables will then be built in the "i2b2metadata" database.
  • Run this to load database with demo data: c:\data\apache-ant\bin\ant.bat -f data_build.xml db_metadata_load_data (make sure you added the line for db.project in the db.properties file or this step will fail).

Data Installation - PM Data

  • Open this file in notepad: C:\DATA\install\i2b2-data-1.7.12a.0001\i2b2-data-1.7.12a.0001\edu.harvard.i2b2.data\Release_1-7\NewInstall\pmdata\db.properties
  • Set the contents of the file to be the following:

File Contents:

db.type=sqlserver
db.username=app_i2b2
db.password=[password you picked for app_i2b2]
db.driver=com.microsoft.sqlserver.jdbc.SQLServerDriver
db.url=jdbc:sqlserver://[your server IP address];database=i2b2pm
  • Open Powershell and cd to: C:\DATA\install\i2b2-data-1.7.12a.0001\i2b2-data-1.7.12a.0001\edu.harvard.i2b2.data\Release_1-7\NewInstall\pmdata>
  • Run this command: c:\data\apache-ant\bin\ant.bat -f data_build.xml create_pmdata_tables_release_1-7
  • Tables will then be built in the "i2b2pm" database.
  • Run this to create triggers: c:\data\apache-ant\bin\ant.bat -f data_build.xml create_triggers_release_1-7
  • Run this to load database with demo data: c:\data\apache-ant\bin\ant.bat -f data_build.xml db_pmdata_load_data (note: the data load didn't work correctly for me so I then had to run pm_access_insert_data.sql manually)

Data Installation - Work Data

  • Open this file in notepad: C:\DATA\install\i2b2-data-1.7.12a.0001\i2b2-data-1.7.12a.0001\edu.harvard.i2b2.data\Release_1-7\NewInstall\workdata\db.properties
  • Set the contents of the file to be the following:

File Contents:

db.type=sqlserver
db.username=app_i2b2
db.password=[password you picked for app_i2b2]
db.driver=com.microsoft.sqlserver.jdbc.SQLServerDriver
db.url=jdbc:sqlserver://[your server IP address];database=i2b2workdata
db.project=demo
  • Open Powershell and cd to: C:\DATA\install\i2b2-data-1.7.12a.0001\i2b2-data-1.7.12a.0001\edu.harvard.i2b2.data\Release_1-7\NewInstall\workdata>
  • Run this command: c:\data\apache-ant\bin\ant.bat -f data_build.xml create_workdata_tables_release_1-7
  • Tables will then be built in the "i2b2workdata" database.
  • Run this to load database with demo data: c:\data\apache-ant\bin\ant.bat -f data_build.xml db_workdata_load_data

Last Steps! - Data Installation - Connecting the Web Services to the DBs

  • We installed the web services used by the web site earlier in the "Wildfly" steps. Now we need to point these web services to the database.
  • We will create/configure 4 XML files to make this happen.
  • After each file is saved you will see Wildfly make a copy of the file named like "filename.xml.deployed" (ex. crc-ds.xml.deployed). This is good. If you see something like "filename.xml.failed" instead, you can try to get details about what is going wrong from the files in directory C:\DATA\wildfly\standalone\log
  • Note that the files are similiar, but they are not the same

File 1:

  • Create a file called crc-ds.xml and put in folder C:\DATA\wildfly\standalone\deployments

  • Put the text below the file. Change the text in [square brackets] to be your specific values.

  • Note that the text in the "driver" node should match the version the file in your specific deployments directory, for example:

      <driver>mssql-jdbc-7.4.1.jre8.jar</driver>

crc-ds.xml File Contents:

<?xml version="1.0" encoding="UTF-8"?><datasources xmlns="http://www.jboss.org/ironjacamar/schema"><datasource jta="false" jndi-name="java:/CRCBootStrapDS" pool-name="CRCBootStrapDS" enabled="true" use-ccm="false"><connection-url>jdbc:sqlserver://[your IP address];database=i2b2hive</connection-url><driver-class>com.microsoft.sqlserver.jdbc.SQLServerDriver</driver-class><driver>mssql-jdbc-7.4.1.jre8.jar</driver><security><user-name>app_i2b2</user-name><password>[your password]</password></security><validation><valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnectionChecker"/><validate-on-match>false</validate-on-match><background-validation>true</background-validation><background-validation-millis>60000</background-validation-millis><use-fast-fail>true</use-fast-fail><check-valid-connection-sql>SELECT 1</check-valid-connection-sql></validation><statement><share-prepared-statements>false</share-prepared-statements></statement></datasource><datasource jta="false" jndi-name="java:/QueryToolDemoDS" pool-name="QueryToolDemoDS" enabled="true" use-ccm="false"><connection-url>jdbc:sqlserver://[your IP address];database=i2b2demodata</connection-url><driver-class>com.microsoft.sqlserver.jdbc.SQLServerDriver</driver-class><driver>mssql-jdbc-7.4.1.jre8.jar</driver><security><user-name>app_i2b2</user-name><password>[your password]</password></security><validation><valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnectionChecker"/><validate-on-match>false</validate-on-match><background-validation>true</background-validation><background-validation-millis>60000</background-validation-millis><use-fast-fail>true</use-fast-fail><check-valid-connection-sql>SELECT 1</check-valid-connection-sql></validation><statement><share-prepared-statements>false</share-prepared-statements></statement></datasource>
</datasources>

File 2:

  • Create a file called ont-ds.xml and put in folder C:\DATA\wildfly\standalone\deployments

  • Put the text below in the file. Change the text in [square brackets] to be your specific values.

  • Note that the text in the "driver" node should match the version the file in your specific deployments directory, for example:

      <driver>mssql-jdbc-7.4.1.jre8.jar</driver>

ont-ds.xml File Contents:

<?xml version="1.0" encoding="UTF-8"?><datasources xmlns="http://www.jboss.org/ironjacamar/schema"><datasource jta="false" jndi-name="java:/OntologyDemoDS"pool-name="OntologyDemoDS" enabled="true" use-ccm="false"><connection-url>jdbc:sqlserver://[your IP address];database=i2b2metadata</connection-url><driver-class>com.microsoft.sqlserver.jdbc.SQLServerDriver</driver-class><driver>mssql-jdbc-7.4.1.jre8.jar</driver><security><user-name>app_i2b2</user-name><password>[your password]</password></security><validation><valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnectionChecker"/><validate-on-match>false</validate-on-match><background-validation>true</background-validation><background-validation-millis>60000</background-validation-millis><use-fast-fail>true</use-fast-fail><check-valid-connection-sql>SELECT 1</check-valid-connection-sql></validation><statement><share-prepared-statements>false</share-prepared-statements></statement></datasource><datasource jta="false" jndi-name="java:/OntologyBootStrapDS"pool-name="OntologyBootStrapDS" enabled="true" use-ccm="false"><connection-url>jdbc:sqlserver://[your IP address];database=i2b2hive</connection-url><driver-class>com.microsoft.sqlserver.jdbc.SQLServerDriver</driver-class><driver>mssql-jdbc-7.4.1.jre8.jar</driver><security><user-name>app_i2b2</user-name><password>[your password]</password></security><validation><valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnectionChecker"/><validate-on-match>false</validate-on-match><background-validation>true</background-validation><background-validation-millis>60000</background-validation-millis><use-fast-fail>true</use-fast-fail><check-valid-connection-sql>SELECT 1</check-valid-connection-sql></validation><statement><share-prepared-statements>false</share-prepared-statements></statement></datasource>
</datasources>

File 3:

  • Create a file called pm-ds.xml and put in folder C:\DATA\wildfly\standalone\deployments

  • Put the text below in the file. Change the text in [square brackets] to be your specific values.

  • Note that the text in the "driver" node should match the version the file in your specific deployments directory, for example:

      <driver>mssql-jdbc-7.4.1.jre8.jar</driver>

pm-ds.xml File Contents:

<?xml version="1.0" encoding="UTF-8"?><datasources xmlns="http://www.jboss.org/ironjacamar/schema"><datasource jta="false" jndi-name="java:/PMBootStrapDS"pool-name="PMBootStrapDS" enabled="true" use-ccm="false"><connection-url>jdbc:sqlserver://[your IP address];database=i2b2pm</connection-url><driver-class>com.microsoft.sqlserver.jdbc.SQLServerDriver</driver-class><driver>mssql-jdbc-7.4.1.jre8.jar</driver><security><user-name>app_i2b2</user-name><password>[your password]</password></security><validation><valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnectionChecker"/><validate-on-match>false</validate-on-match><background-validation>true</background-validation><background-validation-millis>60000</background-validation-millis><use-fast-fail>true</use-fast-fail><check-valid-connection-sql>SELECT 1</check-valid-connection-sql></validation><statement><share-prepared-statements>false</share-prepared-statements></statement></datasource>
</datasources>

File 4:

  • Create a file called work-ds.xml and put in folder C:\DATA\wildfly\standalone\deployments

  • Put the text below in the file. Change the text in [square brackets] to be your specific values.

  • Note that the text in the "driver" node should match the version the file in your specific deployments directory, for example:

      <driver>mssql-jdbc-7.4.1.jre8.jar</driver>

work-ds.xml File Contents:

<?xml version="1.0" encoding="UTF-8"?><datasources xmlns="http://www.jboss.org/ironjacamar/schema"><datasource jta="false" jndi-name="java:/WorkplaceBootStrapDS"pool-name="WorkplaceBootStrapDS" enabled="true" use-ccm="false"><connection-url>jdbc:sqlserver://[your IP address];database=i2b2hive</connection-url><driver-class>com.microsoft.sqlserver.jdbc.SQLServerDriver</driver-class><driver>mssql-jdbc-7.4.1.jre8.jar</driver><security><user-name>app_i2b2</user-name><password>[your password]</password></security><validation><valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnectionChecker"/><validate-on-match>false</validate-on-match><background-validation>true</background-validation><background-validation-millis>60000</background-validation-millis><use-fast-fail>true</use-fast-fail><check-valid-connection-sql>SELECT 1</check-valid-connection-sql></validation><statement><share-prepared-statements>false</share-prepared-statements></statement></datasource><datasource jta="false" jndi-name="java:/WorkplaceDemoDS"pool-name="WorkplaceDemoDS" enabled="true" use-ccm="false"><connection-url>jdbc:sqlserver://[your IP address];database=i2b2workdata</connection-url><driver-class>com.microsoft.sqlserver.jdbc.SQLServerDriver</driver-class><driver>mssql-jdbc-7.4.1.jre8.jar</driver><security><user-name>app_i2b2</user-name><password>[your password]</password></security><validation><valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnectionChecker"/><validate-on-match>false</validate-on-match><background-validation>true</background-validation><background-validation-millis>60000</background-validation-millis><use-fast-fail>true</use-fast-fail><check-valid-connection-sql>SELECT 1</check-valid-connection-sql></validation><statement><share-prepared-statements>false</share-prepared-statements></statement></datasource>
</datasources>

Done!

  • Open a web browser on the server and go to http://localhost/webclient
  • You will get a login screen:
    • Login as user: demo, pwd: demouser to see the standard user view
    • Login as user: i2b2, pwd: demouser to see the admin user view