Operator Instructions

WebDC3 web interface generator

Here we outline what you may need to do to get the web interface up and running on your site. Things may be different for your site depending on your operating system, web server, network policies and so on.

The web interface mainly uses JavaScript for presentation, with Python used to provide underlying services.

Note

WebDC3 has a modular design. Here goes something about the modules:

  • presentation
  • events
  • stations
  • requests
  • maps
  • console

See the Developer Notes for more details about the modules.

Presentation

The design adopted for the implementation uses Ajax queries to load the individual page blocks. The final page assembles those blocks. You (a web site operator) have complete freedom to build your own page layout from the basic supplied blocks. The basic blocks are:

  1. Event Search Control block
  2. Station Search Control block
  3. Mapping Control block (plot events and stations)
  4. Request Control block
  5. Submitting block
  6. Status Control block
  7. Status Results block
  8. Console block

Further blocks can be implemented and later integrated into the current architecture design. Since each block is a self-contained unit we believe they will fit pretty well in any CMS or existing web pages at EIDA nodes, or even the EIDA portal at ODC.

Python and JavaScript (JS)

The complete interface needs a Python back end running, using the WSGI interface. In the Apache web server this is implemented in mod_wsgi. The back end uses the SeisComP seiscomp3 Python libraries for distance and travel time computation, configuration, and logging. The Python back end is responsible for:

  1. Fetch events information for the presentation layer (JavaScript) from different web services or databases.
  2. Fetch NSLC (network-station-location-channel, i.e. inventory) information to the presentation layer from an Arclink server.
  3. Place requests to one or many Arclink servers.
  4. Send e-mail to the user about her/his requests. FIXME: Do we still do that? Should we
  5. Fetch the status information from the Arclink server and send it to the presentation layer.

and a JavaScript set of modules that will contact the back end services and render the page on the user’s browser client and control the work flows on the page.

../_images/wi-overview2.png

Also built in the back end there is an option to send configuration variables as key-value pairs from the server back end to the client JavaScript layer. These variables are initially defined in a configuration file on the server. They are fetched by the JavaScript layer and any module on the client has access to those variables that helps to guide the JavaScript in rendering the page. One clear example of such variables is the Web Mapping Service (WMS) address (URL) that is used by the Mapping control block. For the event control the default values for the magnitude filters and depth filters are also obtained from the server through this mechanism. (See Configuration options for webinterface for details.)

Basic Page Set

Together with this package we are also supplying a set of static pages (HTML files) that can be used as a reference on how to use the package to build your customized interface. During the development of the modules we try not to force any possible work flow. See the content of the examples directory.

The basic page set is composed of two pages, one for making requests and one for checking status information. The request page use demonstrate how to use the modules numbered as 1, 2, 3, 4, 5 and 6 (block list above) and the status page uses blocks numbers 6 and 7.

Note

Make a table. Add screen shots. TODO

The customization of the pages should be done completely in HTML, using the ‘class’ and ‘id’ attributes of HTML entities. The basic idea is that each block renders itself inside a certain ‘<div>’ element, identified by a special ‘id’. Also some blocks can accept options that are passed through the ‘class’ attribute on the ‘<div>’. For example, the apparently empty element:

<div id='wi-StationSearchControl'></div>

would in the end be filled by the StationSearchControl block. And code like this:

<div id='wi-StationSearchControl' class='nosensor'></div>

would load the the StationSearchControl block, but the class nosensor would inhibit the sensor selection dialog to be present allowing each node to further customize its interface.

Note

Adding class=’nosensor’ doesn’t work, Aug 31 2013.

Also, since HTML allows multiple classes to the same container options related to formatting and option for the block control would coexist on the same ‘<div>’. Furthermore on the customization part of the operator manual [REF] you can find all the special ‘id’ and class options that are accepted by each control block to be associated to a certain ‘id’.

The Loader

To build the interface on your basic static HTML page all you need to do is to load the ‘loader.js’ script from the server into your page. When this file is executed in the client, it loads the other required JavaScript modules, guaranteeing the correct load order, as one module can depend on others.

If no ‘<div>’ with the ‘id’ of a particular module is not found on the page then that module will be disabled.

