MongoChemWeb

The following steps are required for the deployment of MongoChemWeb:

Building VTK with web support
VTK needs to be configured with the Web group enabled, and Python wrapping turned on.

Building with Mesa
For offscreen rendering you will need to build OSMesa. The Mesa 10.0.3 OSMesa Gallium llvmpipe state-tracker is the preferred Mesa back-end renderer for VTK. The following shows how to configure it with system installed LLVM. Our strategy is to configure Mesa with the minimal number of options needed for OSMesa. This greatly simplifies the build, as many of the other drivers/renderers depend on X11 or other libraries. The following set of options are from the Mesa v10.0.3 release. Older or newer releases may require slightly different options. Consult ./configure --help for the details.

Some explanation of these options: DEFAULT_SOFTWARE_DEPTH_BITS=31 This sets the internal depth buffer precision for the OSMesa rendering context. In our experience, this is necessary to avoid z-buffer fighting during parallel rendering. Note that we have used this in-place of --with-osmesa-bits=32, which sets both depth buffer and color buffers to 32 bit precision. Because of a bug in Mesa, this introduces over 80 ctest regression failures in VTK related to line drawing. --enable-texture-float Floating point textures are disabled by default due to patent restrictions. They must be enabled for many advanced VTK algorithms. To use Mesa with VTK you will need to set the following options before when configuring VTK:

$ cmake -DVTK_Group_Web:BOOL=ON -DVTK_WRAP_PYTHON:BOOL=ON \ -DVTK_USE_X:BOOL=OFF -DVTK_OPENGL_HAS_OSMESA:BOOL=ON \ -DOPENGL_gl_LIBRARY:FILEPATH="" -DOPENGL_glu_LIBRARY:FILEPATH="" \ -DOPENGL_INCLUDE_DIR:PATH=/opt/mesa/10.0.3/llvmpipe/include \ -DOSMESA_INCLUDE_DIR:PATH=/opt/mesa/10.0.3/llvmpipe/include \ -DOSMESA_LIBRARY:FILEPATH=/opt/mesa/10.0.3/llvmpipe/lib/libOSMesa.so \ -DCMAKE_BUILD_TYPE:STRING=Release ../VTK

Building OpenChemistry
Clone the OpenChemistry repository containg the CJSON to CML conversion executable.

Now follow instruction to build the OpenChemistry project starting at the Build step.

Apache compile, install and configuration
Apache 2.4.7 has support for rewriting websocket URLs so can be used to proxy VTK web connections, this is the easiest way to configure Apache. However, if you are using a older version of Apache you can use the custom proxy code based on mod_python.

Build / Installation
Unless Apache 2.4.7 is packaged your distribution you will need to compile from source.

Obtain the necessary source tarballs. You will need httpd source, as well as apr and apr-util sources.

Now unpack everything in the right places.

Now configure and build.

Configuration
Add a virtual host to the httpd-vhosts.conf file, which will be located in /usr/local/apache2/conf/extra/.

Be sure to update the ProxyPass paths statements to match your configuration. For example if tangelo is going to to be run as user bob. Then / should be forwarded to http://localhost:8080/~bob/mongochemweb/

Include this virtual host in the main httpd configuration file. Find the following line in /usr/local/apache2/conf/httpd.conf and uncomment it.

Find the following lines in the httpd.conf file and uncomment them in order to load some necessary modules.

We need to ensure the mapping file exists before starting Apache. Issue the following command to this.

Start the httpd daemon.

Build / Installation
Old versions of Apache are likely to packaged for your distribution for example Apache 2.2 can be install on Ubuntu LTS using the following command.

Once Apache is installed the mod_python Apache module needs to be installed ( this can be done on Ubuntu) by issuing the following command.

Ensure that the correct link was create to load the module.

This should give:

Autobahn is needed by the proxy to make websocket connections to the backend. It can be install using pip.

The pywebsocket module is required to listen for incoming websocket. It is installed by the following.

Websocket proxy configuration
The websocket proxy code now needs to be downloaded and configured.

Update proxy.json with the following values

"loggingConfiguration": "/var/websocket_proxy/logging.json" "sessionMappingFile": "/tmp/session.map"

The proxy configuration needs to be in home directory of the user who runs Apache. This is usually /var/www.

The following lines need to be added to /etc/apache2/apache2.conf to configure the mod_python module

You will also need to create a site configuration file in /etc/apache2/sites-available/, so create a file called mongochemweb contain the following configuration:

You then need to create symlink in the enabled sites directory

Configuring a process launcher
A launcher is used to start python processes that provide the visualization pipeline for a MongoChemWeb session. If you are using Apache 2.4.7 you should use the Python launcher that comes with VTK, otherwise you will need to use the Jetty based session manager that will do the same job.

Using the VTK web launcher
The launcher can be found in the VTK source tree:

/Web/Python/launcher.py

The launcher takes a configuration file specifies the parameters to use when launching the vtkpython processes.

Create a file launcher.conf containing the following JSON specification:

To start the launcher issue the following command:

$ python /Web/Python/launcher.py launcher.conf

Go to testing launcher to check that things are configured correctly.

Using the Jetty Session Manager
If you are using Apache 2.2.X you will need to use the Jetty session manager. You will need to install Java (on Ubuntu) this can be done using the following command:

How you need to download and configure the session manager.

You will need to update the hostname and path to the mongochemweb directory.

The session manager can now be started using the following command:wil

Testing your launcher configuration
Regardless of the launcher you are using you can use the following procedure to test that it is responsing to requests.

To test the launcher use curl issue the following request.

The launcher should response with:

Now check that the launcher requests are successfully proxies through Apache by issuing the same request to the external URL.

You should see the same result

Tangelo installation and configuration
Install tangelo by issuing the following command:

Now start tangelo by issuing the following command:

MongoChemWeb app installation and configuration
The MongoChemWeb app requires two Python modules which can be installed as follows:

We now need to setup the application that will be run by tangelo. As the user who will used to run tangelo issue the following commands:

The configuration on mongochemweb needs to be adjust to machine the installation. The configuration file an be found in mongochemweb/config/

chemical.json
server - This is the hostname of the mongo database that MongoChemWeb will use to search for molecular data. The data needs to conform to this schema

db - This is the database on the server to use

heliumUrl - Is the URL that the Helium similarity search can be found (optional)

conversion.json
baseUrl - This is the URL as which the MongoChemWeb app is be served by tangelo cjsonToCmlPath - This is the path to executable used to convert from CJSON to CML which we compiled earilier.

Now we need to create a symlink to ensure that the VTK web client can be found by tangelo.

Once the configuration is updated you should restart Tangelo

You should now be able point your browser at http://localhost or http::// and the application should load up.

Troubleshooting
There are three places to look for errors:

If not process is found check your launcher configuration and check /tmp for logs.
 * The Apache logs /usr/local/apache2/logs or /var/log/apache2. This is the place to look for error related to proxying and rewrite rules.
 * The Tangelo log //.config/tangelo/tangelo.log. This is the place to log for application related errors.
 * When a vtkpython process is started by the launcher the stderr and stdout are redirected to a file that will appear in /tmp/ .txt if you change the launcher configuration the directory may be different. This is the place to look for errors related to visualization pipeline.
 * If no 3D view is display the first thing to do it check that the vtkpython processes are be launched