METAMOD Configuration

Introduction

Each METAMOD application needs a configuration directory where specific properties for the application are decribed. These properties will include:

The application configuration directory contains a very important file, the master_config.txt file. This file governs how METAMOD will run.

Example app

The EXAMPLE application that is included in this source tree (app/example) can be used to test the software. The following steps describes how to do this. Copy the app/example directory to somewhere local, preferably renaming it to whatever your METAMOD application is called. Then you are ready to edit the master configuration file.

  $ cp -r /opt/metno-metamod-2.13/app/example .
  $ mv example myapp

Then edit myapp/master_config.txt as needed.

The master_config.txt file

Several variables in this file must be adjusted according to the local computer environment. The most important are:

APPLICATION_ID

Each application delivering data to a database (an application with the METAMODUPLOAD, METAMODHARVEST and/or the METAMODQUEST module) must have a short name (typical an acronym) that uniquely identify the application for the database. Only upper case letters and numbers are allowed.

For local testing, set APPLICATION_USER to your own login.

SERVER

The server name on which the software should run (something like mycomputer.mydomain.com).

ADMIN_DOMAIN

This will typically be the domain found in the SERVER variable (like mydomain.com).

BASE_PART_OF_EXTERNAL_URL

This is the initial part of URLs that external links to the web applications are to use. It will typically be http://mycomputer.mydomain.com or http://mycomputer.mydomain.com:8080 if you are using an unusual port (note: not to be confused with the Catalyst port - usually 3000).

LOCAL_URL

Appended to BASE_PART_OF_EXTERNAL_URL, this represents the top URL for the web applications. URLs for the individual applications are constructed by appending directory names for each of the applications to this top URL.

WEBRUN_DIRECTORY

The top directory for runtime files, which also contain the XML archive.

PG_HOST

Hostname for the PostgreSQL database server. Default is localhost, in which case you should use sockets instead of TCP/IP (set PG_CONNECTSTRING_SHELL to blank).

DATABASE_NAME

Name of the PostgreSQL metadata database

USERBASE_NAME

Name of the PostgreSQL user database

PG_ADMIN_USER
PG_ADMIN_USER_PASSWORD

PG_ADMIN_USER is the PostgreSQL user who may freely create, modify and delete the metadata database (default "admin")

PG_WEB_USER
PG_WEB_USER_PASSWORD

PG_WEB_USER is a PostgreSQL user who may read/write data in the metadata database (default "webuser")

OPENDAP_DIRECTORY

The top directory of the data repository. This directory is assumed to be accessible through an OPeNDAP server (usually TDS/THREDDS) which has to be installed as a separate package (not part of METAMOD 2.x). If no OPeNDAP server is installed, some of the METAMOD 2.x software will not work. For example, links to OPeNDAP presentation of data files set up automatically by the UPLOAD module will not work.

OPENDAP_URL

The URL used to access the data file directory (top level). If no OPeNDAP server is installed, use an URL for HTTP download.

OPERATOR_EMAIL

E-mail address for the person responsible for operating the METAMOD 2.x installation.

SMTP_RELAY

If you wish to send email via an external MTA, enter the qualified hostname here. Otherwise it is assumed you are running a local (sendmail-compatible) MTA which is configured correctly (firewall will often block this). See Deploying a METAMOD application

The following variables are used to select the modules that will comprise the application. Whereas they previously indicated the absolute path of the source directory for each module, they are now only used as booleans (where any non-empty string means true).

    METAMODBASE_DIRECTORY
    METAMODUPLOAD_DIRECTORY
    METAMODPMH_DIRECTORY
    METAMODHARVEST_DIRECTORY
    METAMODTHREDDS_DIRECTORY

If any of these variables are missing, the corresponding module will not be part of the application.

Configuration defaults

A complete inventory of the variables that could be part of the master_config.txt file is found in the app/default/default_config.txt file in the installation directory. This also lists default values wherever applicable.

Config file format

The master_config.txt file (and the default and example versions of this file) contain lines as follows:

    VARNAME = VALUE

VARNAME must start from the first character on the line, and be all uppercase letters [A-Z], underscore or digits. Any number of white space characters may separate VARNAME and '=', and also '=' and VALUE. VALUE starts with the first non-whitespace character and ends with the last non-whitespace character on the line.

Additional lines may be appended to VALUE immediately after the initial "VARNAME = ..." line. Such lines must start with a space character. No whitespace are removed from such appended lines.

Multi-line directives may also be used to construct key-value-pair lists. In this case the first column contains the key and the rest a value (or list of value). Value containing spaces can be inclosed in quotes (single or double):

  WMS_PROJECTIONS =
      EPSG:32661      'WGS 84 / UPS North'
      EPSG:32761      'WGS 84 / UPS South'

VALUEs may be empty, which sometimes indicate that some aspect of the software is turned off. An empty value is indicated by having no characters (or only whitespace characters) after the '=' character.

In addition, comment lines, starting with '#', may be found. Blank lines are ignored (apart from terminating a multi-line directive).

In the source files, all text strings like [==VARNAME==] will be substituted with the corresponding value at runtime when the variable is accessed. Such text strings may also be found within VALUE strings, and they will be substituted as appropriate.

To check current configuration settings, use the lsconf utility, or login to the Admin web interface.

Metadata sources

METAMOD is able to handle a large range of metadata frameworks. For metadata generated through the UPLOAD module (by parsing netCDF files), METAMOD has defined its own XML format, called MM2. This format has a similar structure as Dublin core; it is a flat structure with freely selected metadata keywords. For each keyword one or more values may be found. (Note: This is currently being superceded by a new format named MMD which is currently under implementation.)

Other metadata frameworks, like DIF or ISO19115, are also accepted, and such frameworks will typically emerge when harvesting from other metadata providers through OAI-PMH. While such frameworks (DIF, ISO19115) are hierarchical in nature, a flattening of these structures takes place when they are imported to the SQL database and presented through the METAMOD search interface.

Configuration of the base application

The base application in a cluster of METAMOD applications has the special responsibility of setting up the static tables in the SQL metadata data base that govern which metadata are available for search in the WEB search interface. This is done through the staticdata/searchdata.xml file in the configuration directory.

This XML file contains metadata vocabularies that are imported into the SQL database, and used in the SEARCH module for setting up the interactive forms for web users searching the database.

Note that this file establish which categories of metadata will be available in the SQL data base. Each application will contain additional configuration that will taylor these possibilities to the needs of that application.

Configuration for the UPLOAD module

etc/conf_digest_nc.xml

This XML file describes the parsing of netCDF files in the UPLOAD module. Specifically how attributes and variable values in a netCDF file are translated into keyword - value pairs and stored into an MM2 XML file. The conf_digest_nc.xml file will contain rules regarding which metadata are required in the netCDF files. The app/example/etc/conf_digest_nc.xml file represents a well commented example of such a file that can be used as a starting point for a version tailored to specific needs.

etc/usererrors.conf

This file contain html templates that are used in error reports sent to data providers that have uploaded netCDF files using the UPLOAD module. Each template corresponds to an error condition defined in the etc/conf_digest_nc.xml file. An example file in the app/example/etc directory corresponds to the conf_digest_nc.xml in the same directory.

XSLT

Files for translating from foreign metadata formats. Currently not in use.

Stylesheets and other web configuration

METAMOD can be configured with custom texts and stylesheets. To modify the styles of the application add the following directories to your application configuration directory.

custom/templates

This directory contains the Template::Toolkit templates that you want to override in your configuration. It is generally never a good idea to override anything other than the custom.tt file.

custom/static/css

This directory contains the CSS files that you want to override in your configuration. It is generally never a good idea to override anything but the custom.css file in this folder.

custom/static/images

This folder contains the images that you use in your style configuration.

Overriding texts

To override texts in the application you use the custom.tt file. custom.tt is a file in Template::Toolkit format.

The way it is used is that it re-defines the default texts found in defaults.tt.

For instance the following would re-define the HTML used for the header of the application.

  [% # get a safe path to the header image that works in both Apache and outside of Apache
     SET header_image_url = c.uri_for('/static/images/logo.png');
     app.common.header_html = '<img src="' _ header_image_url _ '" />';
  %]

In the same way you can re-define any of the variables found in defaults.tt

Overriding the CSS

In METAMOD you can override any of the CSS styles in the application using custom.css since this stylesheet will be the last one loaded by the application. It is however wise to only modify properties such as background colors, foreground colors, borders and font size. Modifying the height, width, padding, margins, display type etc. of elements can lead to the application not displaying properly in different browsers. Also modifying these properties can break between different versions of METAMOD.

The style for any element can be modified, but only a few are usually needed. For an example of the common ones see app/example/custom/css/custom.css

Path to images

One of the most common customisations are adding a logo image to the header and the footer of the page. When adding images to the style it is important to get the path to the image right.

custom.tt

To get the path correct in the custom.tt file you can use the following helper function.

 SET image_url = c.uri_for('/static/images/<your image name here>');

This makes a variable image_url that contains the correct URL to the image file.

custom.css

To get the path correct in the custom.css file you can use the following path.

  url("../images/aboutheader.gif");

as in

  background-image: url("../images/aboutheader.gif");