Requirements

  • SeisComP(reg) 3 provides useful functions for configuration, geometry, travel time computation. If you use the update-metadata.sh script, you will need arclink_fetch, either included in the SeisComP distribution, or standalone [http://www.seiscomp3.org/wiki/doc/applications/arclink_fetch].
  • Seiscomp Python library ($SEISCOMP_ROOT/lib/python/seiscomp), including a recent version of manager.py (SeisComP 3 release >= 2013.200; there is a temporary version with this release in the tools directory, which you can use to replace your installed version in $SEISCOMP_ROOT/lib/python/seiscomp/arclink).
  • JavaScript libraries: jquery-base, jquery-ui [https://jquery.org/]
  • OpenLayers. [http://www.openlayers.org/]
  • Python, mod_wsgi (if using Apache). Also Python libraries for libxslt and libxml.
  • Finally, users’ web browsers need to run JavaScript.
  • The update-metadata.sh script uses wget.

Download

Download the tar file / source from the GEOFON web page at http://geofon.gfz-potsdam.de/software. [Eventually it may be included in the SeisComP distribution.]

Note

Nightly builds can be downloaded from Bitbucket at [URL TBD].

Untar into a suitable directory visible to the web server, such as /var/www/webinterface:

cd /var/www/webinterface
tar xvzf /path/to/tarfile.tgz
This location will depend on the location of the root (in the file system)
for your web server.

Installation on Apache

To deploy the WebDC3 web interface on an Apache2 web server using mod_wsgi:

  1. Unpack the files into the chosen directory. (See Download above.) In these instructions we assume this directory is /var/www/webinterface.

  2. Enable mod_wsgi. For openSUSE, add ‘wsgi’ to the list of modules in the APACHE_MODULES variable in /etc/sysconfig/apache2:

    APACHE_MODULES+=" python wsgi"
    

    and restart Apache. You should now see the following line in your configuration (in /etc/apache2/sysconfig.d/loadmodule.conf for openSUSE):

    LoadModule wsgi_module   /usr/lib64/apache2/mod_wsgi.so

    You can also look at the output from a2enmod -l - you should see wsgi listed.

    For Ubuntu/Mint, you can enable the module with the command:

    sudo a2enmod wsgi

    and you can restart apache with:

    sudo service apache2 stop
    sudo service apache2 start

    If the module was added succesfully you should see the following two links in /etc/apache2/mods-enable:

    wsgi.conf -> ../mods-available/wsgi.conf
    wsgi.load -> ../mods-available/wsgi.load

    For any distribution there may be a message like this in Apache’s error_log file, showing that mod_wsgi was loaded:

    [Tue Jul 16 14:24:32 2013] [notice] Apache/2.2.17 (Linux/SUSE)
    PHP/5.3.5 mod_python/3.3.1 Python/2.7 mod_wsgi/3.3 configured
     -- resuming normal operations
  3. Add the following lines to a new file, conf.d/webinterface.conf, or in default-server.conf, or in the configuration for your virtual host:

    WSGIScriptAlias /webinterface/wsgi /var/www/webinterface/wsgi/webdc3.wsgi
       <Directory /var/www/webinterface/wsgi/>
           Order allow,deny
           Allow from all
       </Directory>

    Change /var/www/webinterface to suit your own web server’s needs. You may also need to add a section like:

    <Directory /var/www/webinterface/>
        Order allow,deny
        Allow from all
    </Directory>
  4. Set environment for Apache: Apache needs the “SeisComP” environment variables set when it starts. The seiscomp3 bin and man directories aren’t needed. For OpenSUSE, add the following lines, which are provided by seiscomp print env, to /etc/sysconfig/apache2:

    SEISCOMP_ROOT=/home/sysop/seiscomp3
    LD_LIBRARY_PATH=/home/sysop/seiscomp3/lib
    PYTHONPATH=/home/sysop/seiscomp3/lib/python

    (Omit “export” and variable references, those will not work.)

    For Debian and Ubuntu/Mint add the following lines to the /etc/apache2/envvars file:

    # Make SeisComP3 available for webinterface:
    export SEISCOMP_ROOT=/home/sysop/seiscomp3/
    export LD_LIBRARY_PATH=/home/sysop/seiscomp3/lib:$LD_LIBRARY_PATH
    export PYTHONPATH=/home/sysop/seiscomp3/lib/python:$PYTHONPATH
  5. Change to the installation directory and fix the path which is added in wsgi/webdc3.wsgi:

    sys.path.insert(0, '/var/www/webinterface/wsgi/')
    
  6. Copy webinterface.cfg.sample to e.g. $SEISCOMP_ROOT/etc/webinterface.cfg, or make a symbolic link from there to the webinterface directory:

    cp wsgi/webinterface.cfg.sample wsgi/webinterface.cfg
    cd $SEISCOMP_ROOT/etc
    ln -s /var/www/webinterface/wsgi/webinterface.cfg webinterface.cfg
  7. Edit webinterface.cfg and be sure to configure correctly the SERVER_FOLDER and arclink.address variables. This is discussed under “Configuration Options” below.

  8. Copy one of the top-level example pages to index.html and customise the site as you wish.:

    cd {top directory}
    cp examples/generic/*.html .

    Or:

    cp examples/basic/index.html index.html

    Or:

    cp examples/webdc2012/webdc.html index.html

    Or even (but don’t adopt GFZ’s corporate design, unless you’re at GFZ):

    cp examples/webdc3/*.html .
  9. Start/restart the web server e.g. as root. In OpenSUSE:

    # /etc/init.d/apache2 configtest
    # /etc/init.d/apache2 restart
    

    or in Ubuntu/Mint

    # sudo service apache2 reload
    # sudo service apache2 stop
    # sudo service apache2 start
    
  10. Check that the value of arclink.address is properly set in webinterface.cfg. For instance:

    arclink.address=eida.gfz-potsdam.de:18002

    Then, get initial metadata in the data directory by running the update-metadata.sh script in that directory.:

    # cd /var/www/webinterface/data
    # ./update-metadata.sh
    
  11. It is important to check the permissions of the data directory and the files in it, as webinterface caches metadata there. For instance, in some distributions Apache is run by the www-data user, which belongs to a group with the same name (www-data). The data directory should have read-write permission for the user running Apache and the user who will do the regular metadata updates (see crontab configuration in the last point of this instruction list). The system will also try to create and write temporary information in this directory, but it will still work even if this cannot be done.

    Warning

    Wrong configuration in the permissions of the data directory could diminish the performance of the system.

    One possible configuration would be to install the system as a user (for instance, sysop), who will run the crontab update, with the data directory writable by the group of the user running Apache (www-data in Ubuntu/Mint).:

    # cd {top directory}
    # sudo chown -R sysop.www-data .
    # sudo chmod -R g+w data
    
  12. Visit <http://localhost/webinterface>. You should see the front page.

  13. Arrange for regular updates of the metadata in the data directory. Something like the following lines will be needed in your crontab:

    # Daily metadata update for webinterface:
    52 03 * * * /var/www/webinterface/data/update-metadata.sh

Installation problems

If you see the basic web interface page, but none of the controls load, you may not have the underlying services running correctly. Look in your web server log files (e.g. for Apache: access_log and error_log) for clues.

If you visit http://localhost/webinterface/wsgi/loader (or similar) on your machine you should see the definitions that the JavaScript needs to get started:

var eidaJSSource='/webinterface/js';
var eidaCSSSource='/webinterface/css';
var eidaServiceRoot='/webinterface/wsgi';
var eidaDebug=false;
$(document).ready(function() { $.getScript(eidaJSSource + '/loader.js') });

If these definitions are not found, then you won’t have any controls. If they do show up, check that the URL paths look correct.

You should also be able to visit the “web service” URLs in your browser e.g. going to:

http://localhost/webinterface/wsgi/event/catalogs

should show you something like this:

{"geofon": {"description": "GFZ (eqinfo)", "hasDepth": true, "hasDate":
true, "hasRectangle": true, ...

Configuration options

Configuration follows the SeisComP 3 pattern. Configuration is read from files using a ‘dotted’ notation e.g.:

js.wms.server = "http://myserver.org/wms/vmap0"

See the SeisComP documentation [http://www.seiscomp.org/] for details. Configuration variables beginning with “js” are loaded by the JavaScript loader and made available to scripts in the client’s web browser. Other variables are only available to the Python-based back end modules.

The following files are sought, and if present, their configuration information is loaded, in the order shown:

  1. $SC3ROOT/etc/defaults/global.cfg
  2. $SC3ROOT/etc/defaults/webinterface.cfg
  3. $SC3ROOT/etc/global.cfg
  4. $SC3ROOT/etc/webinterface.cfg
  5. $HOME/.seiscomp3/global.cfg
  6. $HOME/.seiscomp3/webinterface.cfg

Remember that $HOME is for the user running webinterface, which might be the same user as runs your web server. It may be helpful to make a symbolic link from one of these locations to a file in the webinterface directory e.g.:

cd /var/www/.seiscomp3 ; ln -s /path/to/webinterface/wsgi/webinterface.cfg .

At a minimum, you will need to

  1. set arclink.address to point to your Arclink server,
  2. set SERVER_FOLDER to the top directory of your webinterface installation

to something suitable for your site. Other options should be suitable for getting started. You may also wish to adjust the selection of event services. For full details of all configuration options, see full-config-options.

General options

  • Mail server details. WebDC3 sends e-mail to the address given in the Arclink request confirming that the request has been submitted. FIXME
  • Temporary files. WebDC3 creates files in Python’s default temporary directory. This is typically /tmp. This location cannot yet be overridden in webinterface, but you may be able to change it by setting TMPDIR in WebDC3’s environment.

Metadata options

  • List of sensor types. This list is displayed in the Stations/Streams tool and can be configured by modifying the variable self.senstypes in the file wsgi/inventorycache.py. The values can be also grouped but must be separated with a space. For instance, VBB BB will select the streams that are either VBB or BB, while OBS will select only the ones that match this value.
  • Arclink nodes configuration file: this is an XML file [or a URL?]. This option enables you to give a list of Arclink servers which can be checked for status of requests. Generally this list should be those servers which are included in the routing table provided by your Arclink server. For an EIDA node, this should be the EIDA master table.

Events options

FIXME: See options configuration section

  • Event Search Control options:

    js.events.magnitudes.minimum = 3.0
    js.events.depth.minimum = 0
    js.events.depth.maximum = 1000
    js.events.coordinates.north = 90
    js.events.coordinates.south = -90
    js.events.coordinates.west = -180
    js.events.coordinates.east = 180
    
  • Event service configuration options:

    event.[list of services]
    event.names.lookupIfEmpty = True
    event.names.lookupIfGiven = False

Customisation

You may safely modify the following to suit your web site needs:

  • webinterface.cfg - this was described above. (Location: where SeisComP looks for configuration files.)

  • index.html template document. The template must do the following:

    • Make sure jquery gets loaded e.g.:

      <script src="tools/jquery/jquery-1.9.1.js"></script>
      <link rel="stylesheet" href="css/smoothness/jquery-ui.css" />
      <link rel="stylesheet" href="css/smoothness/jquery.ui.theme.css" />
      <script src="tools/jquery/jquery-ui.js"></script>
      <script src="tools/jquery/jquery.cookie.js"></script>
    • Make sure OpenLayers gets loaded:

      <script src="tools/openlayers/OpenLayers.js"></script>
    • Load the JavaScript loader:

      <script src="loadme.js" type="text/javascript"></script>

    The template should contain “<div>” elements for the JavaScript controls. They should be left empty in the template because their content will be filled by the controls running in the client’s brower. The following controls are available:

    <div id="wi-Console" class="consoleframe"></div>
    <div id="wi-StatusListControl" class="frame"></div>
    <div id="wi-StatusQueryControl" class="frame"></div>
    <div id="wi-StatusFullControl" class="statusframe"></div>
    <div id="wi-EventSearchControl" class="frame"></div>
    <div id="wi-StationSearchControl" class="frame"></div>
    <div id="wi-SubmitControl" class="frame"></div>
    <div id="wi-MappingControl" class="frame"></div>
    <div id="wi-RequestManagerControl" class="frame"></div>

    Do not remove the footer text, “Web Interface developed by Helmholtz-Zentrum Potsdam - Deutsches GeoForschungsZentrum GFZ for EIDA, 2013”, which should remain visible to all visitors to the page.

  • css/sample.css - Cascading Style Sheet file.

Maintenance

There may be some temporary files to clean up from time to time. These should be in Python’s default temporary directory e.g. /tmp.

Metadata may need updating after changes in Arclink inventory - you can safely run the update-metadata.sh script at any time to do that. Webinterface creates a processed version of the Arclink XML, but this will be automatically updated each time webinterface notices a new inventory XML file.

Upgrade

At this stage, it’s best to back up and then remove the old installation first.:

cd /var/www ; mv webinterface webinterface.old

Then reinstall from scratch, as in the installation instructions. Your web server configuration should need no modification. At Steps 4-6, re-use your previous versions of webdc2.wsgi and webinterface.cfg:

cp ../webinterface.old/wsgi/webdc2.wsgi wsgi/webdc3.wsgi
cp ../webinterface.old/wsgi/webinterface.cfg wsgi/webinterface.cfg