Anchor
_52j3c58b0474 _52j3c58b0474

WEB CLIENT HOSTING VIA APACHE

Anchor
_x1e492yw167w _x1e492yw167w

General Hosting Installation

In general, you will need to copy all the files and directories into the root hosting directory that you have configured for your web server software. The majority of the web client's files will be served directly by the web server. Certain functionality (primarily the proxy service and SAML-related services) are enabled using PHP script files. To work properly within Apache, you will need to configure the Apache service to execute the PHP scripts contained within the hosting directory. If you are using the NodeJS-based proxy server these things are self-contained.

Anchor
_lxpjrvnny9e2 _lxpjrvnny9e2

Requirement for a Proxy Service

The i2b2 server architecture hosts all i2b2 services within a Java application server JVM. No services within the i2b2 hive exist to host the HTML, CSS and Javascript files that make up the i2b2 web client. To accomplish this the web client's files must be hosted somewhere. Because of the "same-origin" security rule that is baked into all web browsers, the i2b2 web client is not able to directly connect to the different URLs which expose the i2b2 services. In order to accomplish this a "proxy service" must be operated within the web server environment which is hosting the i2b2 web client's code. When hosting the web client using Apache the proxy service is manifested via the proxy.php script file. If you are hosting the web client using the NodeJS-based proxy server the proxy service is self-contained within its code.

Anchor
_g5li0j19jn72 _g5li0j19jn72

Requirement for Whitelist

Whether hosting via NodeJS or Apache, the proxy service uses a whitelist to prevent it from being used in relay attacks to subvert network security. A whitelist is a list of domain names or IP addresses that the proxy will allow requests to be forwarded to.

Anchor
_l683uirkf8b9 _l683uirkf8b9

Whitelist in Apache

To edit the whitelist when the web client is hosted in Apache you will need to edit the values within the proxy.php file. At the top of the file will be a PHP variable called $WHITELIST which will contain an array of URLs. You will need to enter the protocol, hostname and port (if any) for all i2b2 hive services that the web client will need access to. You can see an example of a proper whitelist configuration below:

$WHITELIST = array(
 "http://services.i2b2.org

...

In general, you will need to copy all the files and directories into the root hosting directory that you have configured for your web server software. The majority of the web client's files will be served directly by the web server. Certain functionality (primarily the proxy service and SAML-related services) are enabled using PHP script files. To work properly within Apache, you will need to configure the Apache service to execute the PHP scripts contained within the hosting directory. If you are using the NodeJS-based proxy server these things are self-contained.

...

Whether hosting via NodeJS or Apache, the proxy service uses a whitelist to prevent it from being used in relay attacks to subvert network security. A whitelist is a list of domain names or IP addresses that the proxy will allow requests to be forwarded to.

...

To edit the whitelist when the web client is hosted in Apache you will need to edit the values within the proxy.php file. At the top of the file will be a PHP variable called $WHITELIST which will contain an array of URLs. You will need to enter the protocol, hostname and port (if any) for all i2b2 hive services that the web client will need access to. You can see an example of a proper whitelist configuration below:

$WHITELIST = array(
 "http://services.i2b2.org",
 "http://127.0.0.1:9090",
 "http://127.0.0.1:8080",
 "http://127.0.0.1",
 "http://localhost:8080",
 "http://localhost127.0.0.1:9090",
 "http://localhost"
 );127.0.0.1:8080",
 "http://127.0.0.1",
 "http://localhost:8080",
 "http://localhost:9090",
 "http://localhost"
 );

Anchor
_zdec521nyfc5 _zdec521nyfc5
Anchor
_zdec521nyfc5 _zdec521nyfc5

Blacklist in Apache

In the PHP proxy service file (proxy.php) you will also have the ability to set blacklist entries. These entries will prevent proxying of any requests whose URLs begin with any of the values listed in the $BLACKLIST variable. You can see an example of a proper blacklist configuration below:

...

//==========================================================================//
// THESE ARE ALL THE CELLS THAT ARE INSTALLED ONTO THE SERVER
i2b2.hive.tempCellsList = [
     { code: "PM", ...},
     { code: "ONT", ...},
     { code: "CRC", ...},
     { code: "WORK", ...},
     { code: "PLUGINMGR", ...},
     { code: "Dem1Set",
       forceLoading: true,
       forceConfigMsg: { params: [] },
       roles: [ "DATA_LDS", "DATA_DEID", "DATA_PROT" ],
       forceDir: "cells/plugins/standard"
     },
     { code: "ExportXLS",
       forceLoading: true,
       forceConfigMsg: { params: [] },
       roles: [ "DATA_LDS", "DATA_DEID", "DATA_PROT" ],
       forceDir: "cells/plugins/community"
     }
  ];
//========================================================================================//

Each plugin will have a configuration object within the defined i2b2.hive.tempCellsList array variable. The meaning of the configuration object's attributes is as follows:
The code attribute is the name of the plugin as well as the name of the directory containing the plugin's code and assets.
The forceLoading attribute notifies the legacy i2b2 plugin execution environment that the plugin should be loaded upon environment creation. For the plugin to work correctly this must be set to true.
The forceConfigMsg attribute contains configuration information that is passed to the plugin. It is an object which must contain an array named params.
The roles attribute contains the roles which can use the plugin. The rolls are as follows: DATA_OBFSC for Obfuscated, DATA_AGG for Aggregated, DATA_LDS for Limited Data Set, DATA_DEID for De-identified Data, DATA_PROT for Protected.
The forceDir attribute points to the parent directory that the plugin's directory exists within.

...

//

Each plugin will have a configuration object within the defined i2b2.hive.tempCellsList array variable. The meaning of the configuration object's attributes is as follows:
The code attribute is the name of the plugin as well as the name of the directory containing the plugin's code and assets.
The forceLoading attribute notifies the legacy i2b2 plugin execution environment that the plugin should be loaded upon environment creation. For the plugin to work correctly this must be set to true.
The forceConfigMsg attribute contains configuration information that is passed to the plugin. It is an object which must contain an array named params.
The roles attribute contains the roles which can use the plugin. The rolls are as follows: DATA_OBFSC for Obfuscated, DATA_AGG for Aggregated, DATA_LDS for Limited Data Set, DATA_DEID for De-identified Data, DATA_PROT for Protected.
The forceDir attribute points to the parent directory that the plugin's directory exists within.

Anchor
_g870cp37imp _g870cp37imp

MODIFYING OF LOGIN SCREEN

Anchor
_lujyrxefzh4d _lujyrxefzh4d

Set Address for Legacy Client Link

By default the login screen contains a link for users to access the legacy web client. By default it has no address set. If you are still running the legacy web client then you should enter the URL that it is hosted at. If you are not hosting the legacy web client then remove the link from the template. The HTML template file is located at /js-i2b2/cells/PM/assets/login.html
For more information on changing the HTML and/or the look and feel of the new web client refer to the document titled "Applying Branding Styles to the I2B2 Web Client".

Anchor
_wnib6yo2ddxr _wnib6yo2ddxr

Other Suggested Readings

• For troubleshooting tips, see i2b2 Usage Community FAQ
• Upgrade Guide for i2b2 Release v1.8
• Applying Branding Styles to the i2b2 Release v1.8+
• Plugin Development for i2b2 Release v1.8+

Anchor
_66xfw7awz2lp _66xfw7awz2lp

i2b2 Web Client Repository

https://github.com/hms-dbmi/i2b2v2-webclient

Anchor
_rjshgma5rkyz _rjshgma5rkyz

i2b2 Web Proxy Server Repository

https://github.com/hms-dbmi/i2b2-webclient-proxy

Anchor
troubleshooting troubleshooting

Troubleshooting

Troubleshooting Odd Characters in Query Results

If obfuscated users are encountering an unusual "A-hat" character (Â) in their search results, it's likely due to a character encoding issue within your Apache server. To resolve this, you'll need to enable UTF-8 encoding.

Solution:

1. Locate the charset.conf file:

   • This file is typically located in your Apache configuration directory. Its exact path may vary depending on your server setup. Common locations include:
     • /etc/apache2/conf/charset.conf
     • /etc/httpd/conf/charset.conf

2. Uncomment the UTF-8 line:

   • Open the charset.conf file using a text editor.
   • Find the line that reads:

     AddDefaultCharset UTF-8
     

   • If this line is commented out (preceded by a # symbol), remove the # to uncomment it. This will instruct Apache to use UTF-8 as the default character set.

3. Restart Apache:

   • After making the change, restart your Apache server to apply the configuration. The specific command to restart Apache will depend on your operating system and server setup. Common commands include:
     • Linux: sudo systemctl restart apache2 or sudo service apache2 restart
     • macOS: sudo apachectl restart

...

• Upgrade Guide for i2b2 Release v1.8
• Applying Branding Styles to the i2b2 Release v1.8+
• Plugin Development for i2b2 Release v1.8+

...

https://github.com/hms-dbmi/i2b2v2-webclient

...

Anchor
_qrvsxe4i2xo6 _qrvsxe4i2xo6

Acknowledgments

